Markdown parsing in doc comments for help messages Tracking Issue #5900
Description
This tracks the feature unstable-markdown that implements compile time markdown parsing in the derive macros.
Implemented Markdown features
| markdown | output | comment |
|---|---|---|
| paragraph | joined on one line, surrounded by empty line | |
# heading |
bold + underline + surrounded by empty line | default style for heading |
![image]() |
alt text | anyone feeling sixel?! |
<html> |
verbatim | |
> blockquote |
 |
alternatively could use > |
| code block |  |
same styling as `code` |
| (un)ordered lists |  |
|
*emphasis* |
italic | |
**strong** |
bold | |
~stikethrough~ |
strikethrough | |
[link](url) |
underlined alt text + OSC 8 | |
`inline code ` |
bold | default style for literal |
--- hrule |
--- surrounded by empty lines |
|
| tables | |
verbatim | |
\\\n and \n hard break |
ends line |
Open Questions
- unicode support i.e.
•for bullet lists,Options::ENABLE_SMART_PUNCTUATIONforpulldown_cmark, unicode lines for blockquotes - using the default clap styling for code makes it the same to bold.
- should we make images a link to the image source
- should we add custom html tags a la https://docs.rs/color-print/latest/color_print/ this would allow users to use colors without us actually supporting runtime style information.
- should we use other enumeration for nested lists? e.g.
a.,b.andi.,ii.? we could use https://docs.rs/nominals for that - styling for code blocks and block quotes
- separate control of OSC 8 for links & colors
- option to display URLs next to links.
- option to diplay URLs at the end of the help.
Markdown Parser
See https://github.com/rosetta-rs/md-rosetta-rs for a comparison of parsers.
pulldown-cmark
Same behavior as rustdoc (options for reference https://github.com/rust-lang/rust/blob/59588250ad973ce69bd15879314c9769e65f36b3/compiler/rustc_resolve/src/rustdoc.rs#L244-L250).
But higher compile times, runtime performance probably not as impactful as we are doing it at compile time.
minimad
Had some parsing issues but might be fixable.