Scroll to navigation

LOWDOWN(1) General Commands Manual LOWDOWN(1)

NAME

lowdown—simple markdown translator

SYNOPSIS

lowdown [input_options][output_options][-Ls][-Mmetadata][-mmetadata][-ofile][-tmode][-Xkeyword][file]

DESCRIPTION

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

The short arguments are as follows:

Lists metadata keys, one key per line.The-tmode is ignored.Metadata is automatically enabled.Unsets-X.
Produce a standalone document (e.g., a valid HTML document includingdocument type, head, etc.) around the formatted content.SeeStandalone documentsfor details.
metadata
Provide a single metadata key-value pair.This may be in the normal syntax 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.This overrides-mand what's parsed from the document.SeeMetadata.
metadata
Like-M,but overridden by what's parsed the document, then-M.
file
Send output tofileunless it's“-”,in which case fall back to the default of standard output.
mode,-Tmode
The output mode.This may behtmlfor HTML5 output,latexfor LaTeX,geminifor the Gemini“gemtext”format,msfor roff output using the classic (i.e., no-extension)-mspackage and needing table support,termfor ANSI-compatible UTF-8 terminal output,manfor roff output using the classic-manpackage,tree,to show the parse tree of the input document, andnullto parse the document but do no rendering.SeeOutput media.The-Tmodeform is retained for backward compatibility.
keyword
Output the metadata value ofkeywordor an empty string if not found.The-tmode is ignored.Metadata is automatically enabled.Unsets-L.
file
Input Markdown document.If not given or iffileis“-”,it is read from standard input.

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

Enable highlight span support.This are disabled by default because it may be erroneously interpretedas section headers.
Recognise mathematics equations.
The maximum depth of nested elements.This defaults to 128, which is probably more than enough for anyreal-world document.If the maximum is hit, the system exits as if memory were exhausted.Set to zero for no maximum.
Do not parsehttp,https,ftp,mailto,and relative links or link fragments.
Do not parse with CommonMark constraints.This also disables using the first ordered list value instead ofstarting all lists at one.
Do not parse indented content as code blocks.
Do not parse GFM/MDN callouts(“admonitions”).
Do not parse PHP extra definition lists.
Do not parse PHP extra extended attributes.
Do not parse GFM fenced (language-specific) code blocks.
Do not parse MMD footnotes.
Deprecated.See--parse-no-ext-attrs.
Do not parse emphasis within words and links.
Do not parse manpage title, section, source, and volume from Pandoctitle metadata.Manpages titles are indicated by a title then an open parenthesis, digitfollowed by optional characters, then a closed parenthesis.
Do not parse metadata.This does not affect metadata given on-mor-M.
Do not parse strikethroughs.
Do not parse super-scripts or sub-scripts at all.
Do not parse GFM tables.
Do not parse GFM task lists.
If super-script parsing is enabled, use the traditionalnon-GFM“short”syntax.

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

Alias for-s.
Do not use the smart typography filter.By default, certain character sequences are translated intooutput-specific glyphs.
template
When producing standalone-soutput, use a template file.SeeTemplates.Currently only for-tgemini,-thtml,-tlatex,-tman,-tms,and-ttree.

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

,--html-callout-gfm
Output either or both MDN or GFM callout syntaxes.
Hard-wrap paragraph content by outputting line breaks where applicable.
If--html-no-skiphtmlhas been specified, this causes embedded HTML not to be escaped, and isinstead output verbatim.This has no effect if--html-no-skiphtmlhas not been specified.
Do not outputidattributes for headers.
Don't normalise HTML entities (when possible) as numeric ones andinstead use the entities as given on input.
Don't follow the OWASP recommendations for escaping text, and do onlythe minimal escaping to make sure that regular content isn't interpretedas HTML.
Output embedded HTML.By default, embedded HTML is not output at all.See--html-no-escapehtml.
If any were parsed, format the title information (title, author, date)into a header element appearing first in the document.

