1LOWDOWN(1) BSD General Commands Manual LOWDOWN(1)
2
4 lowdown — simple markdown translator
5
7 lowdown [input_options] [output_options] [-Ls] [-M metadata]
8 [-m metadata] [-o file] [-t mode] [-X keyword] [file]
9
11 Translate from lowdown(5) into diverse output formats. Results are writ‐
12 ten to standard output.
13 The arguments are as follows:
15 -L Lists metadata keys, one key per line. The -t mode is ignored.
17 Metadata is automatically enabled. Unsets -X.
18 -s Standalone mode. This emits a document envelope surrounding the
20 output by drawing from document metadata. See Metadata on pro‐
21 viding information to the document envelope. This applies to
22 -tgemini, -thtml, -tlatex, -tms, -tman, and -tfodt.
23 -M metadata
25 Provide a single metadata key-value pair. This may be in the
26 syntax specified by lowdodwn(5) or as pairs separated by an equal
27 sign, depending upon which character (a colon or equal sign)
28 comes first. Exits with an error if given neither colon nor
29 equal sign. May be invoked multiple times for each pair. This
30 overrides -m and what's parsed from the document.
31 -m metadata
33 Like -M, but is overridden by what's parsed the document, then
34 -M.
35 -o file
37 Send output to file unless it's “-”, in which case fall back to
38 the default of standard output.
39 -t mode, -T mode
41 The output mode. This may be html for HTML5 output, latex for
42 LaTeX, gemini for the Gemini format, ms for roff output using the
43 classic (i.e., no-extension) -ms package and needing table sup‐
44 port, term for ANSI-compatible UTF-8 terminal output, man for
45 roff output using the classic -man package, tree, to show the
46 parse tree of the input document, and null to parse the document
47 but do no rendering. See Output modes. The -T mode form is re‐
48 tained for backward compatibility.
49 -X keyword
51 Output the metadata value of keyword or an empty string if not
52 found. The -t mode is ignored. Metadata is automatically en‐
53 abled. Unsets -L.
54 file Input Markdown document. If not given or if file is “-”, it is
56 read from standard input.
57 The following are options for input parsing. These affect the parse tree
59 passed to all outputs.
60 --parse-hilite
62 Enable highlight span support. This are disabled by default be‐
63 cause it may be erroneously interpreted as section headers.
64 --parse-math
66 Recognise mathematics equations.
67 --parse-maxdepth=depth
69 The maximum depth of nested elements. This defaults to 128,
70 which is probably more than enough for any real-world document.
71 If the maximum is hit, the system exits as if memory were ex‐
72 hausted. Set to zero for no maximum.
73 --parse-no-autolink
75 Do not parse http, https, ftp, mailto, and relative links or link
76 fragments.
77 --parse-no-cmark
79 Do not parse with CommonMark constraints. This also disables us‐
80 ing the first ordered list value instead of starting all lists at
81 one.
82 --parse-no-codeindent
84 Do not parse indented content as code blocks.
85 --parse-no-deflists
87 Do not parse PHP extra definition lists.
88 --parse-no-ext-attrs
90 Do not parse PHP extra extended attributes.
91 --parse-no-fenced
93 Do not parse GFM fenced (language-specific) code blocks.
94 --parse-no-footnotes
96 Do not parse MMD footnotes.
97 --parse-no-img-ext
99 Deprecated. See --parse-no-ext-attrs.
100 --parse-no-intraemph
102 Do not parse emphasis within words and links.
103 --parse-no-mantitle
105 Do not parse manpage title, section, source, and volume from Pan‐
106 doc title metadata. Manpages titles are indicated by a title
107 then an open parenthesis, digit followed by optional characters,
108 then a closed parenthesis.
109 --parse-no-metadata
111 Do not parse metadata. This does not affect metadata given on -m
112 or -M.
113 --parse-no-strike
115 Do not parse strikethroughs.
116 --parse-no-super
118 Do not parse super-scripts.
119 --parse-no-tables
121 Do not parse GFM tables.
122 --parse-no-tasklists
124 Do not parse GFM task lists.
125 There are many output options. The following are shared by all output
127 modes:
128 --out-standalone
130 Alias for -s.
131 --out-no-smarty
133 Do not use the smart typography filter. By default, certain
134 character sequences are translated into output-specific glyphs.
135 What follows are per-output options. For HTML with -thtml, these are as
137 follows:
138 --html-hardwrap
140 Hard-wrap paragraph content by outputting line breaks where ap‐
141 plicable.
142 --html-no-escapehtml
144 If --html-no-skiphtml has been specified, this causes embedded
145 HTML not to be escaped, and is instead output verbatim. This has
146 no effect if --html-no-skiphtml has not been specified.
147 --html-no-head-ids
149 Do not output id attributes for headers.
150 --html-no-num-ent
152 Don't normalise HTML entities (when possible) as numeric ones and
153 instead use the entities as given on input.
154 --html-no-owasp
156 Don't follow the OWASP recommendations for escaping text, and do
157 only the minimal escaping to make sure that regular content isn't
158 interpreted as HTML.
159 --html-no-skiphtml
161 Output embedded HTML. By default, embedded HTML is not output at
162 all. See --html-no-escapehtml.
163 For both -tman and -tms, the following apply:
165 --nroff-no-groff
167 Don't use groff(1) style section headings, PDF hyperlinks and
168 multi-page tables (these further require -tms mode and -mspdf
169 passed to groff(1)), or Unicode sequence syntax. The output is
170 compatible with traditional troff(1). Applies to -tman and -tms.
171 --nroff-no-numbered
173 Don't output numbered headings. Only applies to -tms.
174 --nroff-no-skiphtml
176 Output embedded HTML. This usually doesn't make sense because
177 the HTML won't be interpreted by the output reader. By default,
178 HTML is omitted.
179 --nroff-nolinks
181 Don't show URLs for images and links (autolinks are still shown).
182 (Link content is still shown.) Overrides --nroff-shortlinks for
183 images and links. Applies to -tman or when -nroff-no-groff is
184 specified.
185 --nroff-shortlinks
187 Shorten URLs for images, links, and autolinks to only the domain
188 name and final path. Applies to -tman or when -nroff-no-groff is
189 specified.
190 The -tterm output has the following:
192 --term-columns=columns
194 The number of columns in the screen. Useful for when running in
195 a pipe. Defaults to what the terminal reports or 72 if in a
196 pipe.
197 --term-hmargin=margin
199 The number of left margin spaces. Truncated to the number of
200 columns. Defaults to zero.
201 --term-no-ansi
203 Don't show ANSI styles at all. This implies --term-no-colour.
204 --term-no-colour
206 Don't show ANSI colours. This will still decorate text with un‐
207 derlines, bolds, and italics, but not emit any colour codes.
208 --term-nolinks
210 Don't show URLs for images and links (autolinks are still shown).
211 (Link content is still shown.) Overrides --term-shortlinks for
212 images and links.
213 --term-shortlinks
215 Shorten URLs for images, links, and autolinks to only the domain
216 name and final path.
217 --term-vmargin=margin
219 The number of top and bottom margin newlines. Defaults to zero.
220 --term-width=width
222 Set the soft limit on the number of characters per line. This
223 may be exceeded by literal text. The default (or if zero) is the
224 number of terminal columns or 80 at most.
225 The -tgemini output has several flags that control the placement of
227 links. By default, links (images, autolinks, and links) are queued when
228 specified in-line then emitted in a block sequence after the nearest
229 block element.
230 --gemini-link-end
232 Emit the queue of links at the end of the document instead of af‐
233 ter the nearest block element.
234 --gemini-link-inline
236 Render all links within the flow of text. This will cause break‐
237 age when nested links, such as images within links, links in
238 blockquotes, etc. It should not be used unless in carefully
239 crafted documents.
240 --gemini-link-noref
242 Do not format link labels. Takes precedence over
243 --gemini-link-roman.
244 --gemini-link-roman
246 When formatting link labels, use lower-case Roman numerals in‐
247 stead of the default lower-case hexavigesimal (i.e., “a”, “b”,
248 ..., “aa”, “ab”, ...).
249 --gemini-metadata
251 Print metadata as the canonicalised key followed by a colon then
252 the value, each on one line (newlines replaced by spaces). The
253 metadata block is terminated by a double newline. If there is no
254 metadata, this does nothing.
255 The -tlatex output has the following options:
257 --latex-no-numbered
259 Don't number sections (and subsections, etc.).
260 --latex-no-skiphtml
262 Output embedded HTML. This usually doesn't make sense because
263 the HTML won't be interpreted by the output reader. By default,
264 HTML is omitted.
265 The -tfodt output has the following options:
267 --odt-no-skiphtml
269 Output embedded HTML. This usually doesn't make sense because
270 the HTML won't be interpreted by the output reader. By default,
271 HTML is omitted.
272 --odt-style=file
274 Specify an OpenDocument style file, which must consist of at
275 least <office:font-face-decls>, <office:scripts>, and
276 <office:styles> XML elements in the root of the document. This
277 is not syntax-checked in any way.
278 Output modes
280 The output media is specified by -t, which defaults to -thtml.
281 -tfodt “Flat” OpenDocument output. Automatic styles (those conditional
283 upon document state) are generated with output. Classes speci‐
284 fied by PHP extended attributes are not checked for existence.
285 -tgemini
287 Gemini protocol output. This output mode is experimental.
288 -thtml HTML5 output with UTF-8 encoding.
290 -tlatex
292 Simple LaTeX output. The following packages are required:
293 amsmath and amssymb for maths, graphicx for images, inputenc
294 (utf8) for UTF-8 input, fontend (T1) and textcomp for output
295 glyphs, lmodern for Latin modern font, xcolor for the difference
296 engine output, and hyperref for links.
297 -tman The man macro package suitable for reading by groff(1),
299 mandoc(1), or traditional troff(1). Does not support equations
300 and images. Table support is provided by tbl(1). Since UTF-8
301 may be passed as input values, preconv(1) may need to be used.
302 -tms The ms macro package suitable for reading by groff(1) or tradi‐
304 tional troff(1). Does not support equations and limited image
305 support for encapsulated postscript (PS and EPS suffix) images.
306 Images are always block-formatted. Image dimensions and extended
307 attributes are ignored, though images are downsized if larger
308 than the current text width. Table support is provided by
309 tbl(1). Since UTF-8 may be passed as input values, preconv(1)
310 may need to be used.
311 -tterm ANSI-escaped UTF-8 output suitable for reading on the terminal.
313 Images and equations not supported.
314 -ttree Debugging output: not for general use.
316 Standalone documents
318 When -s is specified, additional content may be added to output:
319 -tfodt Envelope <office:document> and prologue
321 <office:automatic-styles>, <office:master-styles>, and
322 <office:body>.
323 -thtml Envelope <html> and prologue <head>.
325 -tlatex
327 Prologue documentclass and usepackage statements, and surrounding
328 begin{document} statements.
329 -tman, -tms
331 Prologue macros.
332 If parsed from the document or as given by -m or -M, the following meta‐
334 data keys are used by additional content. The metadata keys are canoni‐
335 calised in lowercase and without spaces.
336 Metadata values should not be encoded in their output format, e.g., “css:
338 foo&bar”. The renderer will perform any necessary output encoding.
339 affiliation
341 Author affiliation (organisation or institution). Multiple af‐
342 filiations may be separated by two or more spaces (including new‐
343 lines). Used in -thtml, -tlatex, and -tms.
344 author Document author. Multiple authors may be separated by two or
346 more spaces (including newlines). Overridden by rcsauthor. Used
347 in -tfodt, -thtml, -tlatex, and -tms.
348 baseheaderlevel
350 Added to each header level. Deprecated in favour of
351 shiftheadinglevelby.
352 copyright
354 A document copyright (without the word “Copyright”), for example,
355 “2017, Kristaps Dzonsons”. Used in -tms and -thtml.
356 css A CSS file included in the HTML5 document head. Multiple CSS
358 files (in order) may be separated by two or more spaces (includ‐
359 ing newlines). Only used in -thtml.
360 date Document date in ISO-8601 YYYY-MM-DD format. Overridden by
362 rcsdate. Used in -tfodt, -thtml, -tlatex, -tman, and -tms.
363 javascript
365 A JavaScript file included in the HTML5 document head. Multiple
366 script files (in order) may be separated by two or more spaces
367 (including newlines). Only used in -thtml.
368 lang Document language in RFC 5646 format. Only used in -thtml.
370 rcsauthor
372 Like author, but in RCS author format. Overrides author.
373 rcsdate
375 Like date, but in RCS date format. Overrides date.
376 section
378 Man page section, defaulting to “7”. Only used in -tman.
379 shiftheadinglevelby
381 Shift all headers by the given number. For example, a value of 1
382 causes headers originally at level 1 (“<h1>”) to be level 2
383 (“<h2>”), while a value of -1 moves level 2 to 1. Levels will
384 not move to less than 1. Takes precedence over baseheaderlevel.
385 If unset or not a valid number, defaults to zero. Used in
386 -tfodt, -thtml, -tlatex, -tman, and -tms.
387 source Man page source (organisation providing the manual). Only used
389 in -tman.
390 volume Man page volume (describes the manual page section). Only used
392 in -tman.
393 title Document title. Used in -tfodt, -thtml, -tlatex, -tman, and
395 -tms.
396 Metadata values are parsed and may be used as variables in markdown docu‐
398 ments regardless of whether -s is specified or not.
399 Default values, such “7” for the section, are not set as metadata values,
401 and will not appear if the metadata key is used as a variable.
402
404 NO_COLOR
405 Do not emit colours when in -tterm mode. Synonym for NO_COLOUR.
406 Same as --term-nocolour.
407
409 share/odt/styles.xml
410 Default styles used when generating standalone -tfodt documents.
411 Template for --odt-style styles.
412
414 The lowdown utility exits 0 on success, and >0 if an error occurs.
415 If the -X flag is used, lowdown exits with an error if the given keyword
417 is not found.
418
420 To view a Markdown file on an ANSI-compatible, UTF-8 terminal:
421 lowdown -tterm foo.md | less -R
423 The terminal may also be used with groff(1) or mandoc(1) rendering:
425 lowdown -stms foo.md | groff -itk -mspdf -Tutf8 | less -R
427 lowdown -stman foo.md | groff -itk -man -Tutf8 | less -R
428 lowdown -stman foo.md | mandoc | less
429 To emit a standalone HTML5 document:
431 lowdown -s foo.md > foo.html
433 To use groff(1) or mandoc(1) to format as a PS file:
435 lowdown -stms foo.md | groff -itk -mspdf > foo.ps
437 lowdown -stman foo.md | mandoc -Tps > foo.ps
438 Or with LaTeX:
440 lowdown -stlatex foo.md > foo.latex
442 pslatex foo.latex
443 PDF generation follows similar logic:
445 lowdown -stms foo.md | pdfroff -itk -mspdf > foo.pdf
447 lowdown -stman foo.md | mandoc -Tpdf > foo.pdf
448 lowdown -stlatex foo.md > foo.latex
449 pdflatex foo.latex
450 UTF-8 support for groff(1) PDF or PS output requires appropriate fonts,
452 such as the Unicode Times font. This and other Unicode fonts are not al‐
453 ways installed by default. They may be found, for PDF output, in the
454 devpdf set of the groff(1) font directory and are prefixed with ‘U’.
455 lowdown -stms foo.md | pdfroff -itk -mspdf -FU-T > foo.pdf
457 To list all metadata keys, then to extract the "title" metadata value
459 from foo.md:
460 lowdown -L foo.md
462 lowdown -X title foo.md
463
465 lowdown-diff(1), lowdown(3), lowdown(5)
466
468 lowdown was forked from hoedown: https://github.com/hoedown/hoedown by
469 Kristaps Dzonsons, kristaps@bsd.lv. It has been considerably modified
470 since.
471BSD December 17, 2023 BSD