Add support for YAML frontmatter in Markdown docs (used for Vitepress config)

[aloisklink]

📑 Summary

Adds support to the packages/mermaid/src/docs.mts script for handling YAML frontmatter in Markdown. This is used by Vitepress for custom page-based configuration, see https://vitepress.vuejs.org/config/frontmatter-configs.

I've mainly added it so that we can use custom editLink in the future, as currently the Edit this page on GitHub link is broken for some auto-generated files, like the one at docs/config/setup/README.md.

📏 Design Decisions

We can use remark-frontmatter to automatically add support for parsing YAML frontmatter to remark.

The only issue is that the YAML frontmatter must always be at the front of the file.
So we have to create the WARNING THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. after the frontmatter, if it exists. To be honest, since the YAML frontmatter is currently only used by Vitepress, we could also just delete it for the GitHub output in docs/. But GitHub automatically converts the YAML frontmatter into a nice table, so it's not too big a deal to keep it in 🤷.

Test Case

As a test-case, I modified the flowcharts page to use outline: "deep" for a more in-depth outline in Vitepress:

Before

See https://mermaid.js.org/syntax/flowchart.html

(outline is set to 2, aka only show <h2> headers)

After

(outline is set to "deep", aka show all headers for h2 to h6)

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
  • Test case added in packages/mermaid/src/docs/syntax/flowchart.md, but we have to manually view the changes in Vitepress/docs/ folder
• 📓 have added documentation (if appropriate)
• 🔖 targeted develop branch

[sidharthv96]

If the change is intended only for vitepress, shouldn't we use the vitepress flag to filter it out from the regular docs?

[aloisklink]

That makes sense! Fixed in 816f2f5

[sidharthv96]

Should we set outine = deep as the default?

[aloisklink]

I've quite heavily refactored my changed due to merge conflicts, so you may want to do a total re-review!

Should we set outine = deep as the default?

My opinion is no, because there are some headings that are probably a bit excessive.

E.g. on https://mermaid.js.org/config/setup/modules/mermaidAPI.html, we don't want to see Parameters, Returns, Defined in for every single function.

However, maybe using outline = [2, 3] makes sense?

According to the Vitepress docs, that should mean show <h2> and <h3> headers.

[sidharthv96]

LGTM! Thanks @aloisklink!

---

Side note: I didn't imagine docs.mts would get this complex when writing it. 🙃

[aloisklink]

Side note: I didn't imagine docs.mts would get this complex when writing it.

Hahaha, yeah, it is getting a bit complicated. Locally I also have some code that auto-generates documentation for the Mermaid Config, since currently on the new website, it's very blank: https://mermaid.js.org/config/setup/README.html

Unfortunately, it's not fully ready (I haven't had too much free time), but hopefully I'll get that done soon (although it will make docs.mts even more complicated!)!

[sidharthv96]

As long as we have enough tests & structure, complexity is fine, as it allows us to do many things automatically. 🚀
And your documentation skills are 💯 too.