For both roff formats-tmanand-tms(unless as noted),the following apply:

=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,BIuses bold(“B”)instead of a constant-width.Not specifying a font will use the default, as will specifying azero-length font name.Aliasesnone,bold,andcodeset no special fonts, bold, and the default constant-width.
Delay printing of footnotes until the end of the document.Only applies to-tms,as-tmanonly supports endnotes.
Don't output numbered headings(.NH NN).Only applies to-tms.
Output embedded HTML.This usually doesn't make sense because the HTML won't be interpreted bythe output reader.By default, HTML is omitted.
Don't show URLs for images and links (autolinks are still shown).(Link content is still shown.)Overrides--roff-short-linksfor images and links.Only applies when--roff-traditionalis specified.
Shorten URLs for images, links, and autolinks to only the domain nameand final path.Only applies when--roff-traditionalis specified.
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 traditionaltroff(1).

The argument prefix--nroff,such as in--nroff-traditional,is deprecated in favour of--roff.

The-ttermoutput has the following:

If-sis specified, output all metadata instead of just the title, author, anddate.
The number of columns in the terminal.Useful for when running in a pipe.Defaults to what the terminal reports or 72 if not in a terminal.
The number of left margin characters.Defaults to zero.Can also beautoto set the left margin to half the remaining--term-columnsafter subtracting--term-width.
The number of left padding characters.Defaults to four.Padding eats into--term-width.
Don't show ANSI styles at all.This implies--term-no-colour.
Don't show ANSI colours.This will still decorate text with underlines, bolds, and italics, butnot emit any colour codes.
Don't show URLs for images and links (autolinks are still shown).(Link content is still shown.)Overrides--term-short-linksand--term-no-rellinks.
Don't show URLs for relative links.(Link content is still shown.)Overrides--term-short-links.
Shorten URLs for images, links, and autolinks to only the domain nameand final path.
The number of top and bottom margin newlines.Defaults to zero.
Soft limit on the number of characters per line including(--term-hpadding).This may be exceeded by literal text.If zero or unset, defaults to--term-columnsor 80 at most.Truncates to--term-columns.

The-tgeminioutput has several flags that control the placement of links.By default, links (images, autolinks, and links) are queued whenspecified in-line then emitted in a block sequence after the nearestblock element.

Emit the queue of links at the end of the document instead of after thenearest block element.
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.
Do not format link labels.Takes precedence over--gemini-link-roman.
When formatting link labels, use lower-case Roman numerals instead of thedefault lower-case hexavigesimal (i.e.,“a”,“b”,...,“aa”,“ab”,...).
Print metadata as the canonicalised key followed by a colon then thevalue, 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-tlatexoutput has the following options:

Don't number sections (and subsections, etc.).
Output embedded HTML.This usually doesn't make sense because the HTML won't be interpreted bythe output reader.By default, HTML is omitted.

The-tfodtoutput has the following options:

Output embedded HTML.This usually doesn't make sense because the HTML won't be interpreted bythe output reader.By default, HTML is omitted.
=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 media

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

fodt
“Flat”OpenDocument output.Automatic styles (those conditional upon document state) are generatedwith output.Classes specified by PHP extended attributes are not checked forexistence.
gemini
Gemini“gemtext”format.
html
HTML5 output with UTF-8 encoding.
latex
Simple LaTeX output.The following packages are required:amsmathandamssymbfor maths,graphicxfor images,inputenc(utf8)for UTF-8 input,fontend(T1)andtextcompfor output glyphs,lmodernfor Latin modern font,xcolorfor the difference engine output, andhyperreffor links.
man
Themanmacro package suitable for reading bygroff(1),mandoc(1),Heirloomtroff,or traditionaltroff(1).Does not support equations and images.Table support is provided bytbl(1).Since UTF-8 may be passed as input values,preconv(1)may need to be used.
ms
Themsmacro package suitable for reading bygroff(1)or traditionaltroff(1).Does not support equations and limited image support for encapsulatedpostscript (PS and EPS suffix) images.Images are always block-formatted.Image dimensions and extended attributes are ignored, though images aredownsized if larger than the current text width.Table support is provided bytbl(1).Since UTF-8 may be passed as input values,preconv(1)may need to be used.
term
ANSI-escaped UTF-8 output suitable for reading on the terminal.Images and equations not supported.
tree
Debugging output.Not for programmatic use, as the format may change between versions.

