CDM Documentation site adding support for Mermaid to docusaurus

[chrisisla]

The CDM documentation website is a docusaurus site and the config files are held in the github common-domain-model/website folder. The site currently does not support Mermaid diagrams.

I updated package.json and package-lock.json to include the mermaid theme as a dependency, ensuring that the version matched the current docusaurus version:

  "dependencies": {
    "@docusaurus/core": "^3.9.2",
    "@docusaurus/plugin-google-gtag": "3.9.2",
    "@docusaurus/preset-classic": "^3.9.2",
    "@docusaurus/theme-mermaid": "^3.9.2",                  <- Added this line
    "axios": "^1.16.0",
...

I also updated docusaurus.config.js to add the mermaid markdown and the theme as follows:

module.exports = {
  title: `${projectName}`,
  url: 'https://www.cdm.finos.org',
  baseUrl: '/',
  favicon: 'img/favicon/favicon.ico',
  projectName: `${projectName}`,
  organizationName: 'FINOS',
  customFields: {
    repoUrl: `https://github.com/finos/${projectSlug}`,
  },
  scripts: ['https://buttons.github.io/buttons.js'],
  stylesheets: ['https://fonts.googleapis.com/css?family=Overpass:400,400i,700'],
  markdown: {                                                         <-- Added these lines
    mermaid: true,                                                    <--
  },                                                                  <--
  themes: ['@docusaurus/theme-mermaid'],                              <--

I downloaded the website from github and ran "npm install" and "npm run start" as guided by the website/README.md file. The preview website would not start as it complained that the version of mermaid - 3.9.2 - did not match the version of docusaurus - which was also 3.9.2. Hmmm.

In the end I ran "npm -i @docusaurus/theme-mermaid@3.9.2" which basically added the same lines as I did to package.json and package-lock.json.... but this time the website started and the mermaid diagrams rendered.

My question then.
I need to add a new page to the documentation site for the new serialization format. This contains the mermaid diagrams. This needs to be done before the CDM V7 cut off in a couple of weeks.

• Does anyone know why updating the files as I did has not worked? Is this actually going to be an issue on the live site?
• And secondly, if I do include the mermaid diagrams and the site does not startup then we will need to run npm -i where the site is hosted - is there anyone who can help with this?

If we can't get this sorted then I can remove the mermaid diagrams which would be a shame but will still enable me to publish this documentation along with the CDMV7 release.

Thanks in advance for any suggestions!

[CDM-ReleaseManagement-LSG]

We usually go to help@finos.org on these matters and they resolve quickly

[chrisisla]

Hi @CDM-ReleaseManagement-LSG
I spoke to Mao and Juan who pointed me in the right direction but requested that I ask the community for this final question about why updating these files did not work until I ran npm -i 🤷
Let's hope someone has some experience in this area and can assist 🙂
Thanks!

[maoo]

@chrisisla @CDM-ReleaseManagement-LSG - it's very important to have these conversations in the open, since the website is part of CDM assets and it is maintained by the Maintainers team. Additionally, this issue relates to Docusaurus, which is used by nearly every FINOS project, some of which also use it in combination with Mermaid.

@chrisisla - could you please raise a PR with your changes, so we can take advantage of Docusaurus preview? Then we can continue the conversation there.

[chrisisla]

Hi @maoo
I have created PR #4820 with the changes. I'll create an Issue for it too.
Thanks!