table of contents
LOWDOWN(1) | General Commands Manual | LOWDOWN(1) |
NAME¶
lowdown
— simple
markdown translator
SYNOPSIS¶
lowdown |
[input_options] [output_options] [-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 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
-T
gemini,-T
html,-T
latex,-T
ms, and-T
man. -M
metadata- Provide a single metadata key-value pair. This may be in the usual
lowdown(5) colon-separated metadata format or instead
separated by an equal sign, depending upon which character 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- The output mode. This may be html for HTML5 output,
latex for LaTeX, gemini for
the Gemini 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. -X
keyword- Instead of outputting the full translated file, extract only the given
metadata keyword and exit. These will be escaped according to the output
mode
-T
; for example, a title of “<foo>” with-T
html will be extracted as “<foo>”. Metadata is not rendered for-T
tree or-T
null. - 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-codeindent
- 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. 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.
--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
-T
html, 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 -T
man and
-T
ms, the following apply:
--nroff-no-groff
- Don't use groff(1) style section headings, PDF
hyperlinks (this further requires
-m
spdf passed to groff(1)), or Unicode sequence syntax. The output is compatible with traditional troff(1). Applies to-T
man and-T
ms. --nroff-no-numbered
- Don't output numbered headings. Only applies to
-T
ms. --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. Applies to-T
man or when-nroff-no-groff
is specified. --nroff-shortlinks
- Shorten URLs for images, links, and autolinks to only the domain name and
final path. Applies to
-T
man or when-nroff-no-groff
is specified.
The -T
term 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-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 -T
gemini 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 -T
latex 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.
Metadata¶
If parsed from the document or as given by
-m
or -M
, the following
metadata keys are recognised by output front-ends. 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
-T
man. - Document author. Multiple authors may be separated by more than one space
(including newlines). Overridden by
rcsauthor
. Used in all output modes but-T
man. baseheaderlevel
- The “top-most” header level. For example, having a base
header level of 2 will cause all headers originally level 1 to be level 2.
So for
-T
html, any instance of<h1>
would be instead<h2>
. If unset or less than one, defaults to one. copyright
- A document copyright (without the word “Copyright”), for
example, “2017, Kristaps Dzonsons”. Used in
-T
ms and-T
html. 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. date
- Document date in ISO-8601 YYYY-MM-DD format. Overridden 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
-T
html. - 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. section
- Man page section, defaulting to “7”. Only used in
-T
man. source
- Man page source (organisation providing the manual). Only used in
-T
man. volume
- Man page volume (describes the manual page section). Only used in
-T
man. title
- Document title, defaulting to “Untitled article”. Used in all output modes.
Metadata values are parsed and may be pasted in markdown documents
regardless of whether -s
is specified or not.
Output modes¶
A detailed description of the output modes follows.
-T
gemini- Gemini protocol output. This output mode (and the protocol) are experimental.
-T
html- HTML5 output with UTF-8 encoding. All features of lowdown(5) are supported.
-T
latex- Simple LaTeX output. The following packages are used by
lowdown
:graphicx
for images,inputenc
(utf8) for UTF-8 input,fontend
(T1) andtextcomp
for output glyphs,lmodern
for Latin modern font,xcolor
for the difference engine output, andhyperref
for links. -T
man- 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.
-T
ms- 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.
-T
term- ANSI-escaped UTF-8 output suitable for reading on the terminal. Images and equations not supported.
-T
tree- Debugging output: not for general use.
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 extract the HTML-escaped title from a file's metadata:
lowdown -X title foo.md
SEE ALSO¶
AUTHORS¶
lowdown
was forked from
hoedown by
Kristaps Dzonsons,
kristaps@bsd.lv. It has been
considerably modified since.
February 18, 2021 | Debian |