Docs' 404 base href #16091
Docs' 404 base href #16091
Conversation
Since the 404 page is served at different (sub)paths in a website, relative references to assets (CSS and JS files) don't work for subdirectories. We now add a `--404-base-href` flag to the docs generator to explicitly set that path. Adding that `<base href />` tag in other pages makes hash refs (`#links`) relative to that path, so that would break every other page.
|
I think this ended up being way too verbose and invovled, but couldn't find a better way to make it: a) configurable; and b) only apply to the 404 page. When we address this issue, we need to update distribution-scripts to add the setting when building the docs. |
|
You can see this in action at https://next.crystal-lang.org/api/1.18.0-dev/Base64/wrong.html |
|
This resonates with #15605 (comment) So we probably don't need a flag for just the 404 page. Since this is easy to drop in via post-processing after the doc generator, I suppose this is also not super urgent to fix. |
| end | ||
|
|
||
| record MainTemplate, body : String, types : Array(Type), project_info : ProjectInfo do | ||
| record MainTemplate, body : String, types : Array(Type), project_info : ProjectInfo, page_type : Symbol? do |
There was a problem hiding this comment.
Nitpick: at this point this would be more readable as a struct (no action required though)
Since the 404 page of the docs is served at different (sub)paths in a website, relative references to assets (CSS and JS files) don't work for subdirectories.
We now add a
--404-base-hrefflag to the docs generator to explicitly set that path.Adding that
<base href />tag in other pages makes anchor links (#links) relative to that path, so that would break every other page (a<base href="/docs" />tag makes an<a href="#heading">link</a>of https://example.com/docs/something.html point to https://example.com/docs/#heading - changing the current page).