Refactor architecture diagram to use mermaid flowchart syntax

[cychitivav]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

Refactored the architecture diagram using Mermaid flowchart syntax to improve readability and enhance the visual representation for a clearer understanding of the project structure, improving professionalism despite losing the URLs of links between blocks.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (2245c64) to head (42d5d7c).
Report is 19 commits behind head on main.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #858   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines         1354      1402   +48     
  Branches       113       114    +1     
=========================================
+ Hits          1354      1402   +48     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[remcohaszing]

I like it. Except that the AST types are now no longer links.

[wooorm]

Looks really tiny to me.
I kinda like ASCII art for programming.

[cychitivav]

I like it. Except that the AST types are now no longer links.

Yes, I noticed that, but I couldn't find any information on how to add URLs to the links within the Mermaid diagrams. As an alternative, I thought of preserving the URLs by adding them as a footer or citation in Markdown, but I'm not entirely convinced.

flowchart LR
  markdown[markdown] --> remark[remark]
  subgraph remarkMarkdown[react-markdown]
    direction LR
    remark -- mdast --> remarkPlugins[remark plugins]
    remarkPlugins -- mdast --> remarkRehype[remark-rehype]
    remarkRehype -- hast --> rehypePlugins[rehype plugins]
    rehypePlugins -- hast --> components[components]
  end
  components --> react[react elements]

  click markdown "https://commonmark.org" "Markdown Specification"
  click remark "https://github.com/remarkjs/remark" "Remark Documentation"
  click remarkPlugins "https://github.com/remarkjs/remark/blob/main/doc/plugins.md" "Remark Plugins"
  click remarkRehype "https://github.com/remarkjs/remark-rehype" "Remark Rehype Documentation"
  click rehypePlugins "https://github.com/rehypejs/rehype/blob/main/doc/plugins.md" "Rehype Plugins Documentation"
  click components "#appendix-b-components" "Components Documentation"

Loading

• mdast: https://github.com/syntax-tree/mdast
• hast: https://github.com/syntax-tree/hast

[wooorm]

I really have my doubts on this. I do not want to live in a world where ASCII-diagrams are unprofessional. I don’t think all those zoom controls are useful. I think this is fine.

@ChristianMurphy I think you originally made this graph? Thoughts?

[remcohaszing]

I like this, but I do have my doubts considering the readme may be displayed in places that don’t support mermaid.

[wooorm]

@ChristianMurphy Ping :)

[ChristianMurphy]

I think you originally made this graph?

I made this, and based it off the style of the unified architecture diagram https://github.com/unifiedjs/unified?tab=readme-ov-file#overview

I quite like Mermaid as a diagramming tool and don't have any objections to moving this over.
It would be kinda nice if the links on the lines could remain, but that's something that may need to be raised upstream at mermaid.

[wooorm]

OK. I will not block mermaid per-se. I personally like ASCII more.

I do think that splitting this graph up into both a graph, and then some links under it, is not an improvement.

If there is a way to fix that, I am 🤷‍♂️ to this PR.
If there currently no way to link mdast and hast, then I am 👎 on this PR. I think @remcohaszing too?

@cychitivav Can you somehow link mdast/hast? Report upstream?

[remcohaszing]

I’m also leaning no, but mostly because the Mermaid diagram might not be rendered in places other than GitHub.

[wooorm]

OK, I’ll close this then. I appreciate you contributing, @cychitivav. Thanks, but no thanks!