This is definitely something Rust’s documentation system Rustdoc would like to see in one form or another. We’ve been considering a migration to reStructuredText due to Markdown’s poor standardization, and lack of extensibility. However we prefer markdown for its popularity and simplicity (we want writing docs to be super accessible). Standard Markdown of course resolves the former issue, so having a solution to the latter would be highly desirable!
In particular, we’re interested in being able to write the following extensions:
Mathjax support: adds a new inline and block element with similar semantics to the inline and block code elements that mathjax can correctly handle on the clientside
“Relative” header levels for embedding markdown fragments. That is, # foo isn’t an <h1>, but rather an <h(1 + base_level)>.
Special known sections to be handled differently. Unclear at what level this would be exposed. Just a css class that gets added to be styled/selected on? Or extra metadata returned with the parse to be further used by the caller?
Custom link types. In our case we’d like to be able to say something to the effect of “link to the function/struct/module with this name”.