Open
Description
Here's my use case: I'm working on test
, and the documentation is bigger than a single README file. I've already got JSON reporter protocol docs, and I'm planning to add documentation for the configuration file format pretty soon. I want the following things:
- I want this documentation to be easily consumable on dartdocs.org.
- I want it to also be easily consumable on GitHub.
- At least on dartdocs.org, I want it to be versioned—that is, if a user is looking at the dartdocs for version 0.12.10, they see version 0.12.10 of the README and the JSON reporter protocol as well.
There's not a great way to do this right now. There's no way to get dartdoc to compile any pure-Markdown documentation other than the README, and GitHub isn't versioned at all.
I propose the following solution:
- Crawl the README for links to other documents ending in
.md
. This should naturally support relative URLs, but it should also support links of the formhttps://github.com/____/${package}/blob/____/${path}.md
. - For each link, check for the corresponding path in the package. If it exists, compile it as Markdown and include it in the dartdoc output.
- Update the links to point to the dartdoc-compiled pages rather than their original destinations.
This would allow users to write multi-page documentation that Dartdoc supports properly, while still linking to the GitHub versions of those docs for GitHub users.