LOWDOWN(1)

NAME
lowdown - simple markdown translator

SYNOPSIS
lowdown [-sv] [-D feature] [-d feature] [-E feature] [-e feature] [-o file] [-T mode] [file]
lowdown [-v] [-o file] [-X keyword] [file]

DESCRIPTION
The lowdown utility translates from markdown into HTML5 in XML mode (the default) or roff using the -ms or -man macro packages. If not given a file, or if file is “-”, lowdown reads from standard input. The results are written to standard output. Its arguments are as follows:

-D feature
    Disable the given feature (see Output features). See -E. You can specify this multiple times for different features.

-d feature
    Disable the given feature (see Input features). See -e. You can specify this multiple times for different features.

-E feature
    Enable the given feature (see Output features). See -D. You can specify this multiple times for different features.

-e feature
    Enable the given feature (see Input features). See -d. You can specify this multiple times for different features.

-o file
    Send output to file unless it's “-”, in which case fall back to the default of standard output.

-s  Standalone mode. This emits an HTML5 or roff document envelope surrounding the output. See the metadata key of Input features on providing information to the document envelope.

-T mode
    The output mode. This may be html for HTML5 output, ms for roff output using the classic (i.e., no-extension) -ms package and needing table support, or man for roff ouput using the classic -man package. A debugging output mode, tree, shows the parse tree of the input document.

-v  Verbose mode. Prints out warnings regarding Markdown syntax conformity and other warnings.

-X keyword
    Instead of converting the file, extract the given metadata keyword and exit. These will be escaped according to the output mode -T; for example, a title of “<foo>” in html mode will be extracted as “&lt;foo&gt;”. In either ms or man, a title of “.foo\bar” will be “\&.foo\ebar”.

For best results, use the -T html output, as it includes graphics and equations. The ms and man modes will elide graphics and equations.

By default, lowdown enables the autolink, fenced, footnotes, metadata, strike, super, and tables features. You can see a full list of features in Input features. The html-skiphtml, html-head-ids, nroff-groff, nroff-skiphtml, and smarty output features are enabled by default. See Output features for a full list.

  Input features
There are a number of Markdown (and Markdown extension) features supported by lowdown. These can be enabled with -e and disabled with -d. They are as follows:

autolink
    Autolink http, https, ftp, mailto, and relative links or link fragments.

fenced
    Allow for GFM fenced (language-specific) code blocks.

footnotes
    MMD style footnotes. This only supports one-liner footnotes on the same line as the footnote definition (not the in-line referent).

hilite
    Highlight. Do not use this option.

math
    Recognise single-dollar math mode.

mathexp
    Recognise double-dollar math mode. This only works if math has also been enabled.

metadata
    Accept MMD metadata. For the first paragraph to count as meta-data, the first line must have a colon in it. Otherwise it's considered a regular paragraph. Meta-data is escaped according to the output mode; and if the smarty flag is set, also smartypantsed.

nocodeind
    Do not indent code blocks.

nointem
    Disable emphasis with links.

sphd
    Require a space between hash marks and header.

strike
    Strikethrough support.

super
    Allow for super-scripts. This accepts foo^bar, which puts the parts following the caret until whitespace in superscripts; or foo^(bar), which puts only the parts in parenthesis.

tables
    Allow for GFM tables.

The parser also accepts link titles (quoted alongside the link address) and image dimensions (=WxH or =Wx). Both may also be specified, in any order. For example, ![alt](url title =23x24). These are fairly standard Markdown extensions.

If the metadata input feature is requested, the following metadata keys are used when in standalone (-s) mode:

date
    Document date in ISO-8601 YYYY-MM-DD or YYYY/MM/DD format. Overriden by rcsdate. Defaults to current date. Only used in -T man and -T ms mode.

rcsdate
    Document date in RCS date format. Overrides date. Defaults to current date. Only used in -T man and -T ms mode.

title
    Document title, defaulting to “Untitled article”. Used in all output modes.

author
    Document author. Multiple authors may be separated by more than one space (including newlines). Overrides rcsauthor. Used in all output modes.

rcsauthor
    Document author in RCS author format. Overriden by author. Used in all output modes.

css A CSS file included in the HTML5 document head. Multiple CSS files (in order) may be separated by more than one space (including newlines). Only used in -T html mode.

  Output features
lowdown allows for limited control over output features. These can be enabled with -E and disabled with -D. They are as follows, prefixed by “html” or “nroff” depending upon the output mode:

html-escape
    Leaves in-line HTML in its source form as if it were opaque text.

html-hardwrap
    Retain line-breaks within paragraphs.

html-skiphtml
    Do not render in-document HTML at all. Note that html-escape takes priority if both are specified. Text within HTML elements remains.

html-head-ids
    Give each header an identifier created by encoding its content.

nroff-numbered
    Use numbered sections. Only applies to the -T ms output mode.

nroff-groff
    Use GNU extensions (i.e., for groff(1)) when rendering output. You'll need to include -m pdfmark when invoking groff(1) for formatting links.

nroff-hardwrap
    Retain line-breaks within paragraphs.

nroff-skiphtml
    Do not render in-document HTML at all. Text within HTML elements remains.

smarty
    Don't use “smartypants” formatting. (Applies to all output modes.)

EXAMPLE
To emit a standalone HTML5 document from a file foo.md:

    lowdown -s foo.md > foo.html

To do the same but using groff(1) to format as a PS file:

    lowdown -s -Tms foo.md | \
      groff -t -ms -mpdfmark > foo.ps

Note the -t: since lowdown may emit tables, you'll need it. Moreover, the -m pdfmark is for the groff extensions. Alternatively, using only mandoc(1):

    lowdown -sT man foo.md | mandoc -Tps > foo.ps

If your document uses UTF-8 without the byte-order mark, you may need to specifically set the encoding in either formatter:

    lowdown -sT man foo.md | mandoc -Tps -Kutf-8 > foo.ps

    lowdown -sT ms foo.md | \
      groff -k -Dutf8 -t -ms -mpdfmark > foo.ps

To extract the HTML-escaped title from a file's metadata:

    lowdown -X title foo.md

EXIT STATUS

If the -X flag is used, lowdown exits with an error if the given keyword is not found.

STANDARDS
lowdown implements the classic Markdown specification along with some extensions. See Input features and Output features for a list.

AUTHORS
The lowdown utility was forked by Kristaps Dzonsons, kristaps@bsd.lv, from hoedown: https://github.com/hoedown/hoedown.