md2man - markdown to manpage
Formats tagged and indented paragraphs (see "document format" below).
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 pipeline.
Try converting this example Markdown file into a UNIX manual page:
md2man EXAMPLE.markdown > EXAMPLE.1 man -l EXAMPLE.1
At present, md2man does not translate the following Redcarpet node types:
It issues a warning when it encounters these instead. Patches are welcome!
gem install md2man
git clone git://github.com/sunaku/md2man cd md2man bundle install bundle exec md2man --help # run it directly bundle exec rake -T # packaging tasks
At the command line
Inside a Ruby script
Use the default renderer:
require 'md2man' your_roff_output = Md2Man::ENGINE.render(your_markdown_input)
Build your own renderer:
require 'md2man' engine = Redcarpet::Markdown.new(Md2Man::Engine, your_options_hash) your_roff_output = engine.render(your_markdown_input)
Define your own renderer:
require 'md2man' class YourManpageRenderer < Md2Man::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' 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)
md2man extends Markdown syntax in the following ways, as provisioned in the
Md2Man::Document module and defined in its derivative
Paragraphs whose lines are all uniformly indented by two spaces are considered to be "indented paragraphs". They are unindented accordingly before emission as
.IPin the roff output.
Paragraphs whose subsequent lines (all except the first) are uniformly indented by two spaces are considered to be a "tagged paragraphs". They are unindented accordingly before emission as
.TPin the roff output.
md2man extends Markdown semantics in the following ways:
- The first top-level heading (H1) found in the document is emitted as
.THin the roff(7) output to define the UNIX manual page's header and footer. Any subsequent top-level headings (H1) are treated as second-level (H2).
Pre-building man pages
Add the following lines to your gemspec:
s.files += Dir['man/man?/*.?'] s.add_development_dependency 'md2man', '~> 1.4'
Add the following line to your Rakefile:
You now have a
rake md2man task that builds manual pages from Markdown files
(with ".markdown", ".mkd", or ".md" extension) inside
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/man
Released under the ISC license. See the LICENSE file for details.