Page styles and links broken on angular_components StepDirective page

[chalin]

The Problem

Visiting https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective results in an unstyled page:

The problem is that the page contains <base href="../.."> but the style files are at ...

Why its happening

The cause of the problem is that StepDirective has a field named index, and so the API doc page for this field is index.html. A get request for

• https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective results in
• https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective/index.html being returned.

One might argue that we shouldn't be attempting to access https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective, but it isn't that simple as I explain next.

API docs on webdev.dartlang.org

For a server configured to support clean URLs w/o trailing slashes, a request for

• https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective/index.html
• Will be redirected (HTTP status code 301), to https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective

Solution ideas

A possible solution might be to have a dartdoc option in support of doc servers configured with clean URLs and no trailing slashes. This option would ensure that the base href for API pages named index.html gets set to .. rather than ../...

Another option might be to set the base href dynamically, but that might get tricky.

Note that in the meantime I've been manually patching the generated API docs, setting the base href to a proper value.

cc @kwalrath @kevmoo @nshahan

[jcollins-g]

Another possibility is to never create index.html files and instead use a special, non-colliding name in this case. IIUC that would create the desired behavior (404 not found for https://pub.dartlang.org/documentation/angular_components/0.9.0-beta/material_stepper_material_step/StepDirective) while still allowing us to link to the index property elsewhere.

Dartdoc already does some special things to avoid collisions in naming files so this isn't that outrageous, but it might be one of the first user-visible changes to the linking strategy.

[chalin]

Another possibility is to never create index.html files and instead use a special, non-colliding name in this case.

Interesting proposal.

IIUC that would create the desired behavior

Yes.

it might be one of the first user-visible changes to the linking strategy

Ah, well, that is something to ponder as it would be a precedent (re. user-visible linking strategies).