This is more a feature request than a problem.

Problem

As a new user, I find it a bit difficult to orient myself in the documentation files.
It would probably be more beneficial to have a static website with docs.
At the moment there are many problems e.g.:

• index README.md takes the reader to another md and the reader than loses the track of the outline
• Some pages are not up to date with the code: e.g. config file options page is missing privatePackages

Proposed solution

Delivering a website is relatively simple.
Hosting:

• GitHub pages https://pages.github.com/?(null)
• https://readthedocs.org/

There's no need to change anything about markdown since there are static page generators from markdown.
I find these 2 tools the most popular sphinx and mkDocs
More info and more tools are in this article https://dev.to/mxglt/some-great-tools-to-create-a-static-site-from-your-markdown-documentation-mke.

I come from the Python world where 80% of documentation is generated directly from the code. JS/TS has jsdoc which I really like. And static site generators either have plugins for it or there is another way to generate docs from the code.

Examples:

• https://github.com/mozilla/sphinx-js
• https://jsdoc.app/plugins-markdown.html