Kramdown-man: A Kramdown convert for converting Markdown files into man pages

Description

A Kramdown convert for converting Markdown files into man pages.

Features

Converts markdown to roff:
- Supports codespans, emphasis, and strong fonts.
- Supports normal and tagged paragraphs.
- Supports codeblocks and blockquotes.
- Supports bullet, numbered, and definition lists.
- Supports multi-paragraph list items and blockquotes.
- Supports converting [foo-bar](foo-bar.1.md) and [bash](man:bash(1))
  links into SEE ALSO man page references.
Provides Rake task for converting man/*.md into man pages.
Uses the pure-Ruby Kramdown markdown parser.
Supports Ruby 3.x, JRuby, and TruffleRuby.

Synopsis

usage: kramdown-man [options] MARKDOWN_FILE
    -o, --output FILE                Write the man page output to the file
    -V, --version                    Print the version
    -h, --help                       Print the help output

Examples:
    kramdown-man -o man/myprogram.1 man/myprogram.1.md
    kramdown-man man/myprogram.1.md

Render a man page from markdown:

kramdown-man -o man/myprogram.1 man/myprogram.1.md

Preview the rendered man page:

kramdown-man man/myprogram.1.md

Examples

Render a man page from a markdown file:

require 'kramdown/man'

doc = Kramdown::Document.new(File.read('man/kramdown-man.1.md'))
File.write('man/kramdown-man.1',doc.to_man)

system 'man', 'man/kramdown-man.1'

Define a man and file tasks which render all *.md files within the
man/ directory:

require 'kramdown/man/task'
Kramdown::Man::Task.new

Syntax

Code

code

Emphasis

emphasis

Strong

strong

Paragraph

Normal paragraph.

Usage String

`command` [`--foo`] **FILE**

command [--foo] FILE

Argument Definitions

*ARG*
: Description here.

ARG
: Description here.

Option Definitions

`-o`, `--option` *VALUE*
: Description here.

-o, --option VALUE
: Description here.

Links

[website](http://example.com/)

website

Man Pages

Link to other man pages in a project:

[kramdown-man](kramdown-man.1.md)

kramdown-man

Link to other system man page:

bash

Note: only works on firefox on Linux.

Email Addresses

Email bob@example.com

Lists

one
two
three

Numbered Lists

one
two
three

Definition Lists

ex·am·ple
: a thing characteristic of its kind or illustrating a general rule.

: a person or thing regarded in terms of their fitness to be imitated or the likelihood of their being imitated.

ex·am·ple
: a thing characteristic of its kind or illustrating a general rule.

: a person or thing regarded in terms of their fitness to be imitated or the likelihood of their being imitated.

Blockquotes

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.

–Antoine de Saint-Exupéry

Code Blocks

return 0; }

Source code:

Requirements

kramdown ~> 2.0

Install

Alternatives

Copyright

See {file:LICENSE.txt} for details.