In reply to @djacu:matrix.org

So I created a new column for mkdocs with the Material theme. I've used it in the past and significantly improves the UX of mkdocs. I've answered most of the questions for that combo and I'll try to answer the questions for mkdocs by itself.

I don't understand some of the questions being asked. Could you elaborate on the following?

• Can we deep-link anywhere in the text? (Do you mean literally anywhere or just headers?)
• Does it support tagref or anything similar? (Can you give an example?)
• Does it support the example notation we currently use? (Can you give an example?)
• Can we get a list of all possible links that someone may use?
• How can we generate option docs with it? (I was under the impression that option docs can output to json or markdown. And you would want to create a webpage from that?)
• Can we render it to multiple pages?
• Can we fit the nixos module documentation in it?

• Can we deep-link anywhere in the text? (Do you mean literally anywhere or just headers?)
  • Literally anywhere (e.g. currently we can use {}[#custom-header] almost anywhere in the text and we'll be able to link to that specific part)
• Does it support tagref or anything similar? (Can you give an example?)
  • I added a link to https://github.com/stepchowfun/tagref in the spreadsheet. I was referring to that project (or anything that tries to achieve the same thing)
• Does it support the example notation we currently use? (Can you give an example?)
  • https://github.com/NixOS/nixpkgs/blob/1f82020865a982a3f82934b420165ceb331a3505/doc/README.md?plain=1#L120-L125
• Can we get a list of all possible links that someone may use?
  • Read https://discourse.nixos.org/t/a-roadmap-for-the-documentation-ecosystem/42328/5 and some of the discussion there for more info. What this question asks is "does this framework generate a 'report' of all URLs (including fragments) that are valid with the current content, or does it make this possible in some way?".
• How can we generate option docs with it? (I was under the impression that option docs can output to json or markdown. And you would want to create a webpage from that?)
  • Primarily for backwards compatibility (since we already have a webpage with them), yes. It's possible that further modification of the option docs output will be needed, or there might be other interesting ways to display its contents, which is why this question is there.
• Can we render it to multiple pages?
  • Whether the entire content can be rendered as a multi-page doc (with working crosslinks) rather than the current single-page one.
• Can we fit the nixos module documentation in it?
  • The nixos module documentation is generated dynamically (see https://github.com/NixOS/nixpkgs/blob/ad2096e23d09a67fdbbcd92e068db4119b0999fe/nixos/doc/manual/default.nix#L84-L87 ). This question is whether (and very high level of how) we'd be able to fit that stuff into the framework.

In reply to @sandro:supersandro.de
IMO slightly overengineered but here we are

In reply to @djacu:matrix.org
fricklerhandwerk: alejandrosame I took a look through the code and wrote a comment with a simplified version of the code. Let me know what you all think.