https://github.com/sunaku/md2man
📚 Converts markdown into UNIX manual pages
https://github.com/sunaku/md2man
browser-based manpages markdown-converter terminal-based
Last synced: 7 months ago
JSON representation
📚 Converts markdown into UNIX manual pages
- Host: GitHub
- URL: https://github.com/sunaku/md2man
- Owner: sunaku
- License: other
- Created: 2011-10-13T22:21:03.000Z (about 14 years ago)
- Default Branch: master
- Last Pushed: 2018-02-04T18:45:44.000Z (almost 8 years ago)
- Last Synced: 2025-04-12T19:48:14.086Z (7 months ago)
- Topics: browser-based, manpages, markdown-converter, terminal-based
- Language: Ruby
- Homepage: https://sunaku.github.io/md2man/man
- Size: 505 KB
- Stars: 373
- Watchers: 15
- Forks: 22
- Open Issues: 3
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE
Awesome Lists containing this project
- awesome-ruby-toolbox - md2man - Converts markdown into UNIX manpages and HTML webpages. (Documentation Tools / Documentation Generators)
- awesome-github-repos - sunaku/md2man - 📚 Converts markdown into UNIX manual pages (Ruby)
- Open-Source-Ruby-and-Rails-Apps - md2man - md2man is a Ruby library and a set of command-line programs that convert Markdown into UNIX manpages as well as HTML webpages using Redcarpet. 🔥 🚀 (Happy Exploring 🤘)
README
* Code:
* Docs:
* Bugs:
# md2man - markdown to manpage
md2man is a Ruby library and a set of command-line programs that convert
[Markdown] into UNIX manpages as well as HTML webpages using [Redcarpet].
## Features
* Formats indented, tagged, and normal paragraphs: described in md2man(5).
* Translates all HTML4 and XHTML1 entities into native [roff] equivalents.
* Supports markdown extensions such as [PHP Markdown Extra tables][tables].
* Usable from the command line as a filter in a UNIX command pipeline.
### Examples
Try converting
[this example Markdown file][example]
into
[a UNIX manual page][example-roff]:
```sh
md2man-roff EXAMPLE.markdown > EXAMPLE.1
```
You can view [the resulting UNIX manual page][example-roff] in your man(1)
viewer:
```sh
man -l EXAMPLE.1
```
Next, try converting
[the same example file][example]
into
[a HTML web page][example-html]:
```sh
md2man-html EXAMPLE.markdown > EXAMPLE.html
```
You can view [the resulting HTML manual page][example-html] in your web
browser:
```sh
firefox EXAMPLE.html
```
[example]: https://raw.github.com/sunaku/md2man/master/EXAMPLE.markdown
[example-roff]: https://github.com/sunaku/md2man/raw/gh-pages/man/man0/EXAMPLE
[example-html]: https://sunaku.github.io/md2man/man/man0/EXAMPLE.html
## Installation
```sh
gem install md2man
```
### Development
```sh
git clone https://github.com/sunaku/md2man
cd md2man
bundle install
bundle exec rake --tasks # packaging tasks
bundle exec md2man-roff --help # run it directly
bundle exec md2man-html --help # run it directly
```
## Usage
### For [roff] output
#### At the command line
See md2man-roff(1) manual:
```sh
md2man-roff --help
```
#### Inside a Ruby script
Use the default renderer:
```ruby
require 'md2man/roff/engine'
your_roff_output = Md2Man::Roff::ENGINE.render(your_markdown_input)
```
Build your own renderer:
```ruby
require 'md2man/roff/engine'
engine = Redcarpet::Markdown.new(Md2Man::Roff::Engine, your_options_hash)
your_roff_output = engine.render(your_markdown_input)
```
Define your own renderer:
```ruby
require 'md2man/roff/engine'
class YourManpageRenderer < Md2Man::Roff::Engine
# ... your stuff here ...
end
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
your_roff_output = engine.render(your_markdown_input)
```
Mix-in your own renderer:
```ruby
require 'md2man/roff'
class YourManpageRenderer < Redcarpet::Render::Base
include Md2Man::Roff
# ... your stuff here ...
end
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
your_roff_output = engine.render(your_markdown_input)
```
### For HTML output
#### At the command line
See md2man-html(1) manual:
```sh
md2man-html --help
```
#### Inside a Ruby script
Use the default renderer:
```ruby
require 'md2man/html/engine'
your_html_output = Md2Man::HTML::ENGINE.render(your_markdown_input)
```
Build your own renderer:
```ruby
require 'md2man/html/engine'
engine = Redcarpet::Markdown.new(Md2Man::HTML::Engine, your_options_hash)
your_html_output = engine.render(your_markdown_input)
```
Define your own renderer:
```ruby
require 'md2man/html/engine'
class YourManpageRenderer < Md2Man::HTML::Engine
# ... your stuff here ...
end
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
your_html_output = engine.render(your_markdown_input)
```
Mix-in your own renderer:
```ruby
require 'md2man/html'
class YourManpageRenderer < Redcarpet::Render::Base
include Md2Man::HTML
# ... your stuff here ...
end
engine = Redcarpet::Markdown.new(YourManpageRenderer, your_options_hash)
your_html_output = engine.render(your_markdown_input)
```
### Building manpages
#### At the command line
See md2man-rake(1) manual:
```sh
md2man-rake --help
```
#### Inside a Ruby script
Add this snippet to your gemspec file:
```ruby
s.files += Dir['man/man?/*.?'] # UNIX manpages
s.files += Dir['man/**/*.{html,css}'] # HTML manpages
s.add_development_dependency 'md2man', '~> 5.0'
```
Add this line to your Rakefile:
```ruby
require 'md2man/rakefile'
```
You now have a `rake md2man` task that builds manual pages from Markdown files
(with ".markdown", ".mkd", or ".md" extension) inside `man/man*/` directories.
There are also sub-tasks to build manual pages individually as [roff] or HTML.
If you're using Bundler, this task also hooks into Bundler's gem packaging
tasks and ensures that your manual pages are built for packaging into a gem:
```ruby
bundle exec rake build
gem spec pkg/*.gem | fgrep man/
```
## License
[Spare A Life]: https://sunaku.github.io/vegan-for-life.html
> Like my work? :+1: Please [spare a life] today as thanks!
:cow::pig::chicken::fish::speak_no_evil::v::revolving_hearts:
Copyright 2011 Suraj N. Kurapati
Released under the ISC license. See the LICENSE file for details.
[roff]: http://troff.org
[Redcarpet]: https://github.com/vmg/redcarpet
[Markdown]: http://daringfireball.net/projects/markdown/
[tables]: http://michelf.com/projects/php-markdown/extra/#table