| 1 |
<html> |
| 2 |
<body><!-- FOOTER RIGHT "5-$CHAPTERPAGE" --> |
| 3 |
<div align="justify"> |
| 4 |
<h1 align="right"><a name="MDREF">Chapter 5 - Markdown Reference</a></h1> |
| 5 |
|
| 6 |
<p>This chapter describes the markdown syntax that is recognized and supported by HTMLDOC.</p> |
| 7 |
|
| 8 |
|
| 9 |
<h2>General Syntax</h2> |
| 10 |
|
| 11 |
<p>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.</p> |
| 12 |
|
| 13 |
<p>HTMLDOC supports the <a href="http://spec.commonmark.org/">CommonMark</a> version of markdown syntax with the following exceptions:</p> |
| 14 |
|
| 15 |
<ul> |
| 16 |
<li>Metadata as used by Jekyll and other web markdown solutions can be placed at the beginning of the file;</li> |
| 17 |
<li>"@" links can be used which resolve to headings within the file;</li> |
| 18 |
<li>Tables can be embedded using the "|" separator;</li> |
| 19 |
<li>Embedded HTML markup and entities are explicitly not supported or allowed;</li> |
| 20 |
<li>Tabs are silently expanded to the markdown standard of four spaces since HTML uses eight spaces per tab; and</li> |
| 21 |
<li>Some pathological nested link and inline style features supported by CommonMark (<code>******Really Strong Text******</code>) are not supported by <code>mmd</code>.</li> |
| 22 |
</ul> |
| 23 |
|
| 24 |
<blockquote><b>Note:</b> 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.</blockquote> |
| 25 |
|
| 26 |
|
| 27 |
<h2>Metadata Syntax</h2> |
| 28 |
|
| 29 |
<p>Metadata is specified at the top of a markdown file between two lines containing three hyphens, for example:</p> |
| 30 |
|
| 31 |
<pre> |
| 32 |
--- |
| 33 |
title: My Great Novel |
| 34 |
author: John Doe |
| 35 |
copyright: Copyright © 2018 by John Doe |
| 36 |
version: 1.0 |
| 37 |
language: en-US |
| 38 |
subject: Fiction |
| 39 |
--- |
| 40 |
|
| 41 |
# Preamble |
| 42 |
|
| 43 |
... |
| 44 |
</pre> |
| 45 |
|
| 46 |
<p>HTMLDOC supports the "author", "copyright", "language", "subject", "title", and "version" metadata and silently ignores everything else.</p> |
| 47 |
|
| 48 |
|
| 49 |
<h2>Link Targets and @ Links</h2> |
| 50 |
|
| 51 |
<p>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:</p> |
| 52 |
|
| 53 |
<pre> |
| 54 |
See [Screwing in a Light Bulb](@) for instructions on installing a |
| 55 |
light bulb. |
| 56 |
|
| 57 |
... |
| 58 |
|
| 59 |
# Screwing in a Light Bulb |
| 60 |
|
| 61 |
... |
| 62 |
</pre> |
| 63 |
|
| 64 |
<p>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:</p> |
| 65 |
|
| 66 |
<pre> |
| 67 |
<a href="#screwing-in-a-light-bulb"> ... </a> |
| 68 |
</pre> |
| 69 |
|
| 70 |
|
| 71 |
<!-- NEED 5in --> |
| 72 |
<h2>Table Syntax</h2> |
| 73 |
|
| 74 |
<p>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:</p> |
| 75 |
|
| 76 |
<pre> |
| 77 |
| Heading 1 | Heading 2 | Heading 3 | |
| 78 |
| --------- | --------- | --------- | |
| 79 |
| Cell 1,1 | Cell 1,2 | Cell 1,3 | |
| 80 |
| Cell 2,1 | Cell 2,2 | Cell 2,3 | |
| 81 |
| Cell 3,1 | Cell 3,2 | Cell 3,3 | |
| 82 |
</pre> |
| 83 |
|
| 84 |
<p>will produce:</p> |
| 85 |
|
| 86 |
<table border="1" cellpadding="2"> |
| 87 |
<thead> |
| 88 |
<tr><th bgcolor="#cccccc">Heading 1</th><th bgcolor="#cccccc">Heading 2</th><th bgcolor="#cccccc">Heading 3</th></tr> |
| 89 |
</thead> |
| 90 |
<tbody> |
| 91 |
<tr><td>Cell 1,1</td><td>Cell 1,2</td><td>Cell 1,3</td></tr> |
| 92 |
<tr><td>Cell 2,1</td><td>Cell 2,2</td><td>Cell 2,3</td></tr> |
| 93 |
<tr><td>Cell 3,1</td><td>Cell 3,2</td><td>Cell 3,3</td></tr> |
| 94 |
</tbody> |
| 95 |
</table> |
| 96 |
|
| 97 |
<p>The outer pipes can be omitted, for example:</p> |
| 98 |
|
| 99 |
<pre> |
| 100 |
Heading 1 | Heading 2 | Heading 3 |
| 101 |
--------- | --------- | --------- |
| 102 |
Cell 1,1 | Cell 1,2 | Cell 1,3 |
| 103 |
Cell 2,1 | Cell 2,2 | Cell 2,3 |
| 104 |
Cell 3,1 | Cell 3,2 | Cell 3,3 |
| 105 |
</pre> |
| 106 |
|
| 107 |
<p>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:<p> |
| 108 |
|
| 109 |
<pre> |
| 110 |
Left Alignment | Center Alignment | Right Alignment |
| 111 |
:------------- | :--------------: | --------------: |
| 112 |
Cell 1,1 | Cell 1,2 | 1 |
| 113 |
Cell 2,1 | Cell 2,2 | 12 |
| 114 |
Cell 3,1 | Cell 3,2 | 123 |
| 115 |
</pre> |
| 116 |
|
| 117 |
<p>will produce:</p> |
| 118 |
|
| 119 |
<table border="1" cellpadding="2"> |
| 120 |
<thead> |
| 121 |
<tr><th bgcolor="#cccccc">Left Alignment</th><th bgcolor="#cccccc">Center Alignment</th><th bgcolor="#cccccc">Right Alignment</th></tr> |
| 122 |
</thead> |
| 123 |
<tbody> |
| 124 |
<tr><td>Cell 1,1</td><td align="center">Cell 1,2</td><td align="right">1</td></tr> |
| 125 |
<tr><td>Cell 2,1</td><td align="center">Cell 2,2</td><td align="right">12</td></tr> |
| 126 |
<tr><td>Cell 3,1</td><td align="center">Cell 3,2</td><td align="right">123</td></tr> |
| 127 |
</tbody> |
| 128 |
</table> |
| 129 |
|
| 130 |
<p>Table columns do not need to be padded so that they line up - the following (less readable) example is perfectly valid:</p> |
| 131 |
|
| 132 |
<pre> |
| 133 |
Left Alignment|Center Alignment|Right Alignment |
| 134 |
:--|:--:|--: |
| 135 |
Cell 1,1|Cell 1,2|1 |
| 136 |
Cell 2,1|Cell 2,2|12 |
| 137 |
Cell 3,1|Cell 3,2|123 |
| 138 |
</pre> |
| 139 |
|
| 140 |
</div> |
| 141 |
</body> |
| 142 |
</html> |