Remove usage of Directives in docs

[sidharthv96]

With https://github.com/mermaid-js/mermaid/pull/4750, the directives will be officially deprecated. So all instances of their usage should be removed from the documentation.

The page for directives should remain, as a reference for people using older versions, but their usage from other examples in general should be replaced with the frontmatter.

[Aryangp]

Hey @sidharthv96 can you provide a little more brief about this issue and some reference of what is to be done

[sidharthv96]

There are documentation files in packages/mermaid/src/docs/, many of them have the directive syntax used inside examples. We need to change all that into the yaml syntax.

The fun way to do it would be to write a program to read the .md files, detect the directives, parse the directive using a copy of our existing function, convert it into yaml and replace the directive text with yaml text.

The other option is to manually convert the format.

[nirname]

I can do this right after

• 4767

[Aryangp]

Ok I understand now so should I work on this now @sidharthv96 as @nirname mentioned he want to work on it but I can want to try contributing to this as I am new to open source and this issue will be good start

[nirname]

@Aryangp no problem, I have plenty other things to do, if you are ready to commit - welcome

[nirname]

I see that deprecation warnings are the part of #4750 so in this issue we have to tackle only examples of code, I think

[sidharthv96]

@nirname please see https://github.com/mermaid-js/mermaid/issues/4487#issuecomment-1681607124 regarding assigning issues.

[Yokozuna59]

The fun way to do it would be to write a program to read the .md files, detect the directives, parse the directive using a copy of our existing function, convert it into yaml and replace the directive text with yaml text.

I think it would be nice to have such script, it would help when implementing #4620 and give the ability to preform quick fix when using language server.

[Aryangp]

@Yokozuna59 see I ma new to this tell if I am wrong are you implying to something like a bash script to convert it into yml code

[Yokozuna59]

@Aryangp A TS script would be better, so we could the logic in other places too.

So a TS script that converts directives into yaml in .mmd and .mermaid files (pure mermaid code) and use the same logic in .md file but only on mermaid code block.

[Aryangp]

ok i got that first i will make a ts script and try this approch and tell you the progress here

[Aryangp]

sorry i was working on something else that why wasn't able to work on it , I will make a pr in a few days just want to give you update on progress of this issue and also i have made a script just like mentioned above i will share the code of the script on slack see if it need any improvement @sidharthv96 @Yokozuna59

[Yokozuna59]

@Aryangp Please, if you could, mention users at the beginning of your message so that we know who you're talking to :)

sorry i was working on something else that why wasn't able to work on it , I will make a pr in a few days just want to give you update on progress of this issue

No worries.

and also i have made a script just like mentioned above i will share the code of the script on slack see if it need any improvement

Please create another PR for it. It would easier and better visibility for the community when there's an open PR.

[Aryangp]

hey @sidharthv96 can you tell does the

---
code 
---

is inportant in the final yaml code or is it just for formatting as just there is some space come in this --- after running the script so can you tell

[nirname]

@Aryangp Hi! I am glad to hear that your are working on the task.

As @Yokozuna59 had already mentioned, please open PR to share the source code, no matter how good or bad it is. It is much better to keep it as a history and share with the community.

Sorry for answering the question you had addressed to another person:

is inportant in the final yaml code or is it just for formatting as just there is some space come in this --- after running the script so can you tell it is not clear what you are asking about, let me clarify what is happening there.

We used to have different ways of configuring diagrams. Among the others was "directives" syntax, some JSON-like embedded in diagram, wrapped in %%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%

Now we are going to switch to YAML instead of JSON and custom brackets %%{ }%%. We also use --- as document divider. This marks the beginning of YAML document and it is a part of front-matter.

We do not get rid of directives syntax, we are going to deprecate them.

That being said:

• Diagram configuration is a part of code block
• Diagram configuration is optional
• We use triple dash at the beginning and at the end of diagram configuration, no additional spaces after them needed
• Configuration must be a valid YAML format (preserve indentation)
• Since we don't know what diagram will be inside we keep the name of the diagram as a "key" of the config.

```mermaid
---
title: This is another complicated flow
config:
  theme: base
  sankey:
    nodeAlignment: justify
  flowchart:
    curve: cardinal
    htmlLabels: false
---
// any diagram code goes here

**It already works**.

Now **we simply need to clean it up and replace all the remains of it in the docs**. So the idea is either:
* make it manually
* make it automatically (write script)

In case you are writing script for doing the job, please stick to the example provided. If the example is not as comprehensive as it could be, feel free to ask.

[Aryangp]

hey @sidharthv96 and @Yokozuna59 i have made a pr where i have put the script can you check it out and provide any improvement

[Aryangp]

and yeah @nirname thanks for explaining sorry i seen your message late

[Aakashdeep-Srivastava]

Lets do this.....