LOWDOWN(1) User Commands LOWDOWN(1)

NAME

lowdown - simple markdown translator

SYNOPSIS

lowdown [input_options] [output_options] [-Ls] [-M metadata]
[-m metadata] [-o file] [-t mode] [-X keyword] [file]

DESCRIPTION

Translate from lowdown(5) into diverse output formats. Results are
written to standard output.

The short arguments are as follows:

-L Lists metadata keys, one key per line. The -t mode is ignored.
Metadata is automatically enabled. Unsets -X.

-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 applies
to -tgemini, -thtml, -tlatex, -tms, -tman, and -tfodt.

-M metadata
Provide a single metadata key-value pair. This may be in the
syntax specified by lowdown(5) or as pairs separated by an
equal sign, depending upon which character (a colon or equal
sign) comes first. Exits with an error if given neither colon
nor equal sign. May be invoked multiple times for each pair.
This overrides -m and what's parsed from the document.

-m metadata
Like -M, but is overridden by what's parsed the document, then
-M.

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

-t mode, -T mode
The output mode. This may be html for HTML5 output, latex for
LaTeX, gemini for the Gemini "gemtext" format, 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. The
-T mode form is retained for backward compatibility.

-X keyword
Output the metadata value of keyword or an empty string if not
found. The -t mode is ignored. Metadata is automatically
enabled. Unsets -L.

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

The following are long 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-codeindent
Do not parse indented content as code blocks.

--parse-no-callouts
Do not parse GFM/MDN callouts ("admonitions").

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

--parse-no-ext-attrs
Do not parse PHP extra extended attributes.

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

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

--parse-no-img-ext
Deprecated. See --parse-no-ext-attrs.

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

--parse-no-mantitle
Do not parse manpage title, section, source, and volume from
Pandoc title metadata. Manpages titles are indicated by a
title then an open parenthesis, digit followed by optional
characters, then a closed parenthesis.

--parse-no-metadata
Do not parse metadata. This does not affect metadata given on
-m or -M.

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

--parse-no-super
Do not parse super-scripts or sub-scripts at all.

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

--parse-no-tasklists
Do not parse GFM task lists.

--parse-super-short
If super-script parsing is enabled, use the traditional non-GFM
"short" syntax.

There are many output long 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.

--template template
When producing standalone -s output, use a template file. See
Templates. Currently only for -tgemini, -thtml, -tlatex,
-tman, and -tms.

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

--html-callout-mdn, --html-callout-gfm
Output either or both MDN or GFM callout syntaxes.

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

--html-titleblock
If any were parsed, format the title information (title,
author, date) into a header element appearing first in the
document.

For both -tman and -tms (unless as noted), the following apply:

--nroff-code-font=fonts
Override the default constant-width fonts with a tuple of
regular, bold, italic, and bold-italic variants in that order.
For example, B,B,BI,BI uses bold ("B") instead of a constant-
width. Not specifying a font will use the default, as will
specifying a zero-length font name. Aliases none, bold, and
code set no special fonts, bold, and the default constant-
width.

--nroff-endnotes
Delay printing of footnotes until the end of the document.
Only applies to -tms, as -tman only supports endnotes.

--nroff-no-groff
Deprecated alias for --nroff-traditional.

--nroff-no-numbered
Don't output numbered headings (.NH NN). 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.

--nroff-nolinks
Don't show URLs for images and links (autolinks are still
shown). (Link content is still shown.) Overrides
--nroff-shortlinks for images and links. Only applies when
--nroff-traditional is specified.

--nroff-shortlinks
Shorten URLs for images, links, and autolinks to only the
domain name and final path. Only applies when
--nroff-traditional is specified.

--nroff-traditional
Don't use hyperlink macros (.pdfhref, .UR, .MT), multi-page
tables (.TS H, .TH), Unicode sequence syntax (\[uNNNN]),
example block macros (.EX), modern section headings (.NH NN,
.SH NN, .pdfhref O NN), or intra-document links (.pdfhref L).
The output is compatible with traditional troff(1).

