-
-
Notifications
You must be signed in to change notification settings - Fork 13.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
nixos-render-docs: cannot render commonmark #280514
Comments
it's not just a lint. headings always need ids to be linked from a TOC, and those ids should be stable so you can pass those links around to other people. in the general case we want missing ids to be a hard error instead of generating something because we can't trust any generation method to remain stable without keeping a bunch of conflict-ridden state in nixpkgs.
and that's totally fair! for nixdoc comments it'd be fine to enable auto-generated heading ids since nixdoc is a trustworthy tool. why not add an |
@pennae what do you mean by I found this (not sure if it is the right file) Line 5 in 3763c9f
Would that become something like that? # Functions reference {#chap-functions}
The nixpkgs repository has several utility functions to manipulate Nix expressions.
```{=include=} sections auto-id-prefix="sec-functions"
functions/library.md
functions/generators.section.md
functions/debug.section.md
functions/prefer-remote-fetch.section.md
functions/nix-gitignore.section.md
```
Could you point me to the right file where the id generation would happen? |
pretty much, yep. we'd suggest using
you'll probably want to expand on this infrastructure with a global namespaces that's handled in the base converter |
This issue has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2024-01-25-documentation-team-meeting-notes-106/38792/1 |
I hope for some help from the community here ❤️
Describe the bug
If you feed the nixos-render-doc with regular commonmark; for example:
Tagline # Example Foo content
This won't render because the tool expects an id for each heading.
This is a problem with doc-comments and documentation that originates from the nix source code. Nobody really wants to write heading ids for each heading in a doc-comment. which should also be unique across whole nixpkgs.
Expected behavior
Commonmark as of RFC72 is the official format for documentation.
Also with RFC145 we agreed that the Commonmark format is a valid format for documentation in nix doc-comments.
A related discussion about this was in one of the recent documentation team meetings.
https://discourse.nixos.org/t/2024-01-04-documentation-team-meeting-notes-102/37754/1
There are some different perspectives on how you could perceive this kind of problem.
bad.nix
Those heading ids could be optional / and or autogenerated for doc-comments.
Notify maintainers
@pennae @SuperSandro2000
What do you think
I looked for quite some hours into nixos-render-docs. But I couldn't manage to find a proper solution for this.
I prepared these PRs:
nixos-render-docs is the last piece that is missing to clear the migration path.
It would be so nice if you can help me tackle the problem. ❤️
--
Add a 👍 reaction to issues you find important.
The text was updated successfully, but these errors were encountered: