Description
Context
Currently DartDoc emits relative hrefs when linking to another generated page. These hrefs all start from the docs output directory. In order to make these work, each page also includes a <base href /> in the <head> that walks back to the docs output directory (i.e. .. or ../..). For example, consider these sources:
library a;
class Foo {
void hello(Bar bar) { /* ... */ }
}
library b;
class Bar { /* ... */ }The docs tree would partially look like this:
api/docs/
├── a/
│ ├── a-library.html
│ ├── Foo/
│ │ └── hello-method.class
│ └── Foo-class.html
└── b/
├── b-library.html
└── Bar-class.html
In a/Foo-class.html DartDoc emits <base href=".." />, and emits links to Bar in the form of <a href="b/Bar-class.html" />. Such links will be resolved properly as
{api/docs}/a/../b/Bar-class.html => {api/docs}/b/Bar-class.html.
Without the <base href>, the link would go to a nonexistent page: {api/docs}/a/b/Bar-class.html.
While this technique does make the pages quite portable, we can't use it for Markdown output (#1479). Also, there may be hosting situations where this <base href /> isn't ideal or can't be used.
Proposal: absolute hrefs from site root
The current hrefs are already relative to the site root and can be made absolute by placing a / in front: <a href="/b/Bar-class.html" />. Assuming the site root is in fact api/docs/ in our example, these links will always resolve properly. #2089 implements this.
Caveats and concerns
Specifying a site root
Using a different site root requires updating all the generated hrefs. DartDoc could support a site root prefix to hrefs via a new DartdocOption, otherwise clients are left to using a separate process to find and replace the hrefs. This option is under consideration and not yet implemented.
Link validation
DartDoc tries to ensure that generated links lead to valid pages. This process needs to account for the new href format and any new options for a site root prefix.
Transitioning important DartDoc usages
Major users of DartDoc include api.dartlang.org and flutter.dev/api. These and other usages need to be transitioned smoothly.