Closed hsjobeki closed 3 months ago
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2024-04-25-documentation-team-meeting-notes-122/44080/1
@infinisil I know you where busy with some other work. I'd be delighted If you could find time to review this PR or tell me what to do with it.
This PR fixes the problems that where introduced with using any commonmark parser to shift the headings.
Currently nixdoc cannot be used to build the nixpkgs manual. This PR fixes that and also ensures that it remains buildable.
Even though headings might be detected and can be operated on, it became nearly impossible to serialize the parsed tokens/ast of any parser (the rest of the document). Any parser must support ALL underlying extensions that we use in nixpkgs docs. OR alternatively any parser should preserve whitespace and formatting, but i couldnt find any parser amongst the rust ecosystem with such properties.
Solution
The solution now involves to manually track whether we are inside or outside of code-blocks and shift only headings that are not inside a code block and start right at the beginning of the line.
A rather simple state tracking should be a pretty solid solution for the problem.
Also added an additional check to the flake where we build the nixpkgs manual against the current state of nixdoc.
ping @infinisil
Limitations
https://spec.commonmark.org/0.28/#fenced-code-blocks
Commonmark also specifies how unclosed codeblocks behave. We don't support unclosed code blocks.