Hey team

I met null in the JB Nix Nerds matrix space. We've been chatting about how they can get involved and they mentioned they are a Technical Writer. They said they would like to help out so I invited them here and gave them a link to the nixos calendar.

In reply to @deltaflow:matrix.org
Hi all, love Nix, love the community, and looking to help out wherever I can. I'm in technical writing/editing/knowledge management for a telecommunications company by trade, so hoping I can use those skills here.

In reply to @djacu:matrix.org
I can answer some of those questions when I have time. Is it okay to edit that document?

In reply to @jtojnar:matrix.org
The “I installed a library but my compiler is not finding it. Why?” section disappeared between these two revisions but it is not listed in the diff.

In reply to @danielsidhion:nixos.dev
I'm just catching up on (a lot of) discussions, feel free to!

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?

In reply to @antifuchs:asf.computer
Think this is a diff display bug - selecting “visual” instead of “wikitext” shows the removal.

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.