Observed

All Mermaid visualizations take the full width of the documentation page. This means that smaller Mermaid diagrams are displayed much bigger than larger Mermaid diagrams. For the purpose of documentation, Mermaid diagrams are sometimes intentionally small, in order to show a small example. Specifically, this makes the text in smaller Mermaid diagrams much bigger than the running text.

The following screenshot was made on the graph validation page for TriplyETL:

Expected

The ability to determine the display width of Mermaid diagrams. This allows us to tune the size of the diagram such that the text inside the diagram is comparable in size to the running text.

Requirements

• The currently visited page is not highlighted in the left-hand menu.

• The chapters inside a page (h2) are not visible in the left-hand menu. This makes it difficult to find the right version number on the changelog page, or the right function name of a page that documents several functions.

Nice to have

• Red is not a good color for in-line code. It looks too much like something is wrong ("error"), especially when scrolling through a page.

• The vertical space between "Bugfixes:" and the item list of bugfixes is too big. It is currently equivalent to the vertical space between two block elements that are distinct (e.g. two pragraphs). But in an item lists, the introduction and the items belong together. This may not be fixable in ReadTheDocs, because it requires me to write an item list as follows:

Bugfixes:

- Installation on Windows.
- Fixed warnings for a dependency (async-saxophone for XML processing), which did not yet officially support Node.js 18.

Instead of:

Bugfixes:

- Installation on Windows.
- Fixed warnings for a dependency (async-saxophone for XML processing), which did not yet officially support Node.js 18.

So there is not way to distinguish a regular paragraph from a paragraph that introduces an item list.

This issue also exists in the real ReadThe Docs (e.g. https://docs.conan.io/2/tutorial/consuming_packages/cross_building_with_conan.html).

On Windows I get the following error:

PS > python -m mkdocs serve    
ERROR   -  Config value 'plugins': The "mermaid2" plugin is not
           installed

Aborted with 1 configuration errors!