--- name: "lowdown-diff" section: "1" platform: "linux" package: "lowdown" version: "3.2.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/lowdown-diff" --- # lowdown-diff(1) view differences in markdown files ## NAME **lowdown-diff** – view differences in markdown files ## SYNOPSIS **lowdown-diff** \[input\_options\] \[output\_options\] \[**-s**\] \[**-M** *metadata*\] \[**-m** *metadata*\] \[**-o** *file*\] \[**-t** *mode*\] *oldfile* \[*newfile*\] ## DESCRIPTION Shows differences between [lowdown(5)](/lowdown/5.md) documents as formatted output. Results are written to standard output. The short arguments are as follows: - **-s** Produce a standalone document (e.g., a valid HTML document including document type, head, etc.) around the formatted content. See Standalone documents for details. - **-M** *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 **-m** and what's parsed from the document. See Metadata. - **-m** *metadata* Like **-M**, but 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 “gemtext” format, *ms* for roff output using the **-mspdf** package and needing table support, *term* for ANSI-compatible UTF-8 terminal output, *man* for roff output using the **-man** package, *mdoc* for roff output using the **-mdoc** package, *tree*, to show the parse tree of the input document, and *null* to parse the document but do no rendering. See Output media. The **-T** *mode* form is retained for backward compatibility. - *oldfile*, *newfile* Markdown documents used for comparison. If *newfile* is not given or “-”, it is read from standard input. The following are long 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-callouts** Do not parse GFM/MDN callouts (“admonitions”). - **--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-mantitle** Do not parse manpage title, section, source, and volume from Pandoc title metadata. Manpages titles are indicated by a title then an open parenthesis, digit followed by optional characters, then a closed parenthesis. - **--parse-no-metadata** Do not parse metadata. 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 or sub-scripts at all. - **--parse-no-tables** Do not parse GFM tables. - **--parse-no-tasklists** Do not parse GFM task lists. - **--parse-super-short** If super-script parsing is enabled, use the traditional non-GFM “short” syntax. There are many output long options. The following are shared by all output media: - **--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. - **--template** *template* When producing standalone **-s** output, use a template file. See Templates. Currently only for **-t***gemini*, **-t***html*, **-t***latex*, **-t***man*, **-t***ms*, and **-t***tree*. What follows are per-output long options. For HTML with **-t***html*, these are as follows: - **--html-callout-mdn**, **--html-callout-gfm** Output either or both MDN or GFM callout syntaxes. - **--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**. - **--html-titleblock** If any were parsed, format the title information (title, author, date) into a header element appearing first in the document. For roff formats **-t***man*, **-t***mdoc*, and **-t***ms* (unless as noted), the following apply: - **--roff-code-font**=*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,BI uses bold (“B”) instead of a constant-width. Not specifying a font will use the default, as will specifying a zero-length font name. Aliases none, bold, and code set no special fonts, bold, and the default constant-width. - **--roff-endnotes** Delay printing of footnotes until the end of the document. Only applies to **-t***ms*, as **-t***man* and **-t***mdoc* only support endnotes. - **--roff-manpage** Format output as a manpage. This re-formats paragraphs under the NAME, SYNOPSIS, and SEE ALSO sections in the canonical form used by manpages. The way the document is formatted depends upon the section metadata: 1, 6, and 8 for program-style; 2, 3, and 9 for function-style. Program style re-formats flags and arguments, while function style re-formats function names, variables, arguments. Any content in font spans (e.g., emphasis or double emphasis) in other sections is stripped of the font and re-formatted in the same way. Only applies to **-t***man* and **-t***mdoc*. - **--roff-no-numbered** Don't output numbered headings( .NH NN). Only applies to **-t***ms*. - **--roff-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. - **--roff-no-links** When possible, don't show URLs for images and links. Link content is always shown. Overrides **--roff-short-links** and **--roff-no-rellinks**. - **--roff-no-rellinks** When possible, don't show URLs for relative links. Link content is always shown. Overrides **--roff-short-links**. - **--roff-short-links** When possible, shorten URLs for images, links, and autolinks to only the domain name and final path. - **--roff-traditional** Output traditional **-ms** (not **-mspdf**) and **-man** without extensions. Specifically, 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 traditional [troff(1)](/troff/1.md). The argument prefix **--nroff**, such as in **--nroff-traditional**, is deprecated in favour of **--roff**. The **-t***term* output has the following: - **--term-all-metadata** If **-s** is specified, output all metadata instead of just the title, author, and date. - **--term-columns=columns** 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. - **--term-hmargin=margin** The number of left margin characters. Defaults to zero. Can also be *auto* to set the left margin to half the remaining **--term-columns** after subtracting **--term-width**. - **--term-hpadding=padding** The number of left padding characters. Defaults to four. Padding eats into **--term-width**. - **--term-no-ansi** Don't show ANSI styles at all. Use backspace encoding instead for bold/underline. 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-no-links** When possible, don't show URLs for images and links. Link content is always shown. Overrides **--term-short-links** and **--term-no-rellinks**. - **--term-no-rellinks** When possible, don't show URLs for relative links. Link content is always shown. Overrides **--term-short-links**. - **--term-no-style** Don't use any escape styles at all. This implies **--term-no-ansi**. - **--term-no-tablewrap** Don't wrap table columns to fit the width of the output. - **--term-short-links** When possible, 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** 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-columns** or 80 at most. Truncates to **--term-columns**. 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. The **-t***fodt* 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 \, \, and \ 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 **-t***html*. - **-t***fodt* “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. - **-t***gemini* Gemini “gemtext” format. - **-t***html* HTML5 output with UTF-8 encoding. - **-t***latex* Simple LaTeX output. The following packages are required: amsmath and amssymb for maths, graphicx for images, inputenc (utf8) for UTF-8 input, frontend (T1) and textcomp for output glyphs, lmodern for Latin modern font, xcolor for the difference engine output, and hyperref for links. - **-t***man* The *man* macro package suitable for reading by [groff(1)](/groff/1.md), [mandoc(1)](/mandoc/1.md), Heirloom [troff(1)](/troff/1.md), or traditional [troff(1)](/troff/1.md). Does not support equations and images. Table support is provided by [tbl(1)](/tbl/1.md). Since UTF-8 may be passed as input values, [preconv(1)](/preconv/1.md) may need to be used. - **-t***mdoc* The *mdoc* macro package suitable for reading by [groff(1)](/groff/1.md), [mandoc(1)](/mandoc/1.md), Heirloom [troff(1)](/troff/1.md), or (possibly?) traditional [troff(1)](/troff/1.md). Does not support equations and images. Table support is provided by [tbl(1)](/tbl/1.md). Since UTF-8 may be passed as input values, [preconv(1)](/preconv/1.md) may need to be used. - **-t***ms* The *ms* macro package suitable for reading by [groff(1)](/groff/1.md) or traditional [troff(1)](/troff/1.md). 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)](/tbl/1.md). Since UTF-8 may be passed as input values, [preconv(1)](/preconv/1.md) 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 programmatic use, as the format may change between versions. ### Differences The differences between old and new document are illustrated in the following ways: - **-t***fodt* “Flat” Differences are rendered using document tracking. - **-t***gemini* Differences are not rendered. - **-t***latex* Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). - **-t***man*, **-t***mdoc*, **-t***ms* Differences are rendered by colouring in blue (insert) and red (delete) (this format is not fixed). - **-t***term* Differences are rendered by background-colouring in blue (insert) and red (delete) (this format is not fixed). - **-t***tree* Differences are manually in the tree output. Differences in content metadata use the following rule: deleted metadata key-value pairs are not processed in the output, so only inserted or retained metadata are processed. ### Standalone documents When **-s** is specified, the formatted content is serialised into a self-contained document template as defined by the output type. If not explicitly set with **--template**, a default template is produced as follows: - **-t***fodt* Envelope \ and prologue \, \, and \. - **-t***html* HTML5 doctype declaration followed by envelope \ with optional language, then \. In order, the \ consists of charset and viewport \ elements; optional \ elements from metadata affiliation (creator), author, copyright, and date; optional CSS sources from metadata; optional JavaScript sources from metadata; the possibly-empty \; then optional arbitrary content from metadata HTML header. - **-t***latex* Prologue documentclass and usepackage statements, optional arbitrary content from metadata LaTeX header, then surrounding begin{document} statements. - **-t***man*, **-t***mdoc*, **-t***ms* Prologue macros. - **-t***term* Prologue lines. - **-t***tree* Metadata and parsed template. See Metadata for metadata values used by the default template. ### Metadata Metadata keys are canonicalised and de-deduplicated in the following order: **-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 serialised into document variables and/or standalone **-s** output. When not using **--template**, the following metadata keys are used in the default **-s** template: - affiliation Author affiliation (organisation or institution). Multiple affiliations may be separated by two or more spaces (including newlines). Used in **-t***html*, **-t***latex*, and **-t***ms*. - author Document author. Multiple authors may be separated by two or more spaces (including newlines). Overridden by rcsauthor. Used in **-t***fodt*, **-t***html*, **-t***latex*, **-t***ms*, and **-t***term*. - 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 **-t***ms* and **-t***html*. - css A CSS file output in the HTML document head as a \ 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 **-t***html*. - date Document date in ISO-8601 YYYY-MM-DD format. Overridden by rcsdate. Used in **-t***fodt*, **-t***html*, **-t***latex*, **-t***man*, **-t***mdoc*, **-t***ms*, and **-t***term*. - htmlheader Arbitrary HTML content output in the HTML document head immediately prior to closing the head element. Only used in **-t***html* and with **-s**. This metadata is not processed: it's passed unchanged into the output. - javascript A JavaScript file output in the HTML document head as a \