Standalone documents

When-sis specified, the formatted content is serialised into a self-containeddocument template as defined by the output type.

If not explicitly set with--template,a default template is produced as follows:

fodt
Envelope<office:document>and prologue<office:automatic-styles>,<office:master-styles>,and<office:body>.
html
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, anddate;optional CSS sources from metadata;optional JavaScript sources from metadata;the possibly-empty<title>;then optional arbitrary content from metadata HTML header.
latex
Prologuedocumentclassandusepackagestatements, optional arbitrary content from metadata LaTeX header, thensurroundingbegin{document}statements.
man,-tms
Prologue macros.
term
Prologue lines.
tree
Metadata and parsed template.

SeeMetadatafor metadata values used by the default template.

Metadata

Metadata keys are canonicalised and de-deduplicated in the followingorder:-m(overridden by document content and-M),the prologue of the document itself, then-M(overriding document content and-m).

After de-duplication, metadata is either accessed directly using-Xor-L,or serialised into document variables and/or standalone-soutput.

When not using--template,the following metadata keys are used in the default-stemplate:

Author affiliation (organisation or institution).Multiple affiliations may be separated by two or more spaces (includingnewlines).Used in-thtml,-tlatex,and-tms.
Document author.Multiple authors may be separated by two or more spaces (includingnewlines).Overridden byrcsauthor.Used in-tfodt,-thtml,-tlatex,-tms,and-tterm.
Added to each header level.Deprecated in favour ofshiftheadinglevelby.
A document copyright (without the word“Copyright”),for example,“2017, Kristaps Dzonsons”.Used in-tmsand-thtml.
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.
Document date in ISO-8601 YYYY-MM-DD format.Overridden byrcsdate.Used in-tfodt,-thtml,-tlatex,-tman,-tms,and-tterm.
Arbitrary HTML content output in the HTML document head immediatelyprior to closing the head element.Only used in-thtmland with-s.This metadata is not processed: it's passed unchanged into the output.
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.
Document language in RFC 5646 format.Only used in-thtml.
Arbitrary LaTeX content output in the document prologue immediatelyprior to thebegin{document}.Only used in-tlatexand with-s.This metadata is not processed: it's passed unchanged into the output.
Arbitrary roff content output immediately prior to the.THmacro.Only used in-tmanand with-s.This metadata is not processed: it's passed unchanged into the output.
Arbitrary roff content output immediately prior to the.TLmacro.Only used in-tmsand with-s.This metadata is not processed: it's passed unchanged into the output.
Likeauthor,but in RCS author format.Overridesauthor.
Likedate,but in RCS date format.Overridesdate.
Man page section, defaulting to“7”.Only used in-tman.
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 overbaseheaderlevel.If unset or not a valid number, defaults to zero.Used in-tfodt,-thtml,-tlatex,-tman,and-tms.
Man page source (organisation providing the manual).Only used in-tman.
Man page volume (describes the manual page section).Only used in-tman.
Document title.Used in-tfodt,-thtml,-tlatex,-tman,-tms,and-tterm.

Default values, such“7”for thesection,are not set as metadata values, and will not appear if the metadata keyis used as a variable.

Templates

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

