LOWDOWN(1) General Commands Manual LOWDOWN(1)

NAME

lowdown, lowdown-diffsimple 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
Assume input conforms to the CommonMark specification. 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 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.
 
 
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

The lowdown and lowdown-diff utilities exit 0 on success, and >0 if an error occurs.
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, and Amelie Marian, Detecting Changes in XML Documents, https://www.cs.rutgers.edu/~amelie/papers/2002/diff.pdf, 2002.
Wu Sun, Manber Udi, and Myers Gene, An O(NP) sequence comparison algorithm, Issue 6, Information Processing Letters, Volume 35, 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.
June 16, 2018 OpenBSD 6.3