tables.txt (6072B)
1
2 # Tables
3
4 With the flag `MD_FLAG_TABLES`, MD4C enables extension for recognition of
5 tables.
6
7 Basic table example of a table with two columns and three lines (when not
8 counting the header) is as follows:
9
10 ```````````````````````````````` example
11 | Column 1 | Column 2 |
12 |----------|----------|
13 | foo | bar |
14 | baz | qux |
15 | quux | quuz |
16 .
17 <table>
18 <thead>
19 <tr><th>Column 1</th><th>Column 2</th></tr>
20 </thead>
21 <tbody>
22 <tr><td>foo</td><td>bar</td></tr>
23 <tr><td>baz</td><td>qux</td></tr>
24 <tr><td>quux</td><td>quuz</td></tr>
25 </tbody>
26 </table>
27 ````````````````````````````````
28
29 The leading and succeeding pipe characters (`|`) on each line are optional:
30
31 ```````````````````````````````` example
32 Column 1 | Column 2 |
33 ---------|--------- |
34 foo | bar |
35 baz | qux |
36 quux | quuz |
37 .
38 <table>
39 <thead>
40 <tr><th>Column 1</th><th>Column 2</th></tr>
41 </thead>
42 <tbody>
43 <tr><td>foo</td><td>bar</td></tr>
44 <tr><td>baz</td><td>qux</td></tr>
45 <tr><td>quux</td><td>quuz</td></tr>
46 </tbody>
47 </table>
48 ````````````````````````````````
49
50 ```````````````````````````````` example
51 | Column 1 | Column 2
52 |----------|---------
53 | foo | bar
54 | baz | qux
55 | quux | quuz
56 .
57 <table>
58 <thead>
59 <tr><th>Column 1</th><th>Column 2</th></tr>
60 </thead>
61 <tbody>
62 <tr><td>foo</td><td>bar</td></tr>
63 <tr><td>baz</td><td>qux</td></tr>
64 <tr><td>quux</td><td>quuz</td></tr>
65 </tbody>
66 </table>
67 ````````````````````````````````
68
69 ```````````````````````````````` example
70 Column 1 | Column 2
71 ---------|---------
72 foo | bar
73 baz | qux
74 quux | quuz
75 .
76 <table>
77 <thead>
78 <tr><th>Column 1</th><th>Column 2</th></tr>
79 </thead>
80 <tbody>
81 <tr><td>foo</td><td>bar</td></tr>
82 <tr><td>baz</td><td>qux</td></tr>
83 <tr><td>quux</td><td>quuz</td></tr>
84 </tbody>
85 </table>
86 ````````````````````````````````
87
88 However for one-column table, at least one of those has to be used, otherwise
89 it would be parsed as a Setext title followed by paragraph.
90
91 ```````````````````````````````` example
92 Column 1
93 --------
94 foo
95 baz
96 quux
97 .
98 <h2>Column 1</h2>
99 <p>foo
100 baz
101 quux</p>
102 ````````````````````````````````
103
104 Leading and trailing whitespace in a table cell is ignored and the columns do
105 not need to be aligned.
106
107 ```````````````````````````````` example
108 Column 1 |Column 2
109 ---|---
110 foo | bar
111 baz| qux
112 quux|quuz
113 .
114 <table>
115 <thead>
116 <tr><th>Column 1</th><th>Column 2</th></tr>
117 </thead>
118 <tbody>
119 <tr><td>foo</td><td>bar</td></tr>
120 <tr><td>baz</td><td>qux</td></tr>
121 <tr><td>quux</td><td>quuz</td></tr>
122 </tbody>
123 </table>
124 ````````````````````````````````
125
126 The table cannot interrupt a paragraph.
127
128 ```````````````````````````````` example
129 Lorem ipsum dolor sit amet.
130 | Column 1 | Column 2
131 | ---------|---------
132 | foo | bar
133 | baz | qux
134 | quux | quuz
135 .
136 <p>Lorem ipsum dolor sit amet.
137 | Column 1 | Column 2
138 | ---------|---------
139 | foo | bar
140 | baz | qux
141 | quux | quuz</p>
142 ````````````````````````````````
143
144 But paragraph or other block can interrupt a table as a line without any pipe
145 ends the table.
146
147 ```````````````````````````````` example
148 Column 1 | Column 2
149 ---------|---------
150 foo | bar
151 baz | qux
152 quux | quuz
153 Lorem ipsum dolor sit amet.
154 .
155 <table>
156 <thead>
157 <tr><th>Column 1</th><th>Column 2</th></tr>
158 </thead>
159 <tbody>
160 <tr><td>foo</td><td>bar</td></tr>
161 <tr><td>baz</td><td>qux</td></tr>
162 <tr><td>quux</td><td>quuz</td></tr>
163 </tbody>
164 </table>
165 <p>Lorem ipsum dolor sit amet.</p>
166 ````````````````````````````````
167
168 The ruling line between head and body of the table must include the same amount
169 of cells as the line with column names, and each cell has to consist of three
170 dash (`-`) characters. However first, last or both dashes may be replaced with
171 colon to denote column alignment.
172
173 Thus this is not a table because there are too few dashes for Column 2.
174
175 ```````````````````````````````` example
176 | Column 1 | Column 2
177 | ---------|--
178 | foo | bar
179 | baz | qux
180 | quux | quuz
181 .
182 <p>| Column 1 | Column 2
183 | ---------|--
184 | foo | bar
185 | baz | qux
186 | quux | quuz</p>
187 ````````````````````````````````
188
189 And this is a table where each of the four column uses different alignment.
190
191 ```````````````````````````````` example
192 | Column 1 | Column 2 | Column 3 | Column 4 |
193 |----------|:---------|:--------:|---------:|
194 | default | left | center | right |
195 .
196 <table>
197 <thead>
198 <tr><th>Column 1</th><th align="left">Column 2</th><th align="center">Column 3</th><th align="right">Column 4</th></tr>
199 </thead>
200 <tbody>
201 <tr><td>default</td><td align="left">left</td><td align="center">center</td><td align="right">right</td></tr>
202 </tbody>
203 </table>
204 ````````````````````````````````
205
206 To include a literal pipe character in any cell, it has to be escaped.
207
208 ```````````````````````````````` example
209 Column 1 | Column 2
210 ---------|---------
211 foo | bar
212 baz | qux \| xyzzy
213 quux | quuz
214 .
215 <table>
216 <thead>
217 <tr><th>Column 1</th><th>Column 2</th></tr>
218 </thead>
219 <tbody>
220 <tr><td>foo</td><td>bar</td></tr>
221 <tr><td>baz</td><td>qux | xyzzy</td></tr>
222 <tr><td>quux</td><td>quuz</td></tr>
223 </tbody>
224 </table>
225 ````````````````````````````````
226
227 Contents of each cell is parsed as an inline text which may contents any
228 inline Markdown spans like emphasis, strong emphasis, links etc.
229
230 ```````````````````````````````` example
231 Column 1 | Column 2
232 ---------|---------
233 *foo* | bar
234 **baz** | [qux]
235 quux | [quuz](/url2)
236
237 [qux]: /url
238 .
239 <table>
240 <thead>
241 <tr><th>Column 1</th><th>Column 2</th></tr>
242 </thead>
243 <tbody>
244 <tr><td><em>foo</em></td><td>bar</td></tr>
245 <tr><td><strong>baz</strong></td><td><a href="/url">qux</a></td></tr>
246 <tr><td>quux</td><td><a href="/url2">quuz</a></td></tr>
247 </tbody>
248 </table>
249 ````````````````````````````````
250
251 However pipes which are inside a link, an image or a code span are not
252 recognized as cell boundaries.
253
254 ```````````````````````````````` example
255 Column 1 | [|](/url)
256 ---------|---------
257 `foo | bar`
258 baz | qux
259 quux | quuz
260 .
261 <table>
262 <thead>
263 <tr><th>Column 1</th><th><a href="/url">|</a></th></tr>
264 </thead>
265 <tbody>
266 </tbody>
267 </table>
268 <p><code>foo | bar</code>
269 baz | qux
270 quux | quuz</p>
271
272 ````````````````````````````````