Organize Mermaid

I think that MermaidJS is a great idea, a language to write diagrams, but this repository needs some organizing because I have seen dead documentation and inconsistent code-style in many places.

Ideas

These are some ideas that I came up with to make mermaid a better project.

• Enforce Code styling I have seen the code having inconsistent code style in many places
  • Add a GitHub Action
  • Add a lint:fix script (#2471)
  • Lint all files
    • Note that for the HTML files, the HTML will have to be escaped to prevent parsing errors and messed up the formatting
    • Use eslint-plugin-markdown (#2530)
    • Use eslint-plugin-html (#2531)
    • Use prettier on all files (not only src/**/*.js)
      • Many files of many types have inconsistent prettier code-style
      • Use prettier-plugin-jsdoc (#2471)
  • Add a commit hook using Husky (#1878) (#2522)
  • Enforce .editorconfig is followed using linters
  • Use stylelint
  • Use eslint-plugin-jsdoc https://npmjs.com/package/eslint-plugin-jsdoc (#2471)
    • When implementing this remember to turn off conflicting rules with prettier-plugin-jsdoc
• Documentation
  • Synchronize README and docs/README (see https://github.com/Yash-Singh1/eslint-plugin-userscripts/blob/main/.github/workflows/readme-in-sync.yml)
  • Synchronize CHANGELOG and docs/CHANGELOG
  • Merge flowchart docs in diagrams-and-syntax-and-examples and at root of docs and move all diagram documentation to diagrams-and-syntax-and-examples
  • Remove theme_themed.css
  • Remove redundant example and code (see https://github.com/mermaid-js/mermaid/pull/2449#issue-770022456) (#2449)
  • Group images in landing inside a new img folder
  • Use markdownlint so the documentation is more maintainable
  • Grammar and casing in multiple files
  • Finish up n00b-advanced.md
  • Reference and update the upgrading.md and breakingChanges.md
  • Search for and remove dead documentation and images
  • Keep syntax and docs in sync (there are many parsing features that are in the code but not in the docs, e.g. #2340, #2275)
    • Maybe make it necessary to document changes to syntax
• Metadata
  • Update descriptions in package.json
  • Actually install defined Husky Hooks (#2522)
  • Move todo.md somewhere else
    • I understand it might be useful for personal notes, but putting that in GitHub projects, or making it more formal as a ROADMAP.md would be better
  • Mark dist/* as linguist-generated
  • Have more specific issue templates (#2739)
    • Diagram Proposals
    • Syntax Proposals
    • Theme Proposals
  • Don’t lock/unlock issues (#967) (#2503)
    • This prevents users from being able to give their ideas against why the issues are closed because there are times when the issue is closed and then another idea is brought up.
  • Add some sort of deploy bot to allow preview of documentation on PRs (maybe Netlify because that is what we use in mermaid-live-editor)
  • Standardize commit message with https://www.conventionalcommits.org/en/v1.0.0/ (#2529)
• Bulid
  • Don’t push dist to GitHub
  • Group webpack files
• Source
  • Add JSDOC to helper functions to help contributors and add IntelliSense (#2464)
  • Switch from Annex B escape and unescape to something else

[knsv]

@financelurker thats a good idea. I think that we are reaching a point where the base package of mermaid needs to be split up. If you don’t care about gantt charts why include and load them? I have been thinking about a lazy loading. This could be another way or even better a part of that setup.

There are some refactoring activities that need to happen first though. The code that initially handled two diagrams is not as clean when handling 10+ diagrams after"organic growth". We need to define what a diagram is so that mermaid can treat them all diagrams in the same way with a basic interface. This is high up on my prioritisation list and diagram organisation is a part of that.

[financelurker]

Well, I don’t know either. But having a look at https://github.com/mermaid-js/mermaid/issues/177 there’s a lot of demand of different and new diagram types. And cleaning up the mermaid architecture (described in my issue here: https://github.com/mermaid-js/mermaid/issues/3061 ) could make adding new diagram types more easy and streamlined (especially for people who don’t want to understand the orchestration-layer of mermaid).