Markdown to Roff

clap_mangen/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 <!-- next-header -->
 ## [Unreleased] - ReleaseDate
 
+### Features
+
+- Parse markdown in help text and render as roff formatting (bold, italic, code, headings, lists, code blocks, blockquotes, links)
+- New `markdown` feature flag (enabled by default) powered by `pulldown-cmark`
+- Disable with `--no-default-features` to retain previous verbatim rendering
+
 ## [0.3.0] - 2026-03-27
 
 ### Compatibility

clap_mangen/Cargo.toml

@@ -40,14 +40,16 @@ doc-scrape-examples = true
 [dependencies]
 roff = "1.1.1"
 clap = { path = "../", version = "4.0.0", default-features = false, features = ["std"] }
+pulldown-cmark = { version = "0.13", optional = true, default-features = false }
 
 [dev-dependencies]
 snapbox = { version = "1.2.0", features = ["diff"] }
 clap = { path = "../", version = "4.0.0", default-features = false, features = ["std", "help"] }
 automod = "1.0.16"
 
 [features]
-default = []
+default = ["markdown"]
+markdown = ["dep:pulldown-cmark"]
 env = ["clap/env"]
 debug = ["clap/debug"]
 

clap_mangen/README.md

@@ -20,6 +20,28 @@ Dual-licensed under [Apache 2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT).
 
 Generate [ROFF](https://en.wikipedia.org/wiki/Roff_(software)) from a `clap::Command`.
 
+### Markdown Support
+
+By default, markdown formatting in help text is converted to roff:
+
+| Markdown | Man page rendering |
+|---|---|
+| `**bold**` | **bold** |
+| `*italic*` | *italic* |
+| `` `code` `` | **code** (bold, per man page convention) |
+| `## Heading` | Sub-section heading (`.SS`) |
+| `- item` | Bullet list |
+| `1. item` | Numbered list |
+| ` ``` ` code blocks | No-fill blocks |
+| `> quote` | Indented block |
+| `[text](url)` | text `<url>` |
+
+To disable markdown processing and pass text through verbatim (previous behavior):
+
+```console
+$ cargo add --build clap_mangen --no-default-features
+```
+
 ### Example
 
 We're going to assume you want to generate your man page as part of your

clap_mangen/src/lib.rs

@@ -6,6 +6,10 @@
 #![warn(clippy::print_stderr)]
 #![warn(clippy::print_stdout)]
 
+#[cfg(feature = "markdown")]
+mod markdown;
+#[cfg(not(feature = "markdown"))]
+mod plain;
 mod render;
 
 pub use roff;