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
Translate from lowdown(5) into diverse output formats. lowdown formats documents, lowdown -X keyword extracts metadata keywords, and lowdown-diff shows differences between documents as formatted output. 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, -Tlatex, -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, latex for LaTeX, 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 parse http, https, ftp, mailto, and relative links or link fragments.

--parse-no-cmark
    Do not parse with CommonMark constraints. This also disables using the first ordered list value instead of starting all lists at one.

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

--parse-no-deflists
    Do not parse PHP extra definition lists.

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

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

--parse-no-img-ext
    Do not parse PHP extra image extended attributes.

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

--parse-no-metadata
    Do not parse MMD metadata. For the first paragraph to count as metadata, the first line must have a colon in it. Otherwise it's considered a regular paragraph. Metadata is escaped according to the output mode.

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

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

--parse-no-tables
    Do not parse 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 PDF hyperlinks. If using -mspdf with groff(1), these will be further rendered as a table of contents and clickable links. Only applies to -Tms.

--nroff-no-numbered
    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.

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.

The -Tlatex output has only one option:

--latex-no-numbered
    Don't number sections (and subsections, etc.).

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

  Metadata
If not disabled with --parse-no-metadata, the following metadata keys are used when in standalone (-s) mode. The metadata keys are canonicalised in lowercase and without spaces.

affiliation
    Author affiliation (organisation or institution). Multiple affiliations may be separated by more than one space (including newlines). Used in all output modes but -Tman.

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

baseheaderlevel
    Document-wide header level offset number. This will increase the level of all headers. For example, having a base header level of 2 will cause all headers at level 1 to be <h3> in -Thtml. This may be between zero and five, inclusive.

copyright
    A document copyright (without the word “Copyright”), for example, “2017, Kristaps Dzonsons”. Used in -Tms and -Thtml.

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

date
    Document date in ISO-8601 YYYY-MM-DD format. Overriden by rcsdate. 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 -Thtml.

rcsauthor
    Document author in RCS author format. Overrides author. Used in all output modes.

rcsdate
    Document date in RCS date format. Overrides 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.

-Tlatex
    Simple LaTeX output. The following packages are used by lowdown: graphicx for images, inputenc (utf8) for UTF-8 input, fontend (T1) and textcomp for output glyphs, lmodern for Latin modern font, xcolor for the difference engine output, and hyperref for links.

-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 (PS and EPS suffix) images. Images are always block-formatted. Image dimensions and extended attributes are ignored, though images are downsized if larger than the current text width. 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.

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

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

-Tlatex
    When data has been removed, it is coloured red. When data has been inserted, it is coloured in green.

-Tterm
    Removed and inserted data have different background colours.

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:

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

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

If the file has PS or EPS images and is being processed by groff(1), the images are not converted and the file needs to be manually converted from PS.

    lowdown -sTms foo.md | groff -tki -mspdf -Kutf8 > foo.ps
    ps2dpdf foo.ps

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. It has been considerably modified since.