Docs: GFM Doc Refactor
What does this MR do?
This is a large refactor of the GFM documentation. I found that a lot of the language could be simplified, clarified, expanded, corrected, etc. Many examples were added, expanded or simplified. Long lines were split up.
As suggested in https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22122, the GitLab specific references were combined into one, easy-to-read table, and some undocumented methods were added. Thanks @Crissov!
Most importantly, the sections were reorganized in a more useful way. Instead of starting with the ways GFM extends standard markdown, it puts everything into their logical subsections, as detailed below:
-
Header IDs and links
is now a subsection ofHeaders
-
Multiple underscores in words
is now a subsection ofEmphasis
-
URL Auto Linking
is now a subsection ofLinks
-
Videos
is now a subsection ofImages
-
Multiline blockquote
is now a subsection ofBlockquotes
-
Details and Summary
is now a subsection ofInline HTML
-
Line breaks
is now a subsection ofNewlines
To maintain the ability to quickly find the ways GitLab differs from standard markdown, a new section was added near the top listing the extensions/changes and linking to their descriptions.
GFM extensions that are not related to standard markdown features are listed above the standard markdown explanations.
Related issues
Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/52250
Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/50138
Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/58676
Closes https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25923
Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/56148
Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/52394
Closes https://gitlab.com/gitlab-org/gitlab-ce/issues/12681
Author's checklist
-
Follow the Documentation Guidelines and Style Guide. -
Link docs to and from the higher-level index page, plus other related docs where helpful. -
Apply the ~Documentation label.
Review checklist
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.
1. Primary Reviewer
-
Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.
2. Technical Writer
-
Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.
3. Maintainer
-
Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review. -
Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist. -
If there has not been a technical writer review, create an issue for one using the Doc Review template.