fix: headings with ids get escaped by comrak

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Version 3.0.4
+
+Fixes: issue with headings ids introduced with 3.0.3
+
+by @hsjobeki;
+
+in https://github.com/nix-community/nixdoc/pull/117.
+
 ## Version 3.0.3
 
 Fixes: shifting issue with commonmark headings https://github.com/nix-community/nixdoc/issues/113

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nixdoc"
-version = "3.0.3"
+version = "3.0.4"
 authors = ["Vincent Ambo <[email protected]>", "asymmetric"]
 edition = "2021"
 description = "Generate CommonMark from Nix library functions"

src/format.rs

@@ -1,8 +1,46 @@
 use comrak::{
+    format_commonmark,
     nodes::{AstNode, NodeValue},
     parse_document, Arena, ComrakOptions, Options,
 };
-use textwrap::dedent;
+use std::io::Write;
+use textwrap::dedent; // For using the write! macro
+
+// Your custom renderer
+struct CustomRenderer<'a> {
+    options: &'a ComrakOptions,
+}
+
+impl<'a> CustomRenderer<'a> {
+    fn new(options: &'a ComrakOptions) -> Self {
+        CustomRenderer { options }
+    }
+
+    fn format_node(&self, root: &'a AstNode<'a>, buffer: &mut Vec<u8>) {
+        for node in root.children() {
+            match &node.data.borrow().value {
+                NodeValue::Heading(heading) => {
+                    // Handling headings specifically
+                    write!(buffer, "{} ", "#".repeat(heading.level as usize)).expect(
+                        "Failed to write UTF-8. Make sure files contains only valid UTF-8.",
+                    );
+
+                    node.first_child()
+                        .map(|child| match child.data.borrow().value {
+                            NodeValue::Text(ref text) => {
+                                write!(buffer, "{}\n", text).expect("Failed to write UTF-8. Make sure files contains only valid UTF-8.");
+                            }
+                            _ => (),
+                        });
+                }
+                // Handle other node types using comrak's default behavior
+                _ => format_commonmark(node, self.options, buffer)
+                    .expect("Failed to format markdown using the default comrak formatter."),
+            }
+            buffer.push(b'\n');
+        }
+    }
+}
 
 /// Ensure all lines in a multi-line doc-comments have the same indentation.
 ///
@@ -79,13 +117,11 @@ pub fn shift_headings(raw: &str, levels: u8) -> String {
     increase_heading_levels(root, levels);
 
     let mut markdown_output = vec![];
+    let renderer = CustomRenderer::new(&options);
+    renderer.format_node(root, &mut markdown_output);
 
-    // This could only fail if we transform the AST in a way that is not supported by the markdown renderer.
-    // Since the AST stems from comrak itself, this should never happen.
-    comrak::format_commonmark(root, &options, &mut markdown_output)
-        .expect("Failed to format markdown");
     // We can safely assume that the output is valid UTF-8, since comrak uses rust strings which are valid UTF-8.
-    String::from_utf8(markdown_output).unwrap()
+    String::from_utf8(markdown_output).expect("Markdown contains invalid UTF-8")
 }
 
 // Internal function to operate on the markdown AST

src/snapshots/nixdoc__test__headings.snap

@@ -6,6 +6,8 @@ expression: output
 
 #### h2-heading
 
+#### h2-heading-with-id {#some-id}
+
 ##### h3-heading
 
 ``` nix

test/headings.md

@@ -2,6 +2,8 @@
 
 ## h2-heading
 
+## h2-heading-with-id {#some-id}
+
 ### h3-heading
 
 ```nix