style(uudoc): update header formatting for options and examples

src/bin/uudoc.rs

@@ -465,7 +465,9 @@ impl MDWriter<'_, '_> {
     /// # Errors
     /// Returns an error if the writer fails.
     fn options(&mut self) -> io::Result<()> {
-        writeln!(self.w, "<h2>Options</h2>")?;
+        writeln!(self.w)?;
+        writeln!(self.w, "## Options")?;
+        writeln!(self.w)?;
         write!(self.w, "<dl>")?;
         for arg in self.command.get_arguments() {
             write!(self.w, "<dt>")?;
@@ -576,7 +578,7 @@ fn format_examples(content: String, output_markdown: bool) -> Result<String, std
     use std::fmt::Write;
     let mut s = String::new();
     writeln!(s)?;
-    writeln!(s, "Examples")?;
+    writeln!(s, "## Examples")?;
     writeln!(s)?;
     for line in content.lines().skip_while(|l| !l.starts_with('-')) {
         if let Some(l) = line.strip_prefix("- ") {

tests/uudoc/mod.rs

@@ -132,3 +132,39 @@ fn test_manpage_base64() {
     assert!(output_str.contains("base64 alphabet"));
     assert!(!output_str.to_ascii_lowercase().contains("base32"));
 }
+
+// Test to ensure markdown headers are correctly formatted in generated markdown files
+// Prevents regression of https://github.com/uutils/coreutils/issues/10003
+#[test]
+fn test_markdown_header_format() {
+    use std::fs;
+
+    // Read a sample markdown file from the documentation
+    // This assumes the docs have been generated (they should be in the repo)
+    let docs_path = "docs/src/utils/cat.md";
+
+    if fs::metadata(docs_path).is_ok() {
+        let content =
+            fs::read_to_string(docs_path).expect("Failed to read generated markdown file");
+
+        // Verify Options header is in markdown format (## Options)
+        assert!(
+            content.contains("## Options"),
+            "Generated markdown should contain '## Options' header"
+        );
+
+        // Verify no HTML h2 tags for Options (old format)
+        assert!(
+            !content.contains("<h2>Options</h2>"),
+            "Generated markdown should not contain '<h2>Options</h2>' (use markdown format instead)"
+        );
+
+        // Also verify Examples if it exists
+        if content.contains("## Examples") {
+            assert!(
+                content.contains("## Examples"),
+                "Generated markdown should contain '## Examples' header in markdown format"
+            );
+        }
+    }
+}