Update the Markdown doc for style and fix some inaccuracies

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem to solve

The following is a collection of remaining problems with the Markdown reference https://docs.gitlab.com/ee/user/markdown.html:

  • Rearrange the topics on the page to have sensible flow and order. !143378 (merged)

    The Markdown page is no longer broken down in "Features not found in standard Markdown" and "Features extended from standard Markdown". But, to keep the MRs small, the topics weren't rearranged. Decide on an order of topics and rearrange them, for example, nesting "Images" and "Videos" under "Links".

  • Rephrase Show the issue, merge request, or epic title in the reference and Show the issue, work item or merge request summary in the reference to shorten them and make more change resilient when new features are added. !143378 (comment 1754580497) !159645 (merged)

  • Rename ### Colored code and syntax highlighting to ### Syntax highlighting !159614 (merged)

  • @digitalmoksha started a discussion:

    Are we talking about AsciiDoc or Textile files, etc? If you're using those in the context of GitLab, SaaS or self-managed, then I don't think anything else needs to be installed. gitlab.com already installs any needed support, and the same with self-managed.

    Those file formats are only supported in the wiki and file repositories. I wonder if it would make sense to call these out specifically (unless we do that somewhere else), rather than link to the gitlab-markup project.

  • @digitalmoksha started a discussion:

    We're using images here, would it make sense to use one for the color chips section?

    I'm now conflicted on this. Here in the inline diff section we're using images. Also in other areas such as task lists and table of contents. But in other sections, such as color or math, just let the markdown however it does. For example the math is just broken.

    Do we standardize one way or the other, or leave it like this? It's nice being able to see the markdown rendered natively when you look at the file, but it's also annoying to see broken documentation. Particularly if we're using images in some places and not in others.

    Just tossing an idea out here, don't know if it makes sense. We could use images in all the sections, but then also have an HTML details section underneath that when opened, would show the "rendered" version. On the docs site it would look broken, but in the file it would render correctly.

  • (resolved by !189873 (merged)) @digitalmoksha started a discussion:

    We have "Visit the official page for more details" for the Mermaid section. Do we need something like this for PlantUML and Kroki? What about an example of invoking a PlantUML block and a Kroki block? They won't render here, but it would show the markdown syntax.

  • Clarify how to escape characters in Markdown: #421985 (comment 1771914725) !159645 (merged)

  • Improve the "View this topic in GitLab" note in... (#373018 - closed) !159783 (merged)

Further details

Proposal

Who can address the issue

@msedlakjakubowski or a Community contributor.

Other links/references

Edited by 🤖 GitLab Bot 🤖