Remove <base href> and emit absolute hrefs instead

[jdkoren]

Markdown will not be able to use <base href>; also, some hosting strategies might not favor its use. Instead we can make model elements have an absolute href by prefixing them with a /.

The major caveat is that the generated docs now must be served from the docs output directory, otherwise those absolute hrefs won't work. This will break clients that place generated docs in a subdirectoy of their served pages, whereas that previously worked fine.

#1479

[devoncarew]

We'd need to make sure that https://api.dartlang.org/ and https://flutter.dev/docs continue to work with this change.

[jdkoren]

We'd need to make sure that https://api.dartlang.org/ and https://flutter.dev/docs continue to work with this change.

Indeed. We're toying with an idea to add a DartdocOption<String> that will be prepended to hrefs for local packages. This way the pages can be served from an ancestor directory, but in that case it does mean clients would need to keep this option in sync with their hosting configuration, which is kind of unfortunate to impose on them.

We could try to keep the existing behavior and have the new behavior gated by some options. Something like

• Keep the <base href> in the code
• Add an option that controls whether <base href> is emitted, with default value true. In this case, DartDoc emits relative hrefs as before.
• Add an option to supply a href prefix. Any value would change the above option to false and DartDoc will emit absolute hrefs.

[jcollins-g]

I like the idea of introducing a flag that defaults to the old behavior for now. It would buy us the time we need to adapt downstream clients.

[jdkoren]

As per discussion in #2090, we are sticking with relative hrefs but using another approach which removes the <base> tag.