Consider leveraging MDX to write component docs
Currently, component docs is written with pure Markdown. Some properties can be specified in the frontmatter. We also support some custom tags like [[Story:]]
or Todo:
. Those are parsed at render time and replaced with the proper HTML/Vue components. This forces to maintain some somewhat ugly code to do the parsing: https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/e204b9605e445fb124e5cdcfe583eb389c091d4d/components/md_display.vue#L57-75. It also limits our ability to extend on those custom tags as each feature addition requires updating the parser, which isn't as straightforward as it should be.
We might be able to rework all of this by leveraging MDX: https://mdxjs.com/. Using the Vue loader, we would be able to easily include Vue components in any docs file.
This might require extra-work to preserve frontmatter's support: https://mdxjs.com/guides/frontmatter/
Another advantage of this solution is that the MDX loader seems to provide Hot Module Replacement, making any change to an MDX file much faster to show up in the app whereas the current approach typically requires a full re-build when changing a Markdown file.
- PoC: !2741 (closed)