Debian Codegraph @

doc/5-mdref.html

raw
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 &copy; 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 &lt;a href="#screwing-in-a-light-bulb"&gt; ... &lt;/a&gt;
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>