I work on the documentation for the Rust programming language. We use Markdown for all our docs. It’s been largely great, and we had a debate long ago about which format to use, and markdown won.
However, there’s one thing about Markdown which is an actual pain point for us, and that’s when it comes to writing API documentation. When referring to another type, having links to that type is great, but it can be a real pain to generate by hand. We currently recommend something like this:
A major drawback of Markdown is that it cannot automatically link types in API documentation. Do this yourself with the reference-style syntax, for ease of reading: /// The [`String`] passed in lorum ipsum... /// /// [`String`]: ../string/struct.String.html
This is manageable, but less than ideal. First of all, it’s a lot to write by hand. But secondly, it can lead to errors: in Rust, a type can appear under two namespaces, which means that these relative links get broken. As an example,
BTreeSet is in two places:
All of the links work in the first case, but not the second case.
The basic position of the Rust team has been “when CommonMark has an extensibility mechanism, we can use it to generate these kinds of links.” I personally care a lot about being compliant; I’d hate to be contributing to even further fragmentation of the Markdown ecosystem. But, as it was helpfully pointed out to me in another thread, it seems like that might take some time. In the meantime, people are feeling a lot of pain around this, and have made various proposals for what we should do; even suggesting we shouldn’t do the linking until it can be made automatic.
All of that is a lot of context and preamble for my real question: What do you all think Rust should do here? Should we invent some sort of Markdown syntax for this, and then try to propose it as an extension? Should we wait until the extensibility proposal is accepted someday, and just deal in the meantime? Should we use regular links, but create some kind of URL scheme that we post-process into “real” URLs? Do some post-processing on our “markdown” files to add the links in ourselves? Something else?
Any thoughts or guidance would be appreciated.
Side note: Due to being a new user, I had to remove a bunch of links in this post, thanks to an anti-spam measure. That’s totally fine, but amusing in a thread about how to properly add links