diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-07-06 00:08:43 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-07-06 00:08:43 +0300 |
commit | 59712a466f6f12acf517cdea2c4fa876f0214124 (patch) | |
tree | ba91f1d944811e9eef71bd45843797ad9989c3af /doc/development/gitlab_flavored_markdown | |
parent | 2b2299ea5f8717ad59a47c1c40d951409dfeb35b (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development/gitlab_flavored_markdown')
-rw-r--r-- | doc/development/gitlab_flavored_markdown/specification_guide/index.md | 26 |
1 files changed, 13 insertions, 13 deletions
diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index ae78daa3687..ba37c858b63 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -124,7 +124,7 @@ to report this. #### Official specifications vs internal extensions -Within GFM and GLFM respectively, both GitHub and GitLab have two "sets" of Markdown they support: +GFM for GitHub and GLFM for GitLab have two "sets" of Markdown they support: - Official specification - Internal extensions @@ -297,9 +297,9 @@ The Markdown dialect used in the GitLab application has a dual requirement for r 1. Rendering to static read-only HTML format, to be displayed in various places throughout the application. 1. Rendering editable content in the - [Content Editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/), + [rich text editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/), a ["What You See Is What You Get" (WYSIWYG)](https://en.wikipedia.org/wiki/WYSIWYG) - editor. The Content Editor supports real-time instant switching between an editable + editor. The rich text editor supports real-time instant switching between an editable Markdown source and an editable WYSIWYG document. These requirements means that GitLab has two independent parser and renderer @@ -312,14 +312,14 @@ implementations: GitHub's fork of the reference parser for CommonMark. `libcmark-gfm` is an extended version of the C reference implementation of [CommonMark](https://commonmark.org/) 1. The frontend parser / renderer supports parsing and _WYSIWYG_ rendering for - the Content Editor. It is implemented in JavaScript. Parsing is based on the + the rich text editor. It is implemented in JavaScript. Parsing is based on the [Remark](https://github.com/remarkjs/remark) Markdown parser, which produces a MDAST Abstract Syntax Tree (MDAST). Rendering is the process of turning an MDAST into a [ProseMirror document](../../fe_guide/content_editor.md). Then, ProseMirror is used to render a ProseMirror document to WYSIWYG HTML. In this document, we refer to the process of turning Markdown into an MDAST as the _frontend / JavaScript parser_, and the entire process of rendering Markdown - to WYSIWYG HTML in ProseMirror as the _Content Editor_. Several + to WYSIWYG HTML in ProseMirror as the _rich text editor_. Several requirements drive the need for an independent frontend parser / renderer implementation, including: 1. Lack of necessary support for accurate source mapping in the HTML renderer @@ -356,7 +356,7 @@ used when running [Markdown snapshot testing](#markdown-snapshot-testing). #### WYSIWYG HTML -**WYSIWYG HTML** is HTML produced by the frontend (JavaScript) Content Editor, +**WYSIWYG HTML** is HTML produced by the frontend (JavaScript) rich text editor, which includes parsing and rendering logic. It is used to present an editable document in the ProseMirror WYSIWYG editor. @@ -472,7 +472,7 @@ generating the HTML for footnote examples. Even though it is in the production c no effect unless it is explicitly set, therefore it is innocuous. It allows us to avoid the more-complex regex-based normalization described below. -The current example of this is when normally random footnote IDs are overridden to be deterministic +The current example of this is when footnote IDs that are usually random are overridden to be deterministic by setting `GITLAB_TEST_FOOTNOTE_ID`. It is set along with the fixtures setup in the [`spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb) shared context. @@ -554,9 +554,9 @@ specification and testing infrastructure: 1. The frontend (JavaScript) parser and renderer (which includes GitLab custom code and Remark) can convert Markdown to the expected ProseMirror JSON representing a ProseMirror document. - 1. The **Content Editor** (which includes the frontend (JavaScript) parser and renderer, + 1. The **rich text editor** (which includes the frontend (JavaScript) parser and renderer, and ProseMirror) can convert Markdown to the expected custom WYSIWYG HTML as rendered by ProseMirror. - 1. The **Content Editor** can complete a round-trip test, which involves converting + 1. The **rich text editor** can complete a round-trip test, which involves converting from Markdown, to MDAST, to ProseMirror Document, then back to Markdown. It ensures the resulting Markdown is exactly identical, with no differences. @@ -734,10 +734,10 @@ Markdown snapshot testing RSpec and Jest `*_spec` files (from main app `spec` fo which are driven by `example_snapshot` YAML files. The actual RSpec and Jest test `*_spec` files (frontend and backend) live -under the normal relevant locations under `spec`, matching the location of their +under the usual relevant locations under `spec`, matching the location of their corresponding implementations. They can be run either: -- As part of the normal pipelines. +- As part of the standard pipelines. - From the command line or an IDE, just like any other file under `spec`. However, they are spread across four different locations: @@ -1329,7 +1329,7 @@ Three types of entries exist, with different HTML for each: - **WYSIWYG** - The WYSIWYG (frontend, JavaScript-generated) HTML for each entry in `glfm_specification/output_example_snapshots/examples_index.yml`. - - It is generated (or updated) from the frontend Content Editor implementation via the + - It is generated (or updated) from the frontend rich text editor implementation via the `update-example-snapshots.rb` script. It can be manually updated for WYSIWYG examples with incomplete implementations. @@ -1411,5 +1411,5 @@ This section describes how the scripts can be used to manage the GLFM specificat 1. Visually inspect and confirm any resulting changes to the [example snapshot files](#output-example-snapshot-files). 1. Run [`run-snapshot-tests.sh`](#run-snapshot-testssh-script) as a convenience script to run all relevant frontend (RSpec) and backend (Jest) tests which use the example snapshots. 1. Any frontend or backend snapshot test may also be run individually. - 1. All frontend and backend tests are also run as part of the continuous integration suite, as they normally are. + 1. All frontend and backend tests are also run as part of the continuous integration suite, as they typically are. 1. Commit any changes to the [input specification files](#input-specification-files), [output specification files](#output-specification-files), or [example snapshot files](#output-example-snapshot-files). |