- Code: https://github.com/sunaku/md2man
- Docs: https://sunaku.github.io/md2man/man
- Bugs: https://github.com/sunaku/md2man/issues
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.
-
Usable from the command line as a filter in a UNIX command pipeline.
Examples
Try converting this example Markdown file into a UNIX manual page:
md2man-roff EXAMPLE.markdown > EXAMPLE.1You can view the resulting UNIX manual page in your man(1) viewer:
man -l EXAMPLE.1
Next, try converting the same example file into a HTML web page:
md2man-html EXAMPLE.markdown > EXAMPLE.htmlYou can view the resulting HTML manual page in your web browser:
firefox EXAMPLE.htmlInstallation
gem install md2manDevelopment
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 directlyUsage
For roff output
At the command line
See md2man-roff(1) manual:
md2man-roff --helpInside a Ruby script
Use the default renderer:
require 'md2man/roff/engine'
your_roff_output = Md2Man::Roff::ENGINE.render(your_markdown_input)Build your own renderer:
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:
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:
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:
md2man-html --helpInside a Ruby script
Use the default renderer:
require 'md2man/html/engine'
your_html_output = Md2Man::HTML::ENGINE.render(your_markdown_input)Build your own renderer:
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:
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:
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:
md2man-rake --helpInside a Ruby script
Add this snippet to your gemspec file:
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:
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:
bundle exec rake build
gem spec pkg/*.gem | fgrep man/License
Like my work? 👍 Please spare a life today as thanks! :cow::pig::chicken::fish::speak_no_evil::v::revolving_hearts:
Copyright 2011 Suraj N. Kurapati https://github.com/sunaku
Released under the ISC license. See the LICENSE file for details.