Add latest changes from gitlab-org/gitlab@master

1 files changed, 114 insertions, 42 deletions

diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md
index d1de666cb0f..5af642a52ce 100644
--- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md
+++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md
@@ -64,7 +64,7 @@ serve as input to automated conformance tests. It is
 [explained in the CommonMark specification](https://spec.commonmark.org/0.30/#about-this-document):
 
 > This document attempts to specify Markdown syntax unambiguously. It contains many
-> examples with side-by-side Markdown and HTML. These are intended to double as conformance tests.
+> examples with side-by-side Markdown and HTML. These examples are intended to double as conformance tests.
 
 The HTML-rendered versions of the specifications:
 
@@ -508,21 +508,76 @@ They are either downloaded, as in the case of the
 GFM `spec.txt` file, or manually
 updated, as in the case of all GFM files.
 
-- `glfm_specification/input/github_flavored_markdown/gfm_spec_v_0.29.txt` -
-  official latest [GFM spec.txt](https://github.com/github/cmark-gfm/blob/master/test/spec.txt),
-  automatically downloaded and updated by `update-specification.rb` script.
-- `glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt` -
-  Manually updated text of intro section for generated GLFM `spec.txt`.
-  - Replaces GFM version of introductory
-    section in `spec.txt`.
-- `glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt` -
-  Manually updated canonical Markdown+HTML examples for GLFM extensions.
-  - Standard backtick-delimited `spec.txt` examples format with Markdown + canonical HTML.
-  - Inserted as a new section before the appendix of generated `spec.txt`.
-- `glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml` -
-  Manually updated status of automatic generation of files based on Markdown
-  examples.
-  - Allows example snapshot generation, Markdown conformance tests, or
+##### GitHub Flavored Markdown specification
+
+[`glfm_specification/input/github_flavored_markdown/gfm_spec_v_0.29.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/github_flavored_markdown/gfm_spec_v_0.29.txt)
+is the official latest [GFM `spec.txt`](https://github.com/github/cmark-gfm/blob/master/test/spec.txt).
+
+- It is automatically downloaded and updated by `update-specification.rb` script.
+- When it is downloaded, the version number is added to the filename.
+
+##### `glfm_intro.txt`
+
+[`glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt)
+is the GitLab-specific version of the prose in the introduction section of the GLFM specification.
+
+- It is manually updated.
+- The `update-specification.rb` script inserts it into the generated GLFM `spec.txt` to replace
+  the GitHub-specific GFM version of the introductory section.
+
+##### `glfm_canonical_examples.txt`
+
+[`glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt)
+is the manually updated canonical Markdown+HTML examples for GLFM extensions.
+
+- It contains examples in the [standard backtick-delimited `spec.txt` format](#various-markdown-specifications),
+  each of which contain a Markdown example and the corresponding canonical HTML.
+- The `update-specification.rb` script inserts it as new sections before the appendix
+  of generated `spec.txt`.
+- It should consist of `H1` header sections, with a examples nested exactly 2 levels deep within `H2`
+  header sections.
+
+`glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt` sample entries:
+
+NOTE:
+All lines in this example are prefixed with a `|` character. This prefix helps avoid false
+errors when this file is checked by `markdownlint`, and possible errors in other Markdown editors.
+The actual file should not have these prefixed `|` characters.
+
+```plaintext
+|# First GitLab-Specific Section with Examples
+|
+|## Strong but with two asterisks
+|
+|```````````````````````````````` example
+|**bold**
+|.
+|<p><strong>bold</strong></p>
+|````````````````````````````````
+|
+|# Second GitLab-Specific Section with Examples
+|
+|## Strong but with HTML
+|
+|```````````````````````````````` example
+|<strong>
+|bold
+|</strong>
+|.
+|<p><strong>
+|bold
+|</strong></p>
+|````````````````````````````````
+```
+
+##### `glfm_example_status.yml`
+
+[`glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml)
+controls the behavior of the [scripts](#scripts) and [tests](#types-of-markdown-tests-driven-by-the-glfm-specification).
+
+- It is manually updated.
+- It controls the status of automatic generation of files based on Markdown examples.
+- It allows example snapshot generation, Markdown conformance tests, or
   Markdown snapshot tests to be skipped for individual examples. For example, if
   they are unimplemented, broken, or cannot be tested for some reason.
 
@@ -545,28 +600,39 @@ updated, as in the case of all GFM files.
 The `glfm_specification/output` directory contains the CommonMark standard format
 `spec.txt` file which represents the canonical GLFM specification which is generated
 by the `update-specification.rb` script. It also contains the rendered `spec.html`
-and `spec.pdf` which are generated from with the `spec.txt` as input.
-
-- `glfm_specification/output/spec.txt` - A Markdown file, in the standard format
-  with prose and Markdown + canonical HTML examples, generated (or updated) by the
-  `update-specification.rb` script.
-- `glfm_specification/output/spec.html` - An HTML file, rendered based on `spec.txt`,
-  also generated (or updated) by the `update-specification.rb` script at the same time as
-  `spec.txt`. It corresponds to the HTML-rendered versions of the
-  "GitHub Flavored Markdown" (<abbr title="GitHub Flavored Markdown">GFM</abbr>)
-  [specification](https://github.github.com/gfm/)
-  and the [CommonMark specification](https://spec.commonmark.org/0.30/).
-
-These output `spec.**` files, which represent the official, canonical GLFM specification
+which is generated based on the `spec.txt` as input.
+
+These output `spec.*` files, which represent the official, canonical GLFM specification,
 are colocated under the same parent folder `glfm_specification` with the other
 `input` specification files. They're located here both for convenience, and because they are all
-a mix of manually edited and generated files. In GFM,
-`spec.txt` is [located in the test dir](https://github.com/github/cmark-gfm/blob/master/test/spec.txt),
-and in CommonMark it's located
-[in the project root](https://github.com/github/cmark-gfm/blob/master/test/spec.txt).
-No precedent exists for a standard location. In the future, we may decide to
+a mix of manually edited and generated files.
+
+In GFM, `spec.txt` is [located in the test dir](https://github.com/github/cmark-gfm/blob/master/test/spec.txt),
+and in CommonMark it's located [in the project root](https://github.com/github/cmark-gfm/blob/master/test/spec.txt). No precedent exists for a standard location. In the future, we may decide to
 move or copy a hosted version of the rendered HTML `spec.html` version to another location or site.
 
+##### spec.txt
+
+[`glfm_specification/output/spec.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.txt)
+is a Markdown specification file, in the standard format
+with prose and Markdown + canonical HTML examples. It is generated or updated by the
+`update-specification.rb` script.
+
+It also serves as input for other scripts such as `update-example-snapshots.rb`
+and `run-spec-tests.sh`.
+
+##### spec.html
+
+[`glfm_specification/output/spec.html`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.html)
+is an HTML file, rendered based on `spec.txt`. It is
+also generated (or updated) by the `update-specification.rb` script at the same time as
+`spec.txt`.
+
+It corresponds to the HTML-rendered versions of the
+"GitHub Flavored Markdown" (<abbr title="GitHub Flavored Markdown">GFM</abbr>)
+[specification](https://github.github.com/gfm/)
+and the [CommonMark specification](https://spec.commonmark.org/0.30/).
+
 ### Example snapshot files
 
 The `example_snapshots` directory contains files which are generated by the
@@ -578,12 +644,13 @@ After the entire GLFM implementation is complete for both backend (Ruby) and
 frontend (JavaScript), all of these YAML files can be automatically generated.
 However, while the implementations are still in progress, the `skip_update_example_snapshots`
 key in `glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml`
-can be used to disable automatic generation of some examples, and they can instead
+can be used to disable automatic generation of some examples. They can instead
 be manually edited as necessary to help drive the implementations.
 
 #### `spec/fixtures/glfm/example_snapshots/examples_index.yml`
 
-`spec/fixtures/glfm/example_snapshots/examples_index.yml` is the main list of all
+[`spec/fixtures/glfm/example_snapshots/examples_index.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/examples_index.yml)
+is the main list of all
 CommonMark, GFM, and GLFM example names, each with a unique canonical name.
 
 - It is generated from the hierarchical sections and examples in the
@@ -594,10 +661,15 @@ CommonMark, GFM, and GLFM example names, each with a unique canonical name.
   the additional Section 7 in the GLFM `spec.txt`.
 - It also contains extra metadata about each example, such as:
   1. `spec_txt_example_position` - The position of the example in the generated GLFM `spec.txt` file.
+     - This value is the index order of each individual Markdown + HTML5 example in the file. It is _not_
+       the line number in the file.
+     - This value can be used to locate the example in the rendered `spec.html` file, because the standard
+       CommonMark tooling includes the index number for each example in the rendered HTML file.
+       For example: [https://spec.commonmark.org/0.30/#example-42](https://spec.commonmark.org/0.30/#example-42)
   1. `source_specification` - Which specification the example originally came from:
      `commonmark`, `github`, or `gitlab`.
 - The naming convention for example entry names is based on nested header section
-  names and example index within the header.
+  names and example index in the header.
   - This naming convention should result in fairly stable names and example positions.
     The CommonMark / GLFM specification rarely changes, and most GLFM
     examples where multiple examples exist for the same Section 7 subsection are
@@ -625,7 +697,7 @@ CommonMark, GFM, and GLFM example names, each with a unique canonical name.
 
 #### `spec/fixtures/glfm/example_snapshots/markdown.yml`
 
-`spec/fixtures/glfm/example_snapshots/markdown.yml` contains the original Markdown
+[`spec/fixtures/glfm/example_snapshots/markdown.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/markdown.yml) contains the original Markdown
 for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml`
 
 - For CommonMark and GFM Markdown,
@@ -644,8 +716,8 @@ for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml`
 
 #### `spec/fixtures/glfm/example_snapshots/html.yml`
 
-`spec/fixtures/glfm/example_snapshots/html.yml` contains the HTML for each entry in
-`spec/fixtures/glfm/example_snapshots/examples_index.yml`
+[`spec/fixtures/glfm/example_snapshots/html.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/html.yml)
+contains the HTML for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml`
 
 Three types of entries exist, with different HTML for each:
 
@@ -688,8 +760,8 @@ depending on how the implementations evolve.
 
 #### `spec/fixtures/glfm/example_snapshots/prosemirror_json.yml`
 
-`spec/fixtures/glfm/example_snapshots/prosemirror_json.yml` contains the ProseMirror
-JSON for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml`
+[`spec/fixtures/glfm/example_snapshots/prosemirror_json.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/fixtures/glfm/example_snapshots/prosemirror_json.yml)
+contains the ProseMirror JSON for each entry in `spec/fixtures/glfm/example_snapshots/examples_index.yml`
 
 - It is generated (or updated) from the frontend code via the `update-example-snapshots.rb`
   script, but can be manually updated for examples with incomplete implementations.