Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LOWDOWN(1)		FreeBSD	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 writ-
     ten 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	pro-
	     viding information	to the document	envelope.  This	only applies
	     to	-Tgemini, -Thtml, -Tlatex, -Tms, and -Tman.

     -M	metadata
	     Provide a single metadata key-value pair.	This may be in the
	     usual lowdown(5) colon-separated metadata format or instead sepa-
	     rated 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 over-
	     rides -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	sup-
	     port, 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
	     -Thtml will be extracted as "&lt;foo&gt;".	 Metadata is not ren-
	     dered for -Ttree or -Tnull.

     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 be-
	     cause 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 ex-
	     hausted.  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 us-
	     ing 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 -Thtml, these are as
     follows:

     --html-hardwrap
	     Hard-wrap paragraph content by outputting line breaks where ap-
	     plicable.

     --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-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 af-
	     ter the nearest block element.

     --gemini-link-inline
	     Render all	links within the flow of text.	This will cause	break-
	     age 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	in-
	     stead 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.

   Metadata
     If	parsed from the	document or as given by	-m or -M, the following	meta-
     data keys are recognised by output	front-ends.  The metadata keys are
     canonicalised in lowercase	and without spaces.

     affiliation
	     Author affiliation	(organisation or institution).	Multiple af-
	     filiations	may be separated by more than one space	(including
	     newlines).	 Used in all output modes but -Tman.

     author  Document author.  Multiple	authors	may be separated by more than
	     one space (including newlines).  Overridden by rcsauthor.	Used
	     in	all output modes but -Tman.

     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	-Thtml,	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 -Tms and -Thtml.

     css     A CSS file	included in the	HTML5 document head.  Multiple CSS
	     files (in order) may be separated by more than one	space (includ-
	     ing newlines).  Only used in -Thtml.

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

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

     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	all
	     output modes.

     Metadata values are parsed	and may	be pasted in markdown documents	re-
     gardless of whether -s is specified or not.

   Output modes
     A detailed	description of the output modes	follows.

     -Tgemini
	     Gemini protocol output.  This output mode (and the	protocol) are
	     experimental.

     -Thtml  HTML5 output with UTF-8 encoding.	All features of	lowdown(5) are
	     supported.

     -Tlatex
	     Simple LaTeX output.  The following packages are used by lowdown:
	     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 tradi-
	     tional 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.

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

FreeBSD	13.0			March 28, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | EXAMPLES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lowdown&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help