The -tterm output has the following:

--term-all-metadata
If -s is specified, output all metadata instead of just the
title, author, and date.

--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-no-ansi
Don't show ANSI styles at all. This implies --term-no-colour.

--term-no-colour
Don't show ANSI colours. This will still decorate text with
underlines, bolds, and italics, but not emit any colour codes.

--term-nolinks
Don't show URLs for images and links (autolinks are still
shown). (Link content is still shown.) Overrides
--term-shortlinks for images and links.

--term-shortlinks
Shorten URLs for images, links, and autolinks to only the
domain name and final path.

--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 -tgemini output has several flags that control the placement of
links. By default, links (images, autolinks, and links) are queued
when specified in-line then emitted in a block sequence after the
nearest block element.

--gemini-link-end
Emit the queue of links at the end of the document instead of
after the nearest block element.

--gemini-link-inline
Render all links within the flow of text. This will cause
breakage when nested links, such as images within links, links
in blockquotes, etc. It should not be used unless in carefully
crafted documents.

--gemini-link-noref
Do not format link labels. Takes precedence over
--gemini-link-roman.

--gemini-link-roman
When formatting link labels, use lower-case Roman numerals
instead of the default lower-case hexavigesimal (i.e., "a",
"b", ..., "aa", "ab", ...).

--gemini-metadata
Print metadata as the canonicalised key followed by a colon
then the value, each on one line (newlines replaced by spaces).
The metadata block is terminated by a double newline. If there
is no metadata, this does nothing.

The -tlatex output has the following options:

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

The -tfodt output has the following options:

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

--odt-style=file
Specify an OpenDocument style file, which must consist of at
least <office:font-face-decls>, <office:scripts>, and
<office:styles> XML elements in the root of the document. This
is not syntax-checked in any way.

Output modes

The output media is specified by -t, which defaults to -thtml.

-tfodt "Flat" OpenDocument output. Automatic styles (those
conditional upon document state) are generated with output.
Classes specified by PHP extended attributes are not checked
for existence.

-tgemini
Gemini "gemtext" format.

-thtml HTML5 output with UTF-8 encoding.

-tlatex
Simple LaTeX output. The following packages are required:
amsmath and amssymb for maths, 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), Heirloom troff, 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 output: not for general use.

Standalone documents

When -s is specified, additional content may be added to output:

-tfodt Envelope <office:document> and prologue
<office:automatic-styles>, <office:master-styles>, and
<office:body>.

-thtml HTML5 doctype declaration followed by envelope <html> with
optional language, then <head>. In order, the <head> consists
of charset and viewport <meta> elements; optional <meta>
elements from metadata affiliation (creator), author,
copyright, and date; optional CSS sources from metadata;
optional JavaScript sources from metadata; the possibly-empty
<title>; then optional arbitrary content from metadata HTML
header.

-tlatex
Prologue documentclass and usepackage statements, optional
arbitrary content from metadata LaTeX header, then surrounding
begin{document} statements.

-tman, -tms
Prologue macros.

-tterm Prologue lines.

If parsed from the document or as given by -m or -M, the following
metadata keys are used by additional content. The metadata keys are
canonicalised in lowercase and without spaces.

Metadata values should not be encoded in their output format, e.g.,
"css: foo&bar". The renderer will perform any necessary output
encoding.

affiliation
Author affiliation (organisation or institution). Multiple
affiliations may be separated by two or more spaces (including
newlines). Used in -thtml, -tlatex, and -tms.

author Document author. Multiple authors may be separated by two or
more spaces (including newlines). Overridden by rcsauthor.
Used in -tfodt, -thtml, -tlatex, -tms, and -tterm.

baseheaderlevel
Added to each header level. Deprecated in favour of
shiftheadinglevelby.

copyright
A document copyright (without the word "Copyright"), for
example, "2017, Kristaps Dzonsons". Used in -tms and -thtml.

