1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
|
<!DOCTYPE html>
<!-- NOTE: Styling is based on the CommonMark specification template: -->
<!-- - https://github.com/commonmark/commonmark-spec/blob/master/tools/make_spec.lua -->
<!-- - https://github.com/commonmark/commonmark-spec/blob/master/tools/template.html -->
<!-- -->
<!-- NOTE: 'TODO:' comments will be followed up as task(s) on this issue: -->
<!-- - https://gitlab.com/gitlab-org/gitlab/-/issues/361241 -->
<html lang="en">
<head>
<meta charset="UTF-8">
<title>GitLab Flavored Markdown Official Specification</title>
<style type="text/css">
body {
font-family: Helvetica, arial, freesans, clean, sans-serif;
line-height: 1.4;
max-width: 48em;
margin: auto;
padding: 0 0.5em 4em;
color: #333333;
background-color: #ffffff;
font-size: 13pt;
}
div#TOC ul { list-style: none; }
h1 {
font-size: 140%;
font-weight: bold;
border-top: 1px solid gray;
padding-top: 0.5em;
}
h2 {
font-size: 120%;
font-weight: bold;
}
h3 {
font-size: 110%;
font-weight: bold;
}
h4 {
font-size: 100%;
font-weight: bold;
}
/* NOTE: "font-weight: bold" was applied to "a.definition" class in original CommonMark */
/* template, but in practice it was applied to all anchors */
a {
font-weight: bold;
}
/* TODO: Format whitespace in examples. This will require preprocessing to insert spans around them. */
/*span.space { position: relative; }*/
/*span.space:after {*/
/* content: "·";*/
/* position: absolute;*/
/* !* create a mark that indicates a space (trick from D. Greenspan) *!*/
/* top: 0; bottom: 7px; left: 1px; right: 1px;*/
/* color: #aaaaaa;*/
/*}*/
/*@media print {*/
/* a.dingus { display: none; }*/
/*}*/
div.example {
overflow: hidden;
}
p {
text-align: justify;
}
pre {
padding: 0.5em;
margin: 0.2em 0 0.5em;
font-size: 88%;
}
pre {
white-space: pre-wrap; /* css-3 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
}
code {
font-family: monospace;
background-color: #d3e1e4;
}
pre > code {
background-color: transparent;
}
.example {
font-size: 0; /* hack to get width: 50% to work on inline-block */
padding-bottom: 6pt;
}
.column pre {
font-size: 11pt;
padding: 2pt 6pt;
}
div.examplenum {
font-size: 11pt;
text-align: left;
margin-bottom: 10px;
}
div.column {
display: inline-block;
width: 50%;
vertical-align: top;
}
div.example > div:nth-child(2) {
clear: left;
background-color: #d3e1e4;
}
div.example > div:nth-child(3) {
clear: right;
background-color: #c9cace;
}
@media print {
@page {
size: auto;
margin: 1.2in 1.2in 1.2in 1.2in;
}
body {
margin: 0;
line-height: 1.2;
font-size: 10pt;
}
.column pre {
font-size: 9pt;
}
div.examplenum {
font-size: 9pt;
}
}
</style>
<!-- TODO: Extract this javascript out to a separate file and unit test it -->
<script type="text/javascript">
/* NOTE: The following code performs many of the pre-processing steps originally handled */
/* in https://github.com/commonmark/commonmark-spec/blob/master/tools/make_spec.lua */
/* Adds a div.example wrapper around each pair of example code blocks. */
function addAttributesToExampleWrapperDivs() {
const exampleAnchorTags = document.querySelectorAll("a[href^=\"#example-\"]");
for (const exampleAnchorTag of exampleAnchorTags) {
const examplenumDiv = exampleAnchorTag.parentElement;
examplenumDiv.classList.add("examplenum");
const exampleDiv = examplenumDiv.parentElement;
exampleDiv.classList.add("example");
exampleDiv.id = exampleAnchorTag.getAttribute("href").substring(1);
}
}
function addColumnClassToMarkdownDivs() {
const markdownCodeBlockDivs = document.querySelectorAll("div.markdown-code-block");
for (const markdownCodeBlockDiv of markdownCodeBlockDivs) {
markdownCodeBlockDiv.classList.add("column");
}
}
function addNumbersToHeaders() {
const headers = document.querySelectorAll('h1,h2,h3');
let h1Index = -1; // NOTE: -1 because we don't assign a number to the title
let h2Index = 0;
let h3Index = 0;
const tocEntries = [];
for (const header of headers) {
if (h1Index === -1) {
h1Index++;
continue;
}
const originalHeaderTextContent = header.textContent.trim();
const headerAnchor = originalHeaderTextContent.toLowerCase().replaceAll(' ', '-');
header.id = headerAnchor;
let indent;
let headerTextContent;
if (header.tagName === 'H1') {
h1Index++;
h2Index = 0;
h3Index = 0;
header.textContent = headerTextContent = h1Index + ' ' + originalHeaderTextContent;
indent = 0;
} else if (header.tagName === 'H2') {
h2Index++;
h3Index = 0;
header.textContent =
headerTextContent = h1Index + '.' + h2Index + ' ' + originalHeaderTextContent;
indent = 1;
} else if (header.tagName === 'H3') {
h3Index++;
header.textContent = headerTextContent =
h1Index + '.' + h2Index + '.' + h3Index + ' ' + originalHeaderTextContent;
indent = 2;
}
tocEntries.push({headerAnchor, headerTextContent, indent});
}
}
document.addEventListener("DOMContentLoaded", function(_event) {
addAttributesToExampleWrapperDivs();
addColumnClassToMarkdownDivs();
const tocEntries = addNumbersToHeaders();
addToc(tocEntries);
});
/* NOTE: The following code is to support the "Try it" interactive "dingus", which */
/* we do not yet support. But it is being left here for comparison context with the */
/* original CommonMark template. */
// $$(document).ready(function() {
// $$("div.example").each(function(e) {
// var t = $$(this).find('code.language-markdown').text();
// $$(this).find('a.dingus').click(function(f) {
// window.open('/dingus/?text=' +
// encodeURIComponent(t.replace(/→/g,"\t")));
// });
// });
// $$("code.language-markdown").dblclick(function(e) { window.open('/dingus/?text=' +
// encodeURIComponent($$(this).text()));
// });
// });
</script>
</head>
<body>
<h1 class="title">GitLab Flavored Markdown Official Specification</h1>
<div class="version">Version alpha</div>
<ul class="section-nav">
<li><a href="#introduction">Introduction</a></li>
<li>
<a href="#gitlab-official-specification-markdown">GitLab Official Specification Markdown</a><ul>
<li><a href="#task-list-items">Task list items</a></li>
<li><a href="#front-matter">Front matter</a></li>
<li><a href="#table-of-contents">Table of contents</a></li>
</ul>
</li>
</ul>
<hr data-sourcepos="3:1-3:3">
<p data-sourcepos="4:1-6:3" dir="auto">title: GitLab Flavored Markdown (GLFM) Spec
version: alpha
...</p>
<h1 data-sourcepos="8:1-8:14" dir="auto">
<a id="user-content-introduction" class="anchor" href="#introduction" aria-hidden="true"></a>Introduction</h1>
<p data-sourcepos="10:1-10:284" dir="auto">GitLab Flavored Markdown (GLFM) extends the <a href="https://spec.commonmark.org/current/" rel="nofollow noreferrer noopener" target="_blank">CommonMark specification</a> and is considered a strict superset of CommonMark. It also incorporates the extensions defined by the <a href="https://github.github.com/gfm/" rel="nofollow noreferrer noopener" target="_blank">GitHub Flavored Markdown specification</a>.</p>
<p data-sourcepos="12:1-12:433" dir="auto">This specification will define the various official extensions that comprise GLFM. These extensions are GitLab independent - they do not require a GitLab server for parsing or interaction. The intent is to provide a specification that can be implemented in standard markdown editors. This includes many of the features listed in <a href="https://docs.gitlab.com/ee/user/markdown.html" rel="nofollow noreferrer noopener" target="_blank">user-facing documentation for GitLab Flavored Markdown</a>.</p>
<p data-sourcepos="14:1-14:69" dir="auto">The CommonMark and GitHub specifications will not be duplicated here.</p>
<p data-sourcepos="16:1-19:75" dir="auto">NOTE: The example numbering in this document does not start at "1", because this official specification
only contains a subset of all the examples which are supported by GitLab Flavored Markdown. See
<a href="https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output_example_snapshots/snapshot_spec.html" rel="nofollow noreferrer noopener" target="_blank"><code>snapshot_spec.html</code></a>
for a complete list of all examples, which are a superset of examples from:</p>
<ul data-sourcepos="21:1-25:0" dir="auto">
<li data-sourcepos="21:1-21:12">CommonMark</li>
<li data-sourcepos="22:1-22:26">GitHub Flavored Markdown</li>
<li data-sourcepos="23:1-23:88">GitLab Flavored Markdown Official Specification (the same ones from this specifiation)</li>
<li data-sourcepos="24:1-25:0">GitLab Flavored Markdown Internal Extensions.</li>
</ul>
<h1 data-sourcepos="27:1-27:40" dir="auto">
<a id="user-content-gitlab-official-specification-markdown" class="anchor" href="#gitlab-official-specification-markdown" aria-hidden="true"></a>GitLab Official Specification Markdown</h1>
<p data-sourcepos="29:1-31:104" dir="auto">Note: This specification is a work in progress. Only some of the official GLFM extensions
are defined. We will continue to add any additional ones found in the
<a href="https://docs.gitlab.com/ee/user/markdown.html" rel="nofollow noreferrer noopener" target="_blank">user-facing documentation for GitLab Flavored Markdown</a>.</p>
<p data-sourcepos="33:1-34:69" dir="auto">There is currently only this single top-level heading, but the
examples may be split into multiple top-level headings in the future.</p>
<h2 data-sourcepos="36:1-36:18" dir="auto">
<a id="user-content-task-list-items" class="anchor" href="#task-list-items" aria-hidden="true"></a>Task list items</h2>
<p data-sourcepos="38:1-39:117" dir="auto">See
<a href="https://docs.gitlab.com/ee/user/markdown.html#task-lists" rel="nofollow noreferrer noopener" target="_blank">Task lists</a> in the GitLab Flavored Markdown documentation.</p>
<p data-sourcepos="41:1-44:39" dir="auto">Task list items (checkboxes) are defined as a GitHub Flavored Markdown extension in a section above.
GitLab extends the behavior of task list items to support additional features.
Some of these features are in-progress, and should not yet be considered part of the official
GitLab Flavored Markdown specification.</p>
<p data-sourcepos="46:1-46:85" dir="auto">Some of the behavior of task list items is implemented as client-side JavaScript/CSS.</p>
<p data-sourcepos="48:1-48:80" dir="auto">The following are some basic examples; more examples may be added in the future.</p>
<p data-sourcepos="50:1-50:16" dir="auto">Incomplete task:</p>
<div>
<div><a href="#example-674">Example 674</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="55:1-57:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [ ] incomplete</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="59:1-67:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span>
<span id="LC2" class="line" lang="plaintext"><li></span>
<span id="LC3" class="line" lang="plaintext"><task-button/></span>
<span id="LC4" class="line" lang="plaintext"><input type="checkbox" disabled/></span>
<span id="LC5" class="line" lang="plaintext">incomplete</span>
<span id="LC6" class="line" lang="plaintext"></li></span>
<span id="LC7" class="line" lang="plaintext"></ul></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="70:1-70:15" dir="auto">Completed task:</p>
<div>
<div><a href="#example-675">Example 675</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="75:1-77:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [x] completed</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="79:1-87:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span>
<span id="LC2" class="line" lang="plaintext"><li></span>
<span id="LC3" class="line" lang="plaintext"><task-button/></span>
<span id="LC4" class="line" lang="plaintext"><input type="checkbox" checked disabled/></span>
<span id="LC5" class="line" lang="plaintext">completed</span>
<span id="LC6" class="line" lang="plaintext"></li></span>
<span id="LC7" class="line" lang="plaintext"></ul></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="90:1-90:18" dir="auto">Inapplicable task:</p>
<div>
<div><a href="#example-676">Example 676</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="95:1-97:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [~] inapplicable</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="99:1-109:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span>
<span id="LC2" class="line" lang="plaintext"><li></span>
<span id="LC3" class="line" lang="plaintext"><task-button/></span>
<span id="LC4" class="line" lang="plaintext"><input type="checkbox" data-inapplicable disabled></span>
<span id="LC5" class="line" lang="plaintext"><s></span>
<span id="LC6" class="line" lang="plaintext">inapplicable</span>
<span id="LC7" class="line" lang="plaintext"></s></span>
<span id="LC8" class="line" lang="plaintext"></li></span>
<span id="LC9" class="line" lang="plaintext"></ul></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="112:1-113:50" dir="auto">Inapplicable task in a "loose" list. Note that the <code><del></code> tag is not applied to the
loose text; it has strikethrough applied with CSS.</p>
<div>
<div><a href="#example-677">Example 677</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="118:1-122:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [~] inapplicable</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"> text in loose list</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="124:1-139:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span>
<span id="LC2" class="line" lang="plaintext"><li></span>
<span id="LC3" class="line" lang="plaintext"><p></span>
<span id="LC4" class="line" lang="plaintext"><task-button/></span>
<span id="LC5" class="line" lang="plaintext"><input type="checkbox" data-inapplicable disabled></span>
<span id="LC6" class="line" lang="plaintext"><s></span>
<span id="LC7" class="line" lang="plaintext">inapplicable</span>
<span id="LC8" class="line" lang="plaintext"></s></span>
<span id="LC9" class="line" lang="plaintext"></p></span>
<span id="LC10" class="line" lang="plaintext"><p></span>
<span id="LC11" class="line" lang="plaintext">text in loose list</span>
<span id="LC12" class="line" lang="plaintext"></p></span>
<span id="LC13" class="line" lang="plaintext"></li></span>
<span id="LC14" class="line" lang="plaintext"></ul></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<h2 data-sourcepos="142:1-142:15" dir="auto">
<a id="user-content-front-matter" class="anchor" href="#front-matter" aria-hidden="true"></a>Front matter</h2>
<p data-sourcepos="144:1-145:121" dir="auto">See
<a href="https://docs.gitlab.com/ee/user/markdown.html#front-matter" rel="nofollow noreferrer noopener" target="_blank">Front matter</a> in the GitLab Flavored Markdown documentation.</p>
<p data-sourcepos="147:1-148:95" dir="auto">Front matter is metadata included at the beginning of a Markdown document, preceding the content.
This data can be used by static site generators like Jekyll, Hugo, and many other applications.</p>
<p data-sourcepos="150:1-150:18" dir="auto">YAML front matter:</p>
<div>
<div><a href="#example-678">Example 678</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="155:1-159:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">---</span>
<span id="LC2" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC3" class="line" lang="plaintext">---</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="161:1-167:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><pre></span>
<span id="LC2" class="line" lang="plaintext"><code></span>
<span id="LC3" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC4" class="line" lang="plaintext"></code></span>
<span id="LC5" class="line" lang="plaintext"></pre></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="170:1-170:18" dir="auto">TOML front matter:</p>
<div>
<div><a href="#example-679">Example 679</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="175:1-179:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">+++</span>
<span id="LC2" class="line" lang="plaintext">title: TOML front matter</span>
<span id="LC3" class="line" lang="plaintext">+++</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="181:1-187:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><pre></span>
<span id="LC2" class="line" lang="plaintext"><code></span>
<span id="LC3" class="line" lang="plaintext">title: TOML front matter</span>
<span id="LC4" class="line" lang="plaintext"></code></span>
<span id="LC5" class="line" lang="plaintext"></pre></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="190:1-190:18" dir="auto">JSON front matter:</p>
<div>
<div><a href="#example-680">Example 680</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="195:1-201:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">;;;</span>
<span id="LC2" class="line" lang="plaintext">{</span>
<span id="LC3" class="line" lang="plaintext"> "title": "JSON front matter"</span>
<span id="LC4" class="line" lang="plaintext">}</span>
<span id="LC5" class="line" lang="plaintext">;;;</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="203:1-211:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><pre></span>
<span id="LC2" class="line" lang="plaintext"><code></span>
<span id="LC3" class="line" lang="plaintext">{</span>
<span id="LC4" class="line" lang="plaintext"> "title": "JSON front matter"</span>
<span id="LC5" class="line" lang="plaintext">}</span>
<span id="LC6" class="line" lang="plaintext"></code></span>
<span id="LC7" class="line" lang="plaintext"></pre></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="214:1-214:66" dir="auto">Front matter blocks should be inserted at the top of the document:</p>
<div>
<div><a href="#example-681">Example 681</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="219:1-225:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">text</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext">---</span>
<span id="LC4" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC5" class="line" lang="plaintext">---</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="227:1-231:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><p>text</p></span>
<span id="LC2" class="line" lang="plaintext"><hr></span>
<span id="LC3" class="line" lang="plaintext"><h2>title: YAML front matter</h2></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="234:1-234:74" dir="auto">Front matter block delimiters shouldn’t be preceded by space characters:</p>
<div>
<div><a href="#example-682">Example 682</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="239:1-243:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"> ---</span>
<span id="LC2" class="line" lang="plaintext">title: YAML front matter</span>
<span id="LC3" class="line" lang="plaintext">---</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="245:1-248:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><hr></span>
<span id="LC2" class="line" lang="plaintext"><h2>title: YAML front matter</h2></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<h2 data-sourcepos="251:1-251:20" dir="auto">
<a id="user-content-table-of-contents" class="anchor" href="#table-of-contents" aria-hidden="true"></a>Table of contents</h2>
<p data-sourcepos="253:1-255:46" dir="auto">See
<a href="https://docs.gitlab.com/ee/user/markdown.html#table-of-contents" rel="nofollow noreferrer noopener" target="_blank">table of contents</a>
in the GitLab Flavored Markdown documentation.</p>
<p data-sourcepos="257:1-261:23" dir="auto">NOTE: Because of this bug (<a href="https://gitlab.com/gitlab-org/gitlab/-/issues/359077" rel="nofollow noreferrer noopener" target="_blank">https://gitlab.com/gitlab-org/gitlab/-/issues/359077</a>),
we cannot actually include the <code>TOC</code> tag with single brackets in backticks
in this Markdown document, otherwise it would render a table of contents inline
right here. So, it's been switched to <code>[</code> + <code>TOC</code> + <code>]</code> instead. This can be reverted
once that bug is fixed.</p>
<p data-sourcepos="263:1-264:76" dir="auto">A table of contents is an unordered list that links to subheadings in the document.
Add either the <code>[[_TOC_]]</code> tag or the <code>[</code> + <code>TOC</code> + <code>]</code> tag on its own line.</p>
<div>
<div><a href="#example-683">Example 683</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="269:1-275:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[TOC]</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"># Heading 1</span>
<span id="LC4" class="line" lang="plaintext"></span>
<span id="LC5" class="line" lang="plaintext">## Heading 2</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="277:1-288:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><nav></span>
<span id="LC2" class="line" lang="plaintext"> <ul></span>
<span id="LC3" class="line" lang="plaintext"> <li><a href="#heading-1">Heading 1</a></li></span>
<span id="LC4" class="line" lang="plaintext"> <ul></span>
<span id="LC5" class="line" lang="plaintext"> <li><a href="#heading-2">Heading 2</a></li></span>
<span id="LC6" class="line" lang="plaintext"> </ul></span>
<span id="LC7" class="line" lang="plaintext"> </ul></span>
<span id="LC8" class="line" lang="plaintext"></nav></span>
<span id="LC9" class="line" lang="plaintext"><h1>Heading 1</h1></span>
<span id="LC10" class="line" lang="plaintext"><h2>Heading 2</h2></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<div>
<div><a href="#example-684">Example 684</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="294:1-300:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[[_TOC_]]</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"># Heading 1</span>
<span id="LC4" class="line" lang="plaintext"></span>
<span id="LC5" class="line" lang="plaintext">## Heading 2</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="302:1-313:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><nav></span>
<span id="LC2" class="line" lang="plaintext"> <ul></span>
<span id="LC3" class="line" lang="plaintext"> <li><a href="#heading-1">Heading 1</a></li></span>
<span id="LC4" class="line" lang="plaintext"> <ul></span>
<span id="LC5" class="line" lang="plaintext"> <li><a href="#heading-2">Heading 2</a></li></span>
<span id="LC6" class="line" lang="plaintext"> </ul></span>
<span id="LC7" class="line" lang="plaintext"> </ul></span>
<span id="LC8" class="line" lang="plaintext"></nav></span>
<span id="LC9" class="line" lang="plaintext"><h1>Heading 1</h1></span>
<span id="LC10" class="line" lang="plaintext"><h2>Heading 2</h2></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="316:1-317:5" dir="auto">A table of contents is a block element. It should preceded and followed by a blank
line.</p>
<div>
<div><a href="#example-685">Example 685</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="322:1-328:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[[_TOC_]]</span>
<span id="LC2" class="line" lang="plaintext">text</span>
<span id="LC3" class="line" lang="plaintext"></span>
<span id="LC4" class="line" lang="plaintext">text</span>
<span id="LC5" class="line" lang="plaintext">[TOC]</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="330:1-333:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><p>[[<em>TOC</em>]]text</p></span>
<span id="LC2" class="line" lang="plaintext"><p>text[TOC]</p></span></code></pre>
<copy-code></copy-code>
</div>
</div>
<p data-sourcepos="336:1-336:60" dir="auto">A table of contents can be indented with up to three spaces.</p>
<div>
<div><a href="#example-686">Example 686</a></div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="341:1-345:32" data-canonical-lang="example" data-lang-params="gitlab" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"> [[_TOC_]]</span>
<span id="LC2" class="line" lang="plaintext"></span>
<span id="LC3" class="line" lang="plaintext"># Heading 1</span></code></pre>
<copy-code></copy-code>
</div>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-sourcepos="347:1-354:32" class="code highlight js-syntax-highlight language-plaintext" lang="plaintext" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><nav></span>
<span id="LC2" class="line" lang="plaintext"> <ul></span>
<span id="LC3" class="line" lang="plaintext"> <li><a href="#heading-1">Heading 1</a></li></span>
<span id="LC4" class="line" lang="plaintext"> </ul></span>
<span id="LC5" class="line" lang="plaintext"></nav></span>
<span id="LC6" class="line" lang="plaintext"><h1>Heading 1</h1></span></code></pre>
<copy-code></copy-code>
</div>
</div>
</body>
</html>
|