New Documentation Proposal

[emersonbottero]

Is your feature request related to a problem? Please describe.
Use Vitepress to document this lib, The lib is awesome.. the current docs not so much.. 😅

Describe the solution you'd like
Vitepress has a lot of features and is easy to implement.

Describe alternatives you've considered
Keep as it is 😅. But I really thin it can be improved a lot.

Additional context
I saw some integrations already exist, and I started to work with the equivalent for that when migrating to vitepress

• Dark theme
• Better Organization, logical folder and nav header for related content (intro, syntax, ...)
• Already create a markdown rule to keep the mermaid-example fences working.
• We don't need to keep 2 copies of the documentation as it is today, docs and src/docs
• The documentation don't need to reside inside src folder (I think it became more organized)
• You can still reference files inside src in the docs if needed
• Is easy to create a deploy to github pages!
• I replaced some images with with actually diagrams (they will update in dark theme)

Some images as reference of what I have done so far.

[emersonbottero]

Full working example here

need to search for errors...

[sidharthv96]

This looks great!
Do you think it would be possible to have the full left pane menu all the time?

We don't need to keep 2 copies of the documentation as it is today, docs and src/docs

This is kept so that people reading documentation in Github can read code and see the diagram.
The doc site already had code earlier to render both.

[emersonbottero]

1 - Is pretty easy, I removed because I though it was too much information, that's why we have nav at the top(they identify the path and show the active one), I'll change the example

2 - Is that bad to writer twice the code and diagram?

[emersonbottero]

1 - Done! 😎

2 - The doc example visible in docs and github at the same time would be
In the docs
In github

Edit:
just notice you use a script to transform mermaid-example to code and mermaid..
We can keep that if you think is better than writing twice.

[emersonbottero]

There are more features we can use..
We can actually extract text from ts files and show the content..

[sidharthv96]

Is that bad to writer twice the code and diagram?

Actually, yes. Many diagrams were getting out of sync with code and many issues were raised and maintenance was a pain.
We will stick with one set of docs in /src/docs and generated /docs approach.

Vitepress does look good 🚀 .

[sidharthv96]

Some css issue

---

https://emersonbottero.github.io/mermaid-docs/community/nOOb-overview.html

---

Links need to be updated. There might be others.

---

There should be a link to mermaid.live

[knsv]

It would be great if this issue could be in conjunction with issue #2910

[sidharthv96]

@emersonbottero, can you raise the PR, so we can discuss the details there?

[emersonbottero]

When I try to use this repo I got several issues in commiting and also somewhere for some reason an old versione of Vue or vite Is ben used that caused an conflict..

To many workflows and scripts I dont understand I guess

[sidharthv96]

Did you check https://github.com/mermaid-js/mermaid/blob/develop/CONTRIBUTING.md ?

Can you share what the issues are? We are trying to simplify the onboarding process for new contributors. Would like to hear what the pain points are.

[emersonbottero]

Those are fixed..
in the nav bar the link don't actually leave the page (but can be changed)

[emersonbottero]

1

git clone [email protected]:mermaid-js/mermaid.git
Cloning into 'mermaid'...
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

1 - Create a fork of developer branch

2 yarn

yarn run v1.22.5
$ yarn clean; yarn build:esbuild
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command "clean;" not found. Did you mean "clean"?
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[1] error Command failed with exit code 1.
[1] yarn build exited with code 1
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

2 - change "build": "yarn clean && yarn build:esbuild",

3 yarn test

Test Files  48 passed | 1 skipped (49)
Tests  925 passed | 4 skipped (929)
Start at  19:03:34
Duration  31.77s (transform 2.32s, setup 3.60s, collect 111.87s, tests 4.54s)

