diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-11-22 21:07:57 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-11-22 21:07:57 +0300 |
| commit | 277c0c75bf32b40d882c35feafaae90f69c40dd9 (patch) | |
| tree | 35f3969f59c1886fcfa71812cb2b942c46d9dffe /glfm_specification/output_spec | |
| parent | 5e44c2ba46e780552317dec29e3b51282dfd5696 (diff) | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'glfm_specification/output_spec')
| -rw-r--r-- | glfm_specification/output_spec/spec.html | 443 | ||||
| -rw-r--r-- | glfm_specification/output_spec/spec.txt | 20 |
2 files changed, 388 insertions, 75 deletions
diff --git a/glfm_specification/output_spec/spec.html b/glfm_specification/output_spec/spec.html index a10b7f91d91..525c21a6ad1 100644 --- a/glfm_specification/output_spec/spec.html +++ b/glfm_specification/output_spec/spec.html @@ -1,32 +1,290 @@ -<div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="1:1-4:3" lang="yaml" class="code highlight js-syntax-highlight language-yaml" data-lang-params="frontmatter" v-pre="true"><code><span id="LC1" class="line" lang="yaml"><span class="na">title</span><span class="pi">:</span> <span class="s">GitLab Flavored Markdown (GLFM) Spec</span></span> -<span id="LC2" class="line" lang="yaml"><span class="na">version</span><span class="pi">:</span> <span class="s">alpha</span></span></code></pre> -<copy-code></copy-code> -</div> -<h1 data-sourcepos="5:1-5:14" dir="auto"> +<!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="#footnotes">Footnotes</a></li> +<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> +<h1 data-sourcepos="3:1-3:14" dir="auto"> <a id="user-content-introduction" class="anchor" href="#introduction" aria-hidden="true"></a>Introduction</h1> -<p data-sourcepos="7:1-7:84" dir="auto">TODO: Write a GitLab-specific version of the GitHub Flavored Markdown intro section.</p> +<p data-sourcepos="5:1-5:84" dir="auto">TODO: Write a GitLab-specific version of the GitHub Flavored Markdown intro section.</p> +<p data-sourcepos="7:1-10: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="12:1-16:0" dir="auto"> +<li data-sourcepos="12:1-12:12">CommonMark</li> +<li data-sourcepos="13:1-13:26">GitHub Flavored Markdown</li> +<li data-sourcepos="14:1-14:88">GitLab Flavored Markdown Official Specification (the same ones from this specifiation)</li> +<li data-sourcepos="15:1-16:0">GitLab Flavored Markdown Internal Extensions.</li> +</ul> -<h1 data-sourcepos="10:1-10:40" dir="auto"> +<h1 data-sourcepos="18:1-18: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="12:1-15:104" dir="auto">Currently, only some of the GitLab-specific markdown features are +<p data-sourcepos="20:1-23:104" dir="auto">Currently, only some of the GitLab-specific markdown features are listed in this section. We may eventually add all GitLab-specific features currently listed as supported 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="17:1-18:69" dir="auto">There is currently only this single top-level heading, but the +<p data-sourcepos="25:1-26: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="20:1-20:12" dir="auto"> +<h2 data-sourcepos="28:1-28:12" dir="auto"> <a id="user-content-footnotes" class="anchor" href="#footnotes" aria-hidden="true"></a>Footnotes</h2> -<p data-sourcepos="22:1-23:143" dir="auto">See +<p data-sourcepos="30:1-31:143" dir="auto">See <a href="https://docs.gitlab.com/ee/user/markdown.html#footnotes" rel="nofollow noreferrer noopener" target="_blank">the footnotes section of the user-facing documentation for GitLab Flavored Markdown</a>.</p> +<div> +<div><a href="#example-674">Example 674</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="25:1-29:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">footnote reference tag [^fortytwo]</span> +<pre data-sourcepos="36:1-40:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">footnote reference tag [^fortytwo]</span> <span id="LC2" class="line" lang="plaintext"></span> <span id="LC3" class="line" lang="plaintext">[^fortytwo]: footnote text</span></code></pre> <copy-code></copy-code> </div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="31:1-51:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><p></span> +<pre data-sourcepos="42:1-62:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><p></span> <span id="LC2" class="line" lang="plaintext">footnote reference tag</span> <span id="LC3" class="line" lang="plaintext"><sup></span> <span id="LC4" class="line" lang="plaintext"><a href="#fn-fortytwo-42" id="fnref-fortytwo-42" data-footnote-ref></span> @@ -47,23 +305,26 @@ examples may be split into multiple top-level headings in the future.</p> <span id="LC19" class="line" lang="plaintext"></section></span></code></pre> <copy-code></copy-code> </div> -<h2 data-sourcepos="53:1-53:18" dir="auto"> +</div> +<h2 data-sourcepos="65:1-65: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="55:1-56:117" dir="auto">See +<p data-sourcepos="67:1-68: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="58:1-61:39" dir="auto">Task list items (checkboxes) are defined as a GitHub Flavored Markdown extension in a section above. +<p data-sourcepos="70:1-73: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="63:1-63:85" dir="auto">Some of the behavior of task list items is implemented as client-side JavaScript/CSS.</p> -<p data-sourcepos="65:1-65:80" dir="auto">The following are some basic examples; more examples may be added in the future.</p> -<p data-sourcepos="67:1-67:16" dir="auto">Incomplete task:</p> +<p data-sourcepos="75:1-75:85" dir="auto">Some of the behavior of task list items is implemented as client-side JavaScript/CSS.</p> +<p data-sourcepos="77:1-77:80" dir="auto">The following are some basic examples; more examples may be added in the future.</p> +<p data-sourcepos="79:1-79:16" dir="auto">Incomplete 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="69:1-71:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [ ] incomplete</span></code></pre> +<pre data-sourcepos="84:1-86:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="73:1-81:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span> +<pre data-sourcepos="88:1-96:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -72,13 +333,16 @@ GitLab Flavored Markdown specification.</p> <span id="LC7" class="line" lang="plaintext"></ul></span></code></pre> <copy-code></copy-code> </div> -<p data-sourcepos="83:1-83:15" dir="auto">Completed task:</p> +</div> +<p data-sourcepos="99:1-99:15" dir="auto">Completed 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="85:1-87:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [x] completed</span></code></pre> +<pre data-sourcepos="104:1-106:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="89:1-97:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span> +<pre data-sourcepos="108:1-116:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -87,13 +351,16 @@ GitLab Flavored Markdown specification.</p> <span id="LC7" class="line" lang="plaintext"></ul></span></code></pre> <copy-code></copy-code> </div> -<p data-sourcepos="99:1-99:18" dir="auto">Inapplicable task:</p> +</div> +<p data-sourcepos="119:1-119:18" dir="auto">Inapplicable task:</p> +<div> +<div><a href="#example-677">Example 677</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="101:1-103:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [~] inapplicable</span></code></pre> +<pre data-sourcepos="124:1-126:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="105:1-115:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span> +<pre data-sourcepos="128:1-138:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -104,16 +371,19 @@ GitLab Flavored Markdown specification.</p> <span id="LC9" class="line" lang="plaintext"></ul></span></code></pre> <copy-code></copy-code> </div> -<p data-sourcepos="117:1-118:50" dir="auto">Inapplicable task in a "loose" list. Note that the <code><del></code> tag is not applied to the +</div> +<p data-sourcepos="141:1-142: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-678">Example 678</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="120:1-124:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">- [~] inapplicable</span> +<pre data-sourcepos="147:1-151:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="126:1-141:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><ul></span> +<pre data-sourcepos="153:1-168:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -129,45 +399,54 @@ loose text; it has strikethrough applied with CSS.</p> <span id="LC14" class="line" lang="plaintext"></ul></span></code></pre> <copy-code></copy-code> </div> -<h2 data-sourcepos="143:1-143:15" dir="auto"> +</div> +<h2 data-sourcepos="171:1-171:15" dir="auto"> <a id="user-content-front-matter" class="anchor" href="#front-matter" aria-hidden="true"></a>Front matter</h2> -<p data-sourcepos="145:1-146:121" dir="auto">See +<p data-sourcepos="173:1-174: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="148:1-149:95" dir="auto">Front matter is metadata included at the beginning of a Markdown document, preceding the content. +<p data-sourcepos="176:1-177: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="151:1-151:18" dir="auto">YAML front matter:</p> +<p data-sourcepos="179:1-179:18" dir="auto">YAML 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="153:1-157:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">---</span> +<pre data-sourcepos="184:1-188:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="159:1-165:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><pre></span> +<pre data-sourcepos="190:1-196:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> -<p data-sourcepos="167:1-167:18" dir="auto">TOML front matter:</p> +</div> +<p data-sourcepos="199:1-199:18" dir="auto">TOML 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="169:1-173:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">+++</span> +<pre data-sourcepos="204:1-208:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="175:1-181:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><pre></span> +<pre data-sourcepos="210:1-216:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> -<p data-sourcepos="183:1-183:18" dir="auto">JSON front matter:</p> +</div> +<p data-sourcepos="219:1-219:18" dir="auto">JSON front matter:</p> +<div> +<div><a href="#example-681">Example 681</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="185:1-191:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">;;;</span> +<pre data-sourcepos="224:1-230:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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> @@ -175,7 +454,7 @@ This data can be used by static site generators like Jekyll, Hugo, and many othe <copy-code></copy-code> </div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="193:1-201:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><pre></span> +<pre data-sourcepos="232:1-240:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -184,9 +463,12 @@ This data can be used by static site generators like Jekyll, Hugo, and many othe <span id="LC7" class="line" lang="plaintext"></pre></span></code></pre> <copy-code></copy-code> </div> -<p data-sourcepos="203:1-203:66" dir="auto">Front matter blocks should be inserted at the top of the document:</p> +</div> +<p data-sourcepos="243:1-243:66" dir="auto">Front matter blocks should be inserted at the top of the document:</p> +<div> +<div><a href="#example-682">Example 682</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="205:1-211:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">text</span> +<pre data-sourcepos="248:1-254:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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> @@ -194,42 +476,43 @@ This data can be used by static site generators like Jekyll, Hugo, and many othe <copy-code></copy-code> </div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="213:1-217:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><p>text</p></span> +<pre data-sourcepos="256:1-260:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> -<p data-sourcepos="219:1-219:74" dir="auto">Front matter block delimiters shouldn’t be preceded by space characters:</p> +</div> +<p data-sourcepos="263:1-263:74" dir="auto">Front matter block delimiters shouldn’t be preceded by space characters:</p> +<div> +<div><a href="#example-683">Example 683</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="221:1-225:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"> ---</span> +<pre data-sourcepos="268:1-272:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="227:1-230:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><hr></span> +<pre data-sourcepos="274:1-277:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> -<h2 data-sourcepos="232:1-232:20" dir="auto"> +</div> +<h2 data-sourcepos="280:1-280: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="234:1-236:46" dir="auto">See +<p data-sourcepos="282:1-284: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="238:1-239:58" dir="auto">A table of contents is an unordered list that links to subheadings in the document. -Add either the <code>[[_TOC_]]</code> or </p><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="#footnotes">Footnotes</a></li> -<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> tag on its own line. +<p data-sourcepos="286:1-290: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="292:1-293: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-684">Example 684</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="241:1-247:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[TOC]</span> +<pre data-sourcepos="298:1-304:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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> @@ -237,7 +520,7 @@ Add either the <code>[[_TOC_]]</code> or </p><ul class="section-nav"> <copy-code></copy-code> </div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="249:1-260:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><nav></span> +<pre data-sourcepos="306:1-317:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -249,8 +532,11 @@ Add either the <code>[[_TOC_]]</code> or </p><ul class="section-nav"> <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-685">Example 685</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="262:1-268:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[[_TOC_]]</span> +<pre data-sourcepos="323:1-329:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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> @@ -258,7 +544,7 @@ Add either the <code>[[_TOC_]]</code> or </p><ul class="section-nav"> <copy-code></copy-code> </div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="270:1-281:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><nav></span> +<pre data-sourcepos="331:1-342:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -270,10 +556,13 @@ Add either the <code>[[_TOC_]]</code> or </p><ul class="section-nav"> <span id="LC10" class="line" lang="plaintext"><h2>Heading 2</h2></span></code></pre> <copy-code></copy-code> </div> -<p data-sourcepos="283:1-284:5" dir="auto">A table of contents is a block element. It should preceded and followed by a blank +</div> +<p data-sourcepos="345:1-346: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-686">Example 686</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="286:1-292:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext">[[_TOC_]]</span> +<pre data-sourcepos="351:1-357:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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> @@ -281,19 +570,22 @@ line.</p> <copy-code></copy-code> </div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="294:1-297:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><p>[[<em>TOC</em>]]text</p></span> +<pre data-sourcepos="359:1-362:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> -<p data-sourcepos="299:1-299:60" dir="auto">A table of contents can be indented with up to three spaces.</p> +</div> +<p data-sourcepos="365:1-365:60" dir="auto">A table of contents can be indented with up to three spaces.</p> +<div> +<div><a href="#example-687">Example 687</a></div> <div class="gl-relative markdown-code-block js-markdown-code"> -<pre data-sourcepos="301:1-305:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"> [[_TOC_]]</span> +<pre data-sourcepos="370:1-374:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="example" 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="307:1-314:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" v-pre="true"><code><span id="LC1" class="line" lang="plaintext"><nav></span> +<pre data-sourcepos="376:1-383:32" lang="plaintext" class="code highlight js-syntax-highlight language-plaintext" data-canonical-lang="" 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> @@ -301,4 +593,9 @@ line.</p> <span id="LC6" class="line" lang="plaintext"><h1>Heading 1</h1></span></code></pre> <copy-code></copy-code> </div> +</div> + + +</body> +</html> diff --git a/glfm_specification/output_spec/spec.txt b/glfm_specification/output_spec/spec.txt index e16975ac51f..350acea770c 100644 --- a/glfm_specification/output_spec/spec.txt +++ b/glfm_specification/output_spec/spec.txt @@ -1,11 +1,21 @@ --- -title: GitLab Flavored Markdown (GLFM) Spec +title: GitLab Flavored Markdown Official Specification version: alpha ... # Introduction TODO: Write a GitLab-specific version of the GitHub Flavored Markdown intro section. +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 +[`snapshot_spec.html`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output_example_snapshots/snapshot_spec.html) +for a complete list of all examples, which are a superset of examples from: + +- CommonMark +- GitHub Flavored Markdown +- GitLab Flavored Markdown Official Specification (the same ones from this specifiation) +- GitLab Flavored Markdown Internal Extensions. + <!-- BEGIN TESTS --> # GitLab Official Specification Markdown @@ -215,8 +225,14 @@ See [table of contents](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents) in the GitLab Flavored Markdown documentation. +NOTE: Because of this bug (https://gitlab.com/gitlab-org/gitlab/-/issues/359077), +we cannot actually include the `TOC` 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 `[` + `TOC` + `]` instead. This can be reverted +once that bug is fixed. + A table of contents is an unordered list that links to subheadings in the document. -Add either the `[[_TOC_]]` or `[TOC]` tag on its own line. +Add either the `[[_TOC_]]` tag or the `[` + `TOC` + `]` tag on its own line. ```````````````````````````````` example gitlab [TOC] |