Chapter 5 - Markdown Reference

This chapter describes the markdown syntax that is recognized and supported by HTMLDOC.

General Syntax

Markdown is a simple plain-text format that uses formatting conventions that are commonly used in email and other text-based communications. Markdown is used by most of the major blogging, web site, and project hosting platforms and is supported by many standalone text editors.

HTMLDOC supports the CommonMark version of markdown syntax with the following exceptions:

• Metadata as used by Jekyll and other web markdown solutions can be placed at the beginning of the file;
• "@" links can be used which resolve to headings within the file;
• Tables can be embedded using the "|" separator;
• Embedded HTML markup and entities are explicitly not supported or allowed;
• Link reference definitions are not supported;
• Link titles are silently ignored; and
• Thematic breaks using a mix of whitespace and the separator character are not supported - "* * * *", "-- -- -- --", etc.

Note: HTMLDOC does not support embedded HTML in markdown documents because the version of HTML (or XHTML) cannot be reliably determined, making support of certain character entities and language elements problematic.

Metadata Syntax

Metadata is specified at the top of a markdown file between two lines containing three hyphens, for example:

---
title: My Great Novel
author: John Doe
copyright: Copyright © 2018 by John Doe
version: 1.0
---

# Preamble

...

HTMLDOC supports the "title", "author", "copyright", and "version" metadata and silently ignores everything else.

Link Targets and @ Links

CommonMark defines no standard for how implementations generate anchors or identifiers for headings in a markdown file - this makes hyperlinking to a named section within a document basically impossible. Jekyll and other markdown implementations allow the special link "@" to be used, which HTMLDOC supports:

See [Screwing in a Light Bulb](@) for instructions on installing a
light bulb.

...

# Screwing in a Light Bulb

...

To reference a markdown heading from a HTML file, convert the heading to lowercase, replace spaces with the hyphen ("-"), and remove any special characters. Thus, a HTML file would reference the previous heading using the following HTML:

<a href="#screwing-in-a-light-bulb"> ... </a>

Table Syntax

CommonMark does not define a syntax for plain-text tables, instead relying on embedded HTML which HTMLDOC does not support. Both Github and Jekyll support a common markdown extension for plain text tables that uses the vertical pipe ("|") character to specify column separations. The first line contains the table header, the second line is a horizontal separator, and the remaining lines contain the table body. For example:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| Cell 1,1  | Cell 1,2  | Cell 1,3  |
| Cell 2,1  | Cell 2,2  | Cell 2,3  |
| Cell 3,1  | Cell 3,2  | Cell 3,3  |

will produce:

Heading 1	Heading 2	Heading 3
Cell 1,1	Cell 1,2	Cell 1,3
Cell 2,1	Cell 2,2	Cell 2,3
Cell 3,1	Cell 3,2	Cell 3,3

The outer pipes can be omitted, for example:

Heading 1 | Heading 2 | Heading 3
--------- | --------- | ---------
Cell 1,1  | Cell 1,2  | Cell 1,3
Cell 2,1  | Cell 2,2  | Cell 2,3
Cell 3,1  | Cell 3,2  | Cell 3,3

While table headings are always centered, you can control the alignment of the body cells by using the colon (":") character in the separator line. Put a leading colon to specify left alignment (the default), a trailing colon for right alignment, or both to specify centering. For example:

Left Alignment | Center Alignment | Right Alignment
:------------- | :--------------: | --------------:
Cell 1,1       |     Cell 1,2     |               1
Cell 2,1       |     Cell 2,2     |              12
Cell 3,1       |     Cell 3,2     |             123

will produce:

Left Alignment	Center Alignment	Right Alignment
Cell 1,1	Cell 1,2	1
Cell 2,1	Cell 2,2	12
Cell 3,1	Cell 3,2	123

Table columns do not need to be padded so that they line up - the following (less readable) example is perfectly valid:

Left Alignment|Center Alignment|Right Alignment
:--|:--:|--:
Cell 1,1|Cell 1,2|1
Cell 2,1|Cell 2,2|12
Cell 3,1|Cell 3,2|123