mermaid: Diagram specific configuration with YAML (Sankey-beta missing diagram-specific configuration and parsing error)

I decided to renamed the issue to generalize it and keep the discussion, because it is not about Sankey diagrams at all.

No, we are not dropping directives. We are deprecating them, so no new features will be added to them. All new configs will go into the YAML frontmatter.

To be clear, we NEVER intentionally break backwards compatibility in syntax. We can make breaking JS-API changes in major releases, but we don’t break old syntax (except when using the -beta keyword).

The YAML frontmatter is currently stripped away from the code before it’s sent to the parser, so you can ignore it for now. We can add frontmatter support once we get the diagrams running?

I’m thinking we’d have a file like diagram-frontmatter.d.ts (ideally auto-generated from a JSON Schema YAML like diagram-frontmatter.schema.yaml) that looks like:

import type {MermaidConfig} from "./config.types.js";

type DiagramFrontmatter = {
  title?: string;
  accTitle?: string;
  accDescr?: string;
  config?: MermaidConfig;
};

The diagram config is already defined as part of the MermaidConfig (e.g. config: {myDiagram: {...}}.

Defining it as diagram-frontmatter.schema.yaml will give us nice auto-generated docs, and will let us do runtime checking that we have the correct types, and print warnings if types don’t match.

@Yokozuna59 the triple dash block is the standard of frontmatter. We shouldn’t deviate from that.

https://jekyllrb.com/docs/front-matter/

Would like to hear @aloisklink’s take on this.

re: having the diagram key in yaml, it should be fine. Removing the key is gonna make things more complicated.

If by some reason we would allow to define multiple diagrams per one image the second option (specifying diagram type) would work too. Do we have an issue for adding this yaml-configs?

Each code should only be for one diagram. So, it doesn’t make sense to configure values for other diagrams, i.e., the code is for pie, but the user configures values for gantt`:

%%{init: {"gantt": {"mirrorActor": true}}}%%
pie

In this case, the first approach would be better since all those values would be for the actual diagram.

But doing that, it would be hard to strictly limit possible keys, i.e., if pie1 is only for pie, we can’t throw an error since it’s a supported key but not for other diagrams:

---
pie1: ...
---
pie

And from an LSP perspective, it would be a nightmare, and the user wouldn’t use it since it would provide auto-complete with combining all possible keys, not just the current diagram.

So I guess this is the way to go:

---
title: awesome title
sankey:
  - width: 300
quadrant:
  - chartWidth: 400
---
sankey

Just in case: if I am not mistaken this --- between config and graph definition is a must.

Yes, it is. I have forgotten it by mistake.

That is processed separately, isn’t part of grammar. We just need to add support for the full config options to be read from this frontmatter (except the security focused ones).

For new diagrams, config should go in as yaml frontmatter. I’m not sure if yaml config is currently supported in sankey, but %%{init: {'theme': 'default', 'sankey':{ 'width': 400}}}%% will not be supported. If yaml config is not supported, the support should be added for complete config values, not just sankey. It should be easier now that https://github.com/mermaid-js/mermaid/pull/4112 is merged.