From 730b0a65900c658f2358e0f1da56e036c625d726 Mon Sep 17 00:00:00 2001
From: Haowei Hsu <hwhsu1231@gmail.com>
Date: Sun, 4 Jan 2026 00:58:45 +0800
Subject: [PATCH] style(uudoc): update header formatting for options and
 examples (#10004)

Adjust the formatting of the options and examples sections in the
uudoc output to use Markdown headers:

- Change `<h2>Options</h2>` to `## Options`
- Change `Examples` to `## Examples`
- Add regression test to prevent reverting to HTML headers
---
 src/bin/uudoc.rs   |  6 ++++--
 tests/uudoc/mod.rs | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/src/bin/uudoc.rs b/src/bin/uudoc.rs
index 5a713e040..392375f9e 100644
--- a/src/bin/uudoc.rs
+++ b/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("- ") {
diff --git a/tests/uudoc/mod.rs b/tests/uudoc/mod.rs
index 4be9803b8..455d3984f 100644
--- a/tests/uudoc/mod.rs
+++ b/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"
+            );
+        }
+    }
+}