Control statements are delimited as$statement$or${statement}.Arbitrary white-space may surround the case-insensitive statementbetween 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.
Conditional statement.There may not be any white-space between theifdefand the opening parenthesis.Begins a block that is ended by aelse,endif,or the end of file.Its contents are output only ifexpressionevaluates to a non-empty string.
Begins a block that is ended by aendifor end of file.Its contents are output only if the condition of aprecedingifdefevaluates to an empty string.Anelsewithout a precedingifdefis not output.
Closes a block begin withifdeforelse.If not preceded by one of those statements, is silently ignored.
Looping statement.There may not be any white-space between theforand the opening parenthesis.Begins a block that is ended by anendforor the end of file.Block contents contents are repeatedly output for each list itemevaluated fromexpression.The anaphoric keywordthismay be used to access the current loop expression within the block.
Replaced by the result of evaluating a template expression.

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

Expressions consist of

initial[([arg]*)]?[.transform[([arg]*)]?]*
,

or an initial value accepting optional arguments followed by an optionalseries of transforms accepting optional arguments.If an argument list is empty or not provided, it evaluates to an emptylist.

Theinitialvalue is one of the following:

A non-empty list containing the valuetrueif all expressions evaluate to non-empty lists, otherwise an empty list.An empty expression evaluates to an empty list.
"literal string"
Evaluates to a singleton list containing the string.An empty string evaluates to an empty list.The double quote character may be escaped, such as"foo\"bar".
The parsed input document body.
canonicalised metadata key
The value for the given metadata key, if found, otherwise an empty list.
The parsed input document body.
Produce the metadata value for the canonicalised metadatakey.Allows for keys that are also keywords likebodyorendif.
A non-empty listcontaining the valuetrueif the expression evaluates as an empty list, otherwise an empty list.
A non-empty list containing the valuetrueif one expression evaluates to non-empty lists, otherwise an empty list.An empty expression evaluates to an empty list.
The value of a current loop context or an empty list.

If a metadata key is not specified in the input, or if the anaphoricthishas not initialised by a looping context, the initial value evaluates to anempty list.Otherwise, the value is a singleton list.

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

The following transformations are available:

,escapegeminiline
Escape list items for gemini(-tgemini),either for multiple lines or compressed to a single line.
,escapehtmlattr,escapehtmlurl
Escape list items for HTML(-thtml)body content, attributes, and URL attributes,respectively.
Escape list items for LaTeX(-tlatex)body content.
,escaperoffline
Escape list items for roff(-tms,-tman),either for multiple lines or compressed to a single line.escaperoffalso escapes initial roff delimiters and those after newlines.
Join a list into a singleton list using two spaces as a join delimiter.
Lowercase all list items.
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 ona pre-split list.Invokestrimprior to the first split.The resulting list has no items that are only white-space.
Trim white-space from the beginning and end of all list items.If an item has no non-white-space, it is discarded.
Uppercase all list items.

ENVIRONMENT

Do not emit colours when in-ttermmode.Synonym forNO_COLOUR.Same as--term-nocolour.

FILES

share/html/default.html
The default template used if--templateis not provided to-thtml.
share/latex/default.latex
The default template used if--templateis not provided to-tlatex.
share/man/default.man
The default template used if--templateis not provided to-tman.
share/man/default.ms
The default template used if--templateis not provided to-tms.
share/odt/styles.xml
Default styles used when generating standalone-tfodtdocuments.Template for--odt-stylestyles.

EXIT STATUS

Thelowdownutility exits 0on success, and >0 if an error occurs.

If the-Xflag is used,lowdownexits 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 withgroff(1)ormandoc(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 usegroff(1)ormandoc(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 forgroff(1)PDF or PS output requires appropriate fonts, such as the Unicode Timesfont.This and other Unicode fonts are not always installed by default.They may be found, for PDF output, in thedevpdfset of thegroff(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 fromfoo.md:

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

SEE ALSO

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

AUTHORS

lowdownwas forked fromhoedownbyKristaps Dzonsons,kristaps@bsd.lv.It has been considerably modified since.

August 16, 2025 Debian