Skip to content

Docs: GFM Doc Refactor

Marcel Amirault requested to merge (removed):docs-gfm-cleanup into master

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 of Headers
  • Multiple underscores in words is now a subsection of Emphasis
  • URL Auto Linking is now a subsection of Links
  • Videos is now a subsection of Images
  • Multiline blockquote is now a subsection of Blockquotes
  • Details and Summary is now a subsection of Inline HTML
  • Line breaks is now a subsection of Newlines

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

  1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  2. Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by Evan Read

Merge request reports