LOWDOWN(1)

NAME
lowdown, lowdown-diff - simple markdown translator

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

DESCRIPTION
The lowdown and lowdown-diff utilities translate from markdown into HTML5 in XML mode (the default) or roff using the -ms or -man macro packages. lowdown formats a document, lowdown -X keyword extracts metadata keyword, and lowdown-diff shows differences between documents. See lowdown(5) for a reference of the accepted syntax. The results are written to standard output.

The 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 output 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”.

oldfile
    Input Markdown document used as the basis for comparison with lowdown-diff.

file
    Input Markdown document. If not given or if file is “-”, read from standard input.

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

  Input features
There are a number of Markdown (and Markdown extension) features supported by lowdown and lowdown-diff. These can be enabled with -e and disabled with -d. By default, lowdown and lowdown-diff enable the autolink, fenced, footnotes, metadata, strike, super, commonmark, and tables features. A full list is as follows:

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

commonmark
    Tighten input parsing to the CommonMark specification. This also uses the first ordered list value instead of starting all lists at one. In most cases, this is simply less laxist than the original Markdown. This feature is experimental.

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 mathematics equations.

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.

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:

copyright
    A document copyright (without the word “Copyright”), for example, “2017, Kristaps Dzonsons”. This is currently only used in the -T ms output mode.

date
    Document date in ISO-8601 YYYY-MM-DD or YYYY/MM/DD format. Overriden by rcsdate. Defaults to current date. Used in all output modes.

rcsdate
    Document date in RCS date format. Overrides date. Defaults to current date. Used in all output modes.

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

affiliation
    Author affiliation (organisation or institution). Multiple affiliations may be separated by more than one space (including newlines). 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.

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

  Output features
lowdown and lowdown-diff allow for limited control over output features. These can be enabled with -E and disabled with -D. The html-skiphtml, html-head-ids, nroff-groff, nroff-skiphtml, and smarty output features are enabled by default. A full list is 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. This option is retained for compatibility—don't use it. Instead, use proper escaping of newlines.

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 -Tms output mode. If this and nroff-groff are provided, the document outline will be exported.

nroff-groff
    Use GNU extensions (i.e., for groff(1)) when rendering output. Only applies to the -Tms output mode. You'll need to include -mpdfmark when invoking groff(1) for formatting links, -t for the table extension, and -mpspic (not necessary to specify) for images. Note that pspic will only work with -Tps output or via pdfroff(1) as noted in the EXAMPLES.

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.)

  Diffing
If invoked as lowdown-diff, the traditional Markdown output is augmented with features for viewing file differences. These depend upon the output mode.

-Thtml
    When data has been removed from the old document, it is marked up with the <del> element. When data has been inserted into the new document, <ins> is used instead.

-Tman, -Tms
    When data has been removed, it is coloured red. When data has been inserted, it is coloured in green. In either case, your formatter must support colours or the texts will be freely intermingled.
The algorithm used for diffing derives from “Detecting Changes in XML Documents” (2002). The algorithm for computing the shortest edit script between text nodes is “O(NP) sequence comparison algorithm” (1990).

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 -mspdf -k -Kutf8 > foo.ps

The arguments to groff(1) dictate input type (-mspdf), input encoding (-k, -Kutf8), and extensions (-t). Note that -mspdf is used instead of -ms and -mpdfmark to allow for the “XN” macro, which generates a table of contents for the output PS or PDF. This macro is otherwise ignored.

Alternatively, using only mandoc(1):

    lowdown -sTman foo.md | mandoc -Tps > foo.ps

To have PDF output, use the pdfroff(1) utility instead of the -Tpdf output to groff(1), as it manages image conversion. The -i flag notes standard input; other flags are passed to groff(1).

    lowdown -sTms foo.md | \
      pdfroff -i -t -mspdf -k -Kutf8 > foo.pdf

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

    lowdown -X title foo.md

Lastly, using a traditional troff(1), use the following:

    lowdown -Dnroff-groff -sTms foo.md | \
      tbl | troff -Tps -ms -mpdfmark > foo.ps

EXIT STATUS

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

SEE ALSO
lowdown(3), lowdown(5) Gregory Cobena, Serge Abiteboul, Amelie Marian, 2002, Detecting Changes in XML Documents, https://www.cs.rutgers.edu/~amelie/papers/2002/diff.pdf. Wu Sun, Manber Udi, Myers Gene, An O(NP) sequence comparison algorithm, Information Processing Letters, Volume 35, Issue 6, 1990.

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

AUTHORS
The lowdown and lowdown-diff utilities were forked by Kristaps Dzonsons, kristaps@bsd.lv, from hoedown: https://github.com/hoedown/hoedown.