Prefer no trailing slash

[LilithHafner]

Right now, https://documenter.juliadocs.org/stable/man/guide#Installation redirects to https://documenter.juliadocs.org/stable/man/guide/#Installation, inserting a trailing slash (before the fragment). Personally, I would prefer the reverse redirect and canonical link. Unless the link is to a directory or container of some sort (as opposed to an ordinary web page) I strongly prefer no terminal slash. I also prefer no terminal slash for landing pages that lie somewhere between terminal pages and directories (e.g. https://documenter.juliadocs.org/stable).

See also: LuxDL/DocumenterVitepress.jl#64

[goerz]

That seems kinda subjective. Aesthetically, I think I have a slight preference for including the slash. Not a strong preference, so I don't really care if we want to change it. But is it worth the effort? I feel like DocumenterVitepress as the "newcomer" should adapt to the existing behavior of Documenter, not the other way around.

Although I am a little confused. I always thought that whether or not there is a final slash is completely handled by the browser, and the two URLs with or without the slash are equivalent as far as the HTTP protocol is concerned.

Regarding LuxDL/DocumenterVitepress.jl#64 (comment)

Documenter.jl's […] places […] path/to/guide/index.html while […] DocumenterVitepress.jl output […] would be stored as path/to/guide.html

I might be wrong, but isn't guide/index.html better if there are embedded files (e.g., plots) in guide.md? You'd probably want them in the HTML with href="plot.png", but then if you had multiple pages with a plot.png, that would become a problem if they're not in individual folders.

So, I think the handling of paths in Documenter with prettyurls=true is pretty good, and we probably shouldn't change it. 🤷‍♂️

[goerz]

Also, isn't the DocumenterVitepress behavior just what Documenter does with prettyurls=false? (Which, if it had been up to me, would never have existed as an option, even though I get why people wanted it)

[goerz]

Based on the explanation in LuxDL/DocumenterVitepress.jl#64 (comment), it seems that the trailing slash is correct, and dropping the slash would be incorrect (it would only work with specific server configurations).

Should we close this?

[goerz]

Maybe closing this was a little premature. Documenter could have an option to generate URLs to folders without a trailing slash (e.g., in the sidebar, and when resolving @ref links), purely as an aesthetic choice. This would be perfectly fine if combined with prettyurls=true. (Well, maybe not "perfectly" since some webservers may not support it). With prettyurls=false, it would prevent previewing the documentation locally: Neither LiveServer nor python -m http.server have the ability to map page to page.html (but they do map page to page/). So that's a pretty big caveat. But if @LilithHafner feels strongly enough about not wanting to see trailing slashes in URLs and wants to implement such an option, that seems worth considering.

It could be an "extra pretty" modification of the existing prettyurls option (prettyurls=:noslash or something) since I don't think we should allow the combination of prettyurls=false and no slashes, even though that is exactly what DocumenterVitepress has)

[mortenpi]

Right now, https://documenter.juliadocs.org/stable/man/guide#Installation redirects to https://documenter.juliadocs.org/stable/man/guide/#Installation, inserting a trailing slash (before the fragment).

Note: this redirect is done by GitHub, not Documenter. So there is nothing we can do (to the best of my knowledge).

Documenter sites are assumed to be hosted as static sites. File-based servers generally (universally? In any case, most importantly, GitHub Pages) 301 redirect /foo -> /foo/. So /foo/ is the correct canonical URL, even if aesthetically /foo looks nicer.

So I don't think this is actionable (unless we want to go back to /foo.html, but between that and /foo/, I'd pick the latter every time).

[LilithHafner]

So there is nothing we can do (to the best of my knowledge).

My recommendation is to put files in /foo.html, use /foo as the user-facing canonical url, and temporarily add a 200 redirect from /foo/index.html to /foo.html for compatibility.

You can see this in action at
https://chairmarks.lilithhafner.com/v1.1.2/explanations
https://chairmarks.lilithhafner.com/v1.1.2/explanations/
https://chairmarks.lilithhafner.com/v1.1.2/explanations.html

IMO Documenter.jl's current approach is a reasonable amount more sensible and understandable for folks looking at the gh-pages branch, and possibly (though unconfirmed) more portable to different static site servers while the approach I use for https://chairmarks.lilithhafner.com is a tiny bit more sensible and understandable for website visitors.

[mortenpi]

That GitHub Pages serves /foo from /foo.html is interesting, but seems to be quite unusual and specific to it. We definitely don't want to break every other static site hosting out there. And while we could theoretically have an option for this, I don't think it's really worth the complexity (plus it would have to be opt-in).

[LilithHafner]

That seems like a reasonable choice. Ultimately its a matter of preference and it's your call.