MDMAN(1) NAME mdman - Converts markdown to a man page SYNOPSIS mdman [options] -t type -o outdir sources... DESCRIPTION Converts a markdown file to a man page. The source file is first processed as a handlebars <https://handlebarsjs.com/> template. Then, it is processed as markdown into the target format. This supports different output formats, such as troff or plain text. Every man page should start with a level-1 header with the man name and section, such as # mdman(1). The handlebars template has several special tags to assist with generating the man page: o Every block of command-line options must be wrapped between {{#options}} and {{/options}} tags. This tells the processor where the options start and end. o Each option must be expressed with a {{#option}} block. The parameters to the the block are a sequence of strings indicating the option. For example, {{#option "`-p` _spec_..." "`--package` _spec_..."}} is an option that has two different forms. The text within the string is processed as markdown. It is recommended to use formatting similar to this example. The content of the {{#option}} block should contain a detailed description of the option. Use the {{/option}} tag to end the option block. o References to other man pages should use the {{man name section}} expression. For example, {{man "mdman" 1}} will generate a reference to the mdman(1) man page. For non-troff output, the --man option will tell mdman how to create links to the man page. If there is no matching --man option, then it links to a file named name.md in the same directory. o Variables can be set with {{*set name="value"}}. These variables can then be referenced with {{name}} expressions. o Partial templates should be placed in a directory named includes next to the source file. Templates can be included with an expression like {{> template-name}}. o Other helpers include: o {{lower value}} Converts the given value to lowercase. OPTIONS -t type Specifies the output type. The following output types are supported: o man — A troff-style man page. Outputs with a numbered extension (like .1) matching the man page section. o md — A markdown file, after all handlebars processing has been finished. Outputs with the .md extension. o txt — A text file, rendered for situations where a man page viewer isn't available. Outputs with the .txt extension. -o outdir Specifies the directory where to save the output. --url base_url Specifies a base URL to use for relative URLs within the document. Any relative URL will be joined with this URL. --man name:section=url Specifies a URL to use for the given man page. When the {{man name section}} expression is used, the given URL will be inserted as a link. This may be specified multiple times. If a man page reference does not have a matching --man entry, then a relative link to a file named name.md will be used. sources... The source input filename, may be specified multiple times. EXAMPLES 1. Convert the given documents to man pages: mdman -t man -o doc doc/mdman.md