4 - Installnew docs packages..`

yarn add vitepress-plugin-mermaid -s
yarn add vitepress-plugin-search -D

All ok so far...

yarn add vitepress -D

$ node .esbuild/esbuild.cjs
[1] [0] yarn build:code exited with code 0
[1] [1] yarn build:types exited with code 0
$ documentation build src/mermaidAPI.ts src/config.ts src/defaultConfig.ts --shallow -f md --markdown-toc false > src/docs/Setup.md && prettier --write src/docs/Setup.md    
[1] C:\Users\emers\Source\Repos\mermaid\node_modules\vue-template-compiler\index.js:10
[1]   throw new Error(
[1]   ^
[1]
[1]     at Object.<anonymous> (C:\Users\emers\Source\Repos\mermaid\node_modules\vue-template-compiler\index.js:10:9)
[1]     at Module._compile (node:internal/modules/cjs/loader:1101:14)
[1]     at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
[1]     at Module.load (node:internal/modules/cjs/loader:981:32)
[1]     at Function.Module._load (node:internal/modules/cjs/loader:822:12)
[1]     at Module.require (node:internal/modules/cjs/loader:1005:19)
[1]     at require (node:internal/modules/cjs/helpers:102:18)
[1]     at Object.<anonymous> (C:\Users\emers\Source\Repos\mermaid\node_modules\documentation\src\parsers\vue.js:2:21)
[1]     at Module._compile (node:internal/modules/cjs/loader:1101:14)
[1]     at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[1] error Command failed with exit code 1.
[1] yarn build exited with code 1
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.

but the package installled

5 - Added scripts

    "vdocs:dev": "vitepress dev vdocs",
    "vdocs:build": "vitepress build vdocs",
    "vdocs:serve": "vitepress serve vdocs",

6 - added vdocs folder
7 - added alias do mermaid using unpkg.com..
8 - run vdocs:dev

import { MermaidMarkdown } from "vitepress-plugin-mermaid";
         ^^^^^^^^^^^^^^^
SyntaxError: Named export 'MermaidMarkdown' not found. The requested module 'vitepress-plugin-mermaid' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'vitepress-plugin-mermaid';
const { MermaidMarkdown } = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:181:5)
    at async Promise.all (index 0)
    at async ESMLoader.import (node:internal/modules/esm/loader:281:24)
    at async loadConfigFromBundledFile (file:///C:/Users/emers/Source/Repos/mermaid/node_modules/vitepress/node_modules/vite/dist/node/chunks/dep-557f29e6.js:63494:21)      
    at async loadConfigFromFile (file:///C:/Users/emers/Source/Repos/mermaid/node_modules/vitepress/node_modules/vite/dist/node/chunks/dep-557f29e6.js:63380:28)
    at async resolveUserConfig (file:///C:/Users/emers/Source/Repos/mermaid/node_modules/vitepress/dist/node/serve-38d4ddb1.js:10747:27)
    at async resolveConfig (file:///C:/Users/emers/Source/Repos/mermaid/node_modules/vitepress/dist/node/serve-38d4ddb1.js:10701:48)
    at async createServer (file:///C:/Users/emers/Source/Repos/mermaid/node_modules/vitepress/dist/node/serve-38d4ddb1.js:36022:18)
    at async createDevServer (file:///C:/Users/emers/Source/Repos/mermaid/node_modules/vitepress/dist/node/cli.js:285:20)
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.	

I did the package library but it should not be imported as CommonJS, removing type: module from package.json makes it work.. but probably breaks everything else... and even in this case the page does not render...

Uncaught TypeError: Cannot read properties of undefined (reading 'accept')
    at VPSkipLink.vue:37:3 

final branch

[emersonbottero]

some updates:

I can change my lib to export mjs files and this should fix the type:module issue..
the the vitepress itself is failing and I'm lookin in to it.

[emersonbottero]

Update..
they found the error and it is already fixed but not released.
vitejs/vite#10207 🎉

[weedySeaDragon]

@emersonbottero @sidharthv96 Is this accomplished? Can it be closed?

If it's not finished, what's left -- and can I help in any way?

[sidharthv96]

The main thing left is supporting rendering using library version of mermaid instead of another plugin. I have a branch that works with sync rendering, but not async (mindmaps).

[sidharthv96]

@weedySeaDragon #3846