New Documentation Proposal

emersonbottero commented 2 years ago

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 commented 2 years ago

Full working example here

need to search for errors...

sidharthv96 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

sidharthv96 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

sidharthv96 commented 2 years ago

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

emersonbottero commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

emersonbottero commented 2 years ago

1

git clone git@github.com:mermaid-js/mermaid.git
Cloning into 'mermaid'...
git@github.com: 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 commented 2 years ago

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 commented 2 years ago

Update.. they found the error and it is already fixed but not released. https://github.com/vitejs/vite/pull/10207 🎉

weedySeaDragon commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

@weedySeaDragon https://github.com/mermaid-js/mermaid/pull/3846

mermaid-js / mermaid

New Documentation Proposal #3484