markdown_to_man()

Parse CommonMark/GFM and render as a groff man page.

Usage

Source

markdown_to_man(
    text,
    *,
    hardbreaks=False,
    smart=False,
    normalize=False,
    unsafe=False,
    footnotes=False,
    extensions=(),
    width=0,
    options=0
)

Produces groff-format output suitable for use with the man command or inclusion in manual page source files. Inline formatting maps to font switching requests (\f[B], \f[I], \f[CR]), paragraphs use .PP, and headings use .SH or .SS macros.

The output is a fragment and does not include a .TH title header. Wrap it in your own man page structure to produce a complete manual page.

Parameters

text: str

The Markdown string to parse and render. Must be a Python str.

hardbreaks: bool = False

Render soft line breaks as hard breaks (.br). By default, this is False.

smart: bool = False

Convert straight quotes to curly quotes, -- to en-dashes, --- to em-dashes, and ... to ellipses. By default, this is False.

normalize: bool = False

Consolidate adjacent text nodes in the parsed AST. By default, this is False.

unsafe: bool = False

Allow raw HTML to pass through. Since groff is the target format, raw HTML is typically irrelevant. By default, this is False.

footnotes: bool = False

Enable footnote syntax parsing. By default, this is False.

extensions: Sequence[str] = ()


A sequence of GFM extension names to enable. Valid names are "table", "strikethrough", "autolink", "tagfilter", and "tasklist".

width: int = 0

The column at which to wrap output lines. Set to 0 (the default) to disable line wrapping entirely.

options: int = 0

An integer bitmask of Options flags (e.g., Options.SMART | Options.UNSAFE). Merged via OR with any boolean keyword arguments set to True. Defaults to 0.

Keyword Arguments Vs. Options Flags

The boolean keyword arguments (smart, unsafe, hardbreaks, etc.) are convenience shortcuts for the most common Options flags. When both styles are provided, they are merged via OR. See markdown_to_html() for a detailed explanation.

Returns

str

The rendered groff man page string.

Examples

Render a paragraph with bold and italic:

from multimark import markdown_to_man

markdown_to_man("**bold** and *italic*")

'.PP\n\\f[B]bold\\f[] and \\f[I]italic\\f[]\n'

Render a heading:

markdown_to_man("## Options")

'.SS\nOptions\n'

Wrap at 72 columns:

long_paragraph = "This is a long paragraph of text. " * 10
print(markdown_to_man(long_paragraph, width=72))

.PP
This is a long paragraph of text. This is a long paragraph of text. This
is a long paragraph of text. This is a long paragraph of text. This is a
long paragraph of text. This is a long paragraph of text. This is a long
paragraph of text. This is a long paragraph of text. This is a long
paragraph of text. This is a long paragraph of text.