feat: Support config in frontmatter.

[sidharthv96]

📑 Summary

Allows defining diagram specific config from the frontmatter.

---
config:
  sankey:
    nodeAlignment: justify
---
sankey-beta
%%data

Resolves #4630

📏 Design Decisions

The config will be added using the existing addDirective function, which has the necessary security checks.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🔖 targeted develop branch

[sidharthv96]

Related to #4748

[codecov]

Codecov Report

Merging #4750 (3944e9a) into develop (6e0f411) will increase coverage by 29.27%.
The diff coverage is 52.84%.

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #4750       +/-   ##
============================================
+ Coverage    45.55%   74.83%   +29.27%     
============================================
  Files           53      146       +93     
  Lines         6621    14561     +7940     
  Branches        32      586      +554     
============================================
+ Hits          3016    10896     +7880     
+ Misses        3604     3549       -55     
- Partials         1      116      +115     

Flag	Coverage Δ
e2e	80.88% <85.00%> (?)
unit	45.55% <17.07%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
packages/mermaid/src/directiveUtils.ts	37.80% <ø> (+26.31%)	⬆️
packages/mermaid/src/mermaidAPI.ts	61.38% <37.50%> (+17.69%)	⬆️
packages/mermaid/src/config.ts	74.49% <40.00%> (+15.76%)	⬆️
packages/mermaid/src/diagram-api/frontmatter.ts	62.26% <53.12%> (+14.76%)	⬆️
packages/mermaid/src/utils.ts	59.53% <55.38%> (+21.40%)	⬆️
packages/mermaid/src/Diagram.ts	66.66% <100.00%> (+23.80%)	⬆️
packages/mermaid/src/assignWithDepth.ts	94.28% <100.00%> (+4.28%)	⬆️
packages/mermaid/src/defaultConfig.ts	47.21% <100.00%> (+2.97%)	⬆️

... and 134 files with indirect coverage changes

[aloisklink]

Two comments:

• I don't think we should be changing packages/mermaid/src/config.ts. Can't we just treat config in the YAML frontmatter the same way we treat %%{init: ...} directives?
  That way we can use the already existing addDirective() function, and we don't need to worry about potential security vulnerabilities in this PR. (we may also need to call directiveSanitizer() first).
• This PR needs documentation on the https://mermaid.js.org/ website (maybe on the https://mermaid.js.org/config/configuration.html page?)

[sidharthv96]

Can't we just treat config in the YAML frontmatter the same way we treat %%{init: ...} directives?

Yes, that was my first approach. But directives are currently not typed properly. So tried this as a POC.

Docs will be added before merge.

[aloisklink]

Yes, that was my first approach. But directives are currently not typed properly.

Is there any reason why can't just change the addDirective() function so that it is typed properly? E.g. something like:

diff --git a/packages/mermaid/src/config.ts b/packages/mermaid/src/config.ts
index e0066382..a7e6c49b 100644
--- a/packages/mermaid/src/config.ts
+++ b/packages/mermaid/src/config.ts
@@ -8,10 +8,10 @@ export const defaultConfig: MermaidConfig = Object.freeze(config);
 
 let siteConfig: MermaidConfig = assignWithDepth({}, defaultConfig);
 let configFromInitialize: MermaidConfig;
-let directives: any[] = [];
+let directives: MermaidConfig[] = [];
 let currentConfig: MermaidConfig = assignWithDepth({}, defaultConfig);
 
-export const updateCurrentConfig = (siteCfg: MermaidConfig, _directives: any[]) => {
+export const updateCurrentConfig = (siteCfg: MermaidConfig, _directives: MermaidConfig[]) => {
   // start with config being the siteConfig
   let cfg: MermaidConfig = assignWithDepth({}, siteCfg);
   // let sCfg = assignWithDepth(defaultConfig, siteConfigDelta);
@@ -188,7 +188,7 @@ export const sanitize = (options: any) => {
  *
  * @param directive - The directive to push in
  */
-export const addDirective = (directive: any) => {
+export const addDirective = (directive: MermaidConfig) => {
   if (directive.fontFamily) {
     if (!directive.themeVariables) {
       directive.themeVariables = { fontFamily: directive.fontFamily };

We may have to add add // @ts-expect-error comments, but that's okay, as long as we're improving the existing TypeScript situation (e.g. removing any types).

[sidharthv96]

Is there any reason why can't just change the addDirective() function so that it is typed properly?

No reason at all. I guess my brain was in POC mode and didn't want to touch any existing stuff.

I've cleaned it up now :)

[aloisklink]

No reason at all. I guess my brain was in POC mode and didn't want to touch any existing stuff.

I've cleaned it up now :)

The implementation looks great to me, all it needs is:

• E2E tests
  • Can you add a test that has both a config directive in YAML frontmatter, and in a %%{init: } block, just to confirm it works?
• an example in the demos/ folder (or multiple examples), and
• some documentation in the https://mermaid.js.org site!

If you want to be really fancy, you can rewrite the your commits to split up the refactor commits (which have no visible changes to users), fix: commits (which fix potential bugs), and the feat: commits (which add new features), e.g. something like refactor: sanitize in addDirective, refactor: improve addDirective types, ... fix: improve YAML frontmatter type handling, feat: support config directives in YAML, but this is a pretty small PR, so it doesn't matter too much 😄

FYI, I think this PR will close issue #4630! If you agree, feel free to stick it in your PR's description.

[sidharthv96]

Merging myself as @knsv has approved and attempted a merge.