search

nix-community / nixdoc

Tool to generate documentation for Nix library functions [maintainer=@infinisil]
GNU General Public License v3.0
123 stars 15 forks source link

fix: headings with ids get escaped by comrak #117

Closed hsjobeki closed 4 months ago

hsjobeki commented 4 months ago

The problem was that headings with id got escaped by the default formatter of comrak.

# heading {#some-id} -> # heading {\#some-id}

Unfortunately it seems there is no option or other crate that allows easy bi-directional serializing of common mark.

All other options i investigated require an incredible amount of work. (i.e. pulldown-cmark requires wiriting a complete engine, that handle all ast cases and sub node cases)

I fixed that issue now by implementing a custom formatter, that uses comrak::format_commonmark for all nodes except for headings.

Fixes: https://github.com/NixOS/nixpkgs/pull/303330.

nixos-discourse commented 4 months ago

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-04-11-documentation-team-meeting-notes-118/43203/1