diff options
Diffstat (limited to 'doc/development/gitlab_flavored_markdown/specification_guide/index.md')
-rw-r--r-- | doc/development/gitlab_flavored_markdown/specification_guide/index.md | 106 |
1 files changed, 67 insertions, 39 deletions
diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index 79a4ac9b49a..806ac3837bf 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -514,29 +514,30 @@ of how the normalizations are specified. Given all the constraints above, we can summarize the various goals related to the GLFM specification and testing infrastructure: -1. A canonical `spec.txt` exists, and represents the official specification for - GLFM, which meets these requirements: - 1. The spec is a strict superset of the GitHub Flavored Markdown +1. There is an official specification and single source of truth for how GLFM should render Markdown to HTML. + This source of truth is represented by three Markdown files: + 1. [`ghfm_spec_v_?.??.md`](#github-flavored-markdown-specification) for the CommonMark + GFM examples. + 1. [`glfm_official_specification.md`](#glfm_official_specificationmd) for the GLFM official examples. + 1. [`glfm_internal_extensions.md`](#glfm_internal_extensionsmd) for the GLFM internal extensions. +1. This official specification meets these requirements: + 1. The specification is a strict superset of the GitHub Flavored Markdown (GFM) specification, just as <abbr title="GitHub Flavored Markdown">GFM</abbr> is a strict superset [of the CommonMark specification](https://github.github.com/gfm/#what-is-github-flavored-markdown-). 1. Therefore, it contains the superset of all [Markdown examples](#markdown-examples) for CommonMark and GFM, as well as the GLFM [official specification](#official-specifications) and [internal extensions](#internal-extensions). - 1. It contains a prose introduction section which is specific to GitLab and GLFM. - 1. It contains all other non-introduction sections verbatim from the - [GFM specification](#github-flavored-markdown-specification). - 1. It contains new, extra sections for all the additional Markdown contained in the GLFM + 1. It contains sections and examples for all the additional Markdown contained in the GLFM [official specification](#official-specifications) and [internal extensions](#internal-extensions), - with [Markdown examples](#markdown-examples) and accompanying prose, just like the CommonMark and GFM examples. - 1. All its headers and [Markdown examples](#markdown-examples) should be in the standard format which can be processed by the standard + with [Markdown examples](#markdown-examples) and any accompanying prose, just like the CommonMark and GFM examples. + 1. All headers and [Markdown examples](#markdown-examples) should be in the standard format, which can be processed by the standard CommonMark tool [`spec_tests.py`](https://github.com/github/cmark-gfm/blob/master/test/spec_tests.py) used to perform [Markdown conformance testing](#markdown-conformance-testing) against all examples contained in a `spec.txt`. 1. The GLFM parsers and HTML renderers for both the static backend (Ruby) and WYSIWYG frontend (JavaScript) implementations support _consistent_ rendering of all canonical Markdown + HTML examples in the - GLFM `spec.txt` specification, as verified by `spec_tests.py`. + specification, as verified by [`run-spec-tests.sh`](#run-spec-testssh-script). NOTE: Consistent does not mean that both of these implementations render @@ -616,26 +617,41 @@ them from the corresponding implementation class entry point files under #### `update-specification.rb` script The `scripts/glfm/update-specification.rb` script uses [input specification files](#input-specification-files) to -generate and update `spec.txt` (Markdown) and `spec.html` (HTML). The `spec.html` is -generated by passing the generated (or updated) `spec.txt` Markdown to the backend API -for rendering to static HTML: +generate and update Markdown and HTML output files for the +[`spec.txt`](#spectxt) and [`spec.html`](#spechtml) +[output specification files](#output-specification-files) as well as the +[`snapshot_spec.md`](#snapshot_specmd) and [`snapshot_spec.html`](#snapshot_spechtml) +[output example snapshot files](#output-example-snapshot-files). + +The HTML files are created by passing the generated (or updated) Markdown to the backend API +for rendering to HTML. + +```mermaid +graph LR +subgraph script: + S{update-specification.rb} +end +subgraph input - markdown files + I1[glfm_official_specification.md - GLFM official specification examples] --> S +end +subgraph output - specification files + S --> O1[spec.txt - GLFM official specification examples] + S --> O2[spec.html - GLFM official specification examples] +end +``` ```mermaid graph LR subgraph script: - A{update-specification.rb} - A --> B{Backend Markdown API} + S{update-specification.rb} end -subgraph input:<br/>input specification files - C[ghfm_spec_v_0.29.md] --> A - D[glfm_intro.md] --> A - E[glfm_official_specification.md] --> A - F[glfm_internal_extensions.md] --> A +subgraph input - markdown files + I1[ghfm_spec_v_0.29.md - CommonMark and GHFM specification examples] --> S + I2[glfm_internal_extensions.md - GLFM internal extension examples] --> S end -subgraph output:<br/>GLFM specification files - A --> G[spec.txt] - G --> B - B --> H[spec.html] +subgraph output - example snapshot files + S --> O1[snapshot_spec.md - CommonMark, GHFM, GLFM internal extension examples] + S --> O2[snapshot_spec.html - CommonMark, GHFM, GLFM internal extension examples] end ``` @@ -655,7 +671,8 @@ script, which expects canonical HTML, against the GitLab renderer implementation `scripts/glfm/run-spec-tests.sh` is a convenience shell script which runs conformance specs via the CommonMark standard `spec_tests.py` script, -which uses the `glfm_specification/output_spec/spec.txt` file and `scripts/glfm/canonicalize-html.rb` +which uses the `ghfm_spec_v_0.29.md` and `glfm_specification/output_spec/spec.txt` files +with the `scripts/glfm/canonicalize-html.rb` helper script to test the GLFM renderer implementations' support for rendering Markdown specification examples to canonical HTML. @@ -669,7 +686,8 @@ subgraph scripts: end end subgraph input - D[spec.txt GLFM specification] --> C + D1[ghfm_spec_v_0.29.md GLFM specification] --> C + D2[spec.txt GLFM specification] --> C E((GLFM static<br/>renderer implementation)) --> B F((GLFM WYSIWYG<br/>renderer implementation)) --> B end @@ -680,22 +698,28 @@ end #### `update-example-snapshots.rb` script -The `scripts/glfm/update-example-snapshots.rb` script uses the GLFM -`glfm_specification/output_spec/spec.txt` specification file and the -`glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml` -file to create and update the [example snapshot](#output-example-snapshot-files) -YAML files: +The `scripts/glfm/update-example-snapshots.rb` script creates and updates the +[example snapshot](#output-example-snapshot-files) YAML files. + +Its inputs are: + +- The `glfm_specification/output_spec/snapshot_spec.md` file, which contains the + superset of all CommonMark, GFM, and GLFM official and internal examples. +- The `glfm_specification/input/gitlab_flavored_markdown/glfm_example_*.yml` YAML files, which + contain metadata to control how to generate the example snapshot files. ```mermaid graph LR subgraph script: A{update-example-snapshots.rb} end -subgraph input:<br/>input specification file - B[spec.txt] --> A - C[glfm_example_status.yml] --> A +subgraph input: markdown input specification files + B1[snapshot_spec.md] --> A + C1[glfm_example_status.yml] --> A + C2[glfm_example_normalizations.yml] --> A + C3[glfm_example_metadata.yml] --> A end -subgraph output:<br/>example snapshot files +subgraph output: YAML example snapshot files A --> E[examples_index.yml] A --> F[markdown.yml] A --> G[html.yml] @@ -736,15 +760,15 @@ end subgraph script: A{run-snapshopt-tests.sh} -->|invokes| B end +subgraph output:<br/>test results/output + B --> H[rspec+jest output] +end subgraph input:<br/>YAML C[examples_index.yml] --> B D[markdown.yml] --> B E[html.yml] --> B F[prosemirror_json.yml] --> B end -subgraph output:<br/>test results/output - B --> H[rspec+jest output] -end ``` #### `verify-all-generated-files-are-up-to-date.rb` script @@ -1111,8 +1135,12 @@ move or copy a hosted version of the rendered HTML `spec.html` version to anothe is a Markdown specification file, in the standard format with prose and Markdown + canonical HTML examples. +In the GLFM specification, `spex.txt` only contains the official specifiaction examples from +[`glfm_official_specification.md`](#glfm_official_specificationmd). It does not contain +the internal extension examples from [`glfm_internal_extensions.md`](#glfm_internal_extensionsmd). + It also serves as input for other scripts such as -`run-spec-tests.sh`. +[`run-spec-tests.sh`](#run-spec-testssh-script). It is generated or updated by the `update-specification.rb` script, using the [input specification files](#input-specification-files) as input. |