Provided by: lowdown_1.0.0-2_amd64
NAME
lowdown — simple markdown translator
SYNOPSIS
lowdown [input_options] [output_options] [-s] [-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 applies to -tgemini, -thtml, -tlatex, -tms, -tman, and -tfodt. -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, -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. 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. file Input Markdown document. If not given or if file is “-”, it 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-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-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. --parse-no-tasklists Do not parse GFM task lists. 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-no-groff Don't use groff(1) style section headings, PDF hyperlinks and multi-page tables (these further require -tms mode and -mspdf passed to groff(1)), or Unicode sequence syntax. The output is compatible with traditional troff(1). Applies to -tman and -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. --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 -tman 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 -tman or when -nroff-no-groff is specified. 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-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 protocol output. This output mode is experimental. -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), 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 Envelope <html> and prologue <head>. -tlatex Prologue documentclass and usepackage statements, and surrounding begin{document} statements. -tman, -tms Prologue macros. 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, and -tms. 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 included in the HTML5 document head. Multiple CSS files (in order) may be separated by two or more spaces (including newlines). Only used in -thtml. date Document date in ISO-8601 YYYY-MM-DD format. Overridden by rcsdate. Used in -tfodt, -thtml, -tlatex, -tman, and -tms. javascript A JavaScript file included in the HTML5 document head. Multiple script files (in order) may be separated by two or more spaces (including newlines). Only used in -thtml. 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, defaulting to “Untitled article”. Used in -tfodt, -thtml, -tlatex, -tman, and -tms. Metadata values are parsed and may be used as variables in markdown documents regardless of whether -s is specified or not. Default values, such “Untitled article” for the title, are not set as metadata values, and will not appear if the metadata key is used as a variable.
ENVIRONMENT
NO_COLOR Do not emit colours when in -tterm mode. Synonym for NO_COLOUR. Same as --term-nocolour.
FILES
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 extract the HTML-escaped title from a file's metadata: 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.