Update the Markdown doc for style and fix some inaccuracies
Problem to solve
-
Rearrange the topics on the page to have sensible flow and order. !143378 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
andShow the issue, work item or merge request summary in the reference
to shorten them and make more change resilient when new features are added. -
@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 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.
-
@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.
Further details
Proposal
Who can address the issue
@msedlakjakubowski or a Community contributor.