LOWDOWN(1)

NAME
lowdown, lowdown-diff - simple markdown translator

SYNOPSIS
lowdown [in_opts] [out_opts] [-s] [-o file] [-T mode] [file]
lowdown [in_opts] [out_opts] [-o file] [-T mode] -X keyword [file]
lowdown-diff [in_opts] [out_opts] [-s] [-o file] [-T mode] oldfile [file]

DESCRIPTION
These utilities translate from lowdown(5) into a variety of output formats. lowdown formats documents, lowdown -X keyword extracts metadata keywords, and lowdown-diff shows differences between documents as formatted output. The results are written to standard output.

The arguments are as follows:

-s  Standalone mode. This emits a document envelope surrounding the output by drawing from document metadata. See Metadata on providing information to the document envelope. This only applies to -Thtml, -Tms, and -Tman.

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

-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, term for ANSI-compatible UTF-8 terminal output, man for roff output using the classic -man package, tree, to show the parse tree of the input document, and null to parse the document but do no rendering. See Output modes.

-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>” with -Thtml will be extracted as “&lt;foo&gt;”. Metadata is not rendered for -Ttree or -Tnull.

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.

The following are options for input parsing. These affect the parse tree passed to all outputs.

--parse-hilite
    Enable highlight span support. This are disabled by default because it may be erroneously interpreted as section headers.

--parse-math
    Recognise mathematics equations.

--parse-maxdepth=depth
    The maximum depth of nested elements. This defaults to 128, which is probably more than enough for any real-world document. If the maximum is hit, the system exits as if memory were exhausted. Set to zero for no maximum.

--parse-no-autolink
    Do not autolink http, https, ftp, mailto, and relative links or link fragments.

--parse-no-cmark
    Do not 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.

--parse-no-codeind
    Do not parse indented content as code blocks.

--parse-no-fenced
    Do not allow for GFM fenced (language-specific) code blocks.

--parse-no-footnotes
    Do not allow MMD style footnotes.

--parse-no-intraemph
    Do not allow emphasis within words and links.

--parse-no-metadata
    Do not allow 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.

--parse-no-strike
    Do not allow strikethroughs.

--parse-no-super
    Do not allow super-scripts.

--parse-no-tables
    Do not allow GFM tables.

There are many output options. The following are shared by all output modes:

--out-standalone
    Alias for -s.

--out-no-smarty
    Do not use the smart typography filter. By default, certain character sequences are translated into output-specific glyphs.

What follows are per-output options. For HTML with -Thtml, these are as follows:

--html-hardwrap
    Hard-wrap paragraph content by outputting line breaks where applicable.

--html-no-escapehtml
    If --html-no-skiphtml has been specified, this causes embedded HTML not to be escaped, and is instead output verbatim. This has no effect if --html-no-skiphtml has not been specified.

--html-no-head-ids
    Do not output id attributes for headers.

--html-no-num-ent
    Don't normalise HTML entities (when possible) as numeric ones and instead use the entities as given on input.

--html-no-owasp
    Don't follow the OWASP recommendations for escaping text, and do only the minimal escaping to make sure that regular content isn't interpreted as HTML.

--html-no-skiphtml
    Output embedded HTML. By default, embedded HTML is not output at all. See --html-no-escapehtml.

For both -Tman and -Tms, the following apply:

--nroff-hardwrap
    Hard-wrap paragraph content by outputting line breaks where applicable.

--nroff-no-groff
    Don't use groff(1) style section headings and don't output PDF hyper-links. See --nroff-no-numbered. Only applies to -Tms.

--nroff-no-numbered
    If --nroff-no-groff is set, don't output numbered headings. Only applies to -Tms.

--nroff-no-skiphtml
    Output embedded HTML. This usually doesn't make sense because the HTML won't be interpreted by the output reader. By default, HTML is omitted.

Lastly, the -Tterm output has the following:

--term-columns=columns
    The number of columns in the screen. Useful for when running in a pipe. Defaults to what the terminal reports or 72 if in a pipe.

--term-hmargin=margin
    The number of left margin spaces. Truncated to the number of columns. Defaults to zero.

--term-shortlinks
    Shorten URLs to only the domain name and final path. This is useful for reading when links aren't clickable. Applies to images, autolinks, and real links.

--term-vmargin=margin
    The number of top and bottom margin newlines. Defaults to zero.

--term-width=width
    Set the soft limit on the number of characters per line. This may be exceeded by literal text. The default (or if zero) is the number of terminal columns or 80 at most.

  Metadata
If not disabled with --parse-no-metadata, the following metadata keys are used when in standalone (-s) mode:

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.

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

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.

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.

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.

rcsauthor
    Document author in RCS author format. Overriden by author. 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.

  Output modes
A detailed description of the output modes follows.

-Thtml
    HTML5 output with UTF-8 encoding. All features of lowdown(5) are supported.

-Tman
    The man macro package suitable for reading by groff(1), mandoc(1), or traditional troff(1). Does not support equations and images. Table support is provided by tbl(1). Since UTF-8 may be passed as input values, preconv(1) may need to be used.

-Tms
    The ms macro package suitable for reading by groff(1) or traditional troff(1). Does not support equations and limited image support for encapsulated postscript (eps, eps suffix) images. Table support is provided by tbl(1). Since UTF-8 may be passed as input values, preconv(1) may need to be used.

-Tterm
    ANSI-escaped UTF-8 output suitable for reading on the terminal. Images and equations not supported.

-Ttree
    Debugging ouptut: not for general use.

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

-Tterm
    Removed and inserted data have different background colours.

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

EXIT STATUS

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

EXAMPLES
To view a Markdown file on an ANSI-compatible, UTF-8 terminal:

    lowdown -Tterm foo.md | less -R

If preferred, the terminal may also be used with groff(1) or mandoc(1) rendering:

    lowdown -sTms foo.md | groff -tki -mspdf -Kutf8 -Tutf8 | less -R
    lowdown -sTman foo.md | mandoc | less

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

    lowdown -s foo.md > foo.html

To use groff(1) or mandoc(1) to format as a PS file:

    lowdown -sTms foo.md | groff -tki -mspdf -Kutf8 > foo.ps
    lowdown -sTman foo.md | mandoc -Tps > foo.ps

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

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

Both groff(1) and mandoc(1) support the -Tpdf arguments for PDF output. The former also has pdfroff(1).

UTF-8 support for PDF or PS is limited to groff(1) installations with the appropriate fonts, such as the Unicode Times font. This and other Unicode fonts are not always installed by default. They may be found, for PDF output, in the devpdf set of the groff(1) font directory and are prefixed with ‘U’.

    lowdown -sTms foo.md | \
      groff -Tpdf -tki -mspdf -Kutf8 -FU-T > foo.pdf

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

    lowdown -X title foo.md

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.

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