css A CSS file output in the HTML document head as a <link
rel="stylesheet" href="..." /> statement. Multiple CSS files
(in order) may be separated by two or more spaces (including
newlines) and are output in the given order. Only used in
-thtml.

date Document date in ISO-8601 YYYY-MM-DD format. Overridden by
rcsdate. Used in -tfodt, -thtml, -tlatex, -tman, -tms, and
-tterm.

htmlheader
Arbitrary HTML content output in the HTML document head
immediately prior to closing the head element. Only used in
-thtml and with -s. This metadata is not processed: it's
passed unchanged into the output.

javascript
A JavaScript file output in the HTML document head as a <script
src="..."></script> statement. Multiple script files (in
order) may be separated by two or more spaces (including
newlines) and are output in the given order. Only used in
-thtml.

lang Document language in RFC 5646 format. Only used in -thtml.

latexheader
Arbitrary LaTeX content output in the document prologue
immediately prior to the begin{document}. Only used in -tlatex
and with -s. This metadata is not processed: it's passed
unchanged into the output.

manheader
Arbitrary roff content output immediately prior to the .TH
macro. Only used in -tman and with -s. This metadata is not
processed: it's passed unchanged into the output.

msheader
Arbitrary roff content output immediately prior to the .TL
macro. Only used in -tms and with -s. This metadata is not
processed: it's passed unchanged into the output.

rcsauthor
Like author, but in RCS author format. Overrides author.

rcsdate
Like date, but in RCS date format. Overrides date.

section
Man page section, defaulting to "7". Only used in -tman.

shiftheadinglevelby
Shift all headers by the given number. For example, a value of
1 causes headers originally at level 1 ("<h1>") to be level 2
("<h2>"), while a value of -1 moves level 2 to 1. Levels will
not move to less than 1. Takes precedence over
baseheaderlevel. If unset or not a valid number, defaults to
zero. Used in -tfodt, -thtml, -tlatex, -tman, and -tms.

source Man page source (organisation providing the manual). Only used
in -tman.

volume Man page volume (describes the manual page section). Only used
in -tman.

title Document title. Used in -tfodt, -thtml, -tlatex, -tman, -tms,
and -tterm.

Metadata values are parsed and may be used as variables in markdown
documents regardless of whether -s is specified or not.

Default values, such "7" for the section, are not set as metadata
values, and will not appear if the metadata key is used as a variable.

Templates

Some output modes accept a template (--template) to customise
standalone (-s) output. Parsed input content is filled into templates
through control statements that support conditionals, loops, and
variable transformation sequences.

Control statements are delimited as $statement$ or ${statement}.
Arbitrary white-space may surround the case-insensitive statement
between matching delimiters. Statements without a closing delimiter
are considered opaque text.

The following statements are available:

$$, ${}
Output a literal $. This may contain arbitrary white-space.

$ifdef(expression)$
Conditional statement. There may not be any white-space
between the ifdef and the opening parenthesis. Begins a block
that is ended by a else, endif, or the end of file. Its
contents are output only if expression evaluates to a non-empty
string.

$else$ Begins a block that is ended by a endif or end of file. Its
contents are output only if the condition of a preceding ifdef
evaluates to an empty string. An else without a preceding
ifdef is not output.

$endif$
Closes a block begin with ifdef or else. If not preceded by
one of those statements, is silently ignored.

$for(expression)$
Looping statement. There may not be any white-space between
the for and the opening parenthesis. Begins a block that is
ended by an endfor or the end of file. Block contents contents
are repeatedly output for each list item evaluated from
expression. The anaphoric keyword this may be used to access
the current loop expression within the block.

$expression$
Replaced by the result of evaluating a template expression.

If a control statement ends with two consecutive hyphens before the
closing delimiter, input is consumed up to and including the next
newline or until end of file. This allows for line-sensitive output
media to use control statements without superfluous blank lines.

Expressions consist of initial[([arg]*)]?[.transform[([arg]*)]?]*, or
an initial value accepting optional arguments followed by an optional
series of transforms accepting optional arguments. If an argument list
is empty or not provided, it evaluates to an empty list.

The initial value is one of the following:

and(expression[,expression]*)
A non-empty list containing the value true if all expressions
evaluate to non-empty lists, otherwise an empty list. An empty
expression evaluates to an empty list.

canonicalised metadata key
The value for the given metadata key, if found, otherwise an
empty list.

body The parsed input document body.

meta(val)
Evaluate val as a canonicalised metadata key, even if it's a
keyword like body or endif.

not(expression)
A non-empty list containing the value true if the expression
evaluates as an empty list, otherwise an empty list.

or(expression[,expression]*)
A non-empty list containing the value true if one expression
evaluates to non-empty lists, otherwise an empty list. An
empty expression evaluates to an empty list.

this The value of a current loop context or an empty list.

If a metadata key is not specified in the input, or if the anaphoric
this has not initialised by a looping context, the initial value
evaluates to an empty list. Otherwise, the value is a singleton list.

If transforms are invalid, they will transform into an empty list.

The following transformations are available:

escapegemini, escapegeminiline
Escape list items for gemini (-tgemini), either for multiple
lines or compressed to a single line.

escapehtml, escapehtmlattr, escapehtmlurl
Escape list items for HTML (-thtml) body content, attributes,
and URL attributes, respectively.

escapelatex
Escape list items for LaTeX (-tlatex) body content.

escaperoff, escaperoffline
Escape list items for roff (-tms, -tman), either for multiple
lines or compressed to a single line.

join Join a list into a singleton list using two spaces as a join
delimiter.

lowercase
Lowercase all list items.

split Split list items on sequences of two or more white-space tokens
(space, newline, tab). This is usually invoked on a singleton,
but may be repeatedly invoked on a pre-split list. Invokes
trim prior to the first split. The resulting list has no items
that are only white-space.

trim Trim white-space from the beginning and end of all list items.
If an item has no non-white-space, it is discarded.

uppercase
Uppercase all list items.

ENVIRONMENT

NO_COLOR
Do not emit colours when in -tterm mode. Synonym for
NO_COLOUR. Same as --term-nocolour.

FILES

share/html/default.html
The default template used if --template is not provided to
-thtml.

share/latex/default.latex
The default template used if --template is not provided to
-tlatex.

share/man/default.man
The default template used if --template is not provided to
-tman.

share/man/default.ms
The default template used if --template is not provided to
-tms.

share/odt/styles.xml
Default styles used when generating standalone -tfodt
documents. Template for --odt-style styles.

EXIT STATUS

The lowdown utility exits 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.

EXAMPLES

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

lowdown -tterm foo.md | less -R

The terminal may also be used with groff(1) or mandoc(1) rendering:

lowdown -stms foo.md | groff -itk -mspdf -Tutf8 | less -R
lowdown -stman foo.md | groff -itk -man -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 -itk -mspdf > foo.ps
lowdown -stman foo.md | mandoc -Tps > foo.ps

Or with LaTeX:

lowdown -stlatex foo.md > foo.latex
pslatex foo.latex

PDF generation follows similar logic:

lowdown -stms foo.md | pdfroff -itk -mspdf > foo.pdf
lowdown -stman foo.md | mandoc -Tpdf > foo.pdf
lowdown -stlatex foo.md > foo.latex
pdflatex foo.latex

UTF-8 support for groff(1) PDF or PS output requires 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 | pdfroff -itk -mspdf -FU-T > foo.pdf

To list all metadata keys, then to extract the "title" metadata value
from foo.md:

lowdown -L foo.md
lowdown -X title foo.md

SEE ALSO

lowdown-diff(1), lowdown(3), lowdown(5)

AUTHORS

lowdown was forked from hoedown: https://github.com/hoedown/hoedown by
Kristaps Dzonsons, kristaps@bsd.lv. It has been considerably modified
since.

illumos February 27, 2025 illumos