Provide a way to compile and link to non-README documentation files

[nex3]

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 form https://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.

[donny-dont]

This is similar to the pages support requested at #72

[sethladd]

Cool! Would love to see "pages" support.

[joseluis]

Completely agree. It's specially annoying when using GitHub features like images and emoji that doesn't render properly on dartdoc generated html.

It would be nice to have at least an argument for specifying a custom readme file.

For now what I'm doing is to use a script that switches the README.md file before calling dartdoc, and switching it again after dartdoc finishes.

[sethladd]

patches welcome!

[jcollins-g]

While #72 was closed, this can and should be done as part of #1353; it makes sense for concepts to have documentation in separate markdown files.

[jcollins-g]

#1353 never really addressed the idea of independent page compilation, if I remember correctly it just didn't align with the implementation path. So this still needs to be done for individual pages.