Doc links are not consistent on path names

[harrisi]

Describe the bug
The sidebar and the content of the page use different paths for relative links. The sidebar uses *.html#foo, whereas links in the content use *#foo (i.e., no .html). This causes a roundtrip when using both, because the browser doesn't know they're the same page.

To Reproduce

• Navigate to https://www.erlang.org/doc/apps/erts/erl_nif.html
• from the sidebar click on enif_alloc_binary()
  • this will use erl_nif.html#enif_alloc_binary
• click on enif_release_binary link from the description of enif_alloc_binary
  • this will use erl_nif#enif_release_binary
• notice round trip
  • if you then click a link to the same page from the sidebar, there will be another round trip to the erl_nif.html#foo location from erl_nif#bar.

Expected behavior
No round trip for locations in the same page.

Affected versions
Docs issue related to transition to ex_doc, I believe.

Additional context
I'm not sure exactly where or how the sidebar links are being generated. I think it's just an ex_doc configuration issue or something, since this isn't in hexdocs (I checked the Elixir docs on hexdocs).

[garazdawi]

The Erlang docs are hosted on netlify that does "prettying" of URLs which means that among other things they strip the ".html" and seamlessly update all html links to not use it. However, the ExDoc sidebar is rendering using json, so the ".html" is not stripped there which is what you are seeing.

We already do a pass updating the html generated by ExDoc to fix other issues, so also munging the json for the sidebar to strip the html should not be hard.

I'm transferring this issue to the erlang.org repo as that is where the problem should be fixed.

[garazdawi]

Having looked a bit closer it seems like it is ExDoc that does this, specifically the code in this file: https://github.com/elixir-lang/ex_doc/blob/v0.37.2/assets/js/sidebar/sidebar-list.js

There seems to be quite a bit of code in there that assumes that we end in .html...

I'll open an issue on ExDoc and see if anyone there can do something about it.

[garazdawi]

hmm, having looked even closer at it, maybe this is an issue on our end... or rather with how netlify does rewrites of URLs... re-opening and I'll keep digging

[harrisi]

Thanks for looking into this @garazdawi! I'm trying to find the time to poke at this a bit more, but after my initial investigation not turning up anything obvious in configuration files, I was kinda lost as to what's happening and why.

I can't look into it now, but you did make me wonder if hexdocs is doing something to hide this issue? I doubt it, but it's another difference between the erlang and elixir docs.

[garazdawi]

It is netlify that is the source of the problem for us (and why hexdocs does not have any issue).

What netlify does is that they rewrite all <a href="a/b.html"> to <a href="a/b"> in the actual HTML, but we you can still open https://www.erlang.org/doc/apps/stdlib/lists.html (with the .html extension). I was thinking that maybe I should add a redirect that strips the .html, but then you have the problem that the sidebar always adds the .html, so when you click the sidebar it will first go to lists.html#foreach and then redirect to lists#foreach.

It is possible to disable the URL prettying logic in netlify... though it is a bit hard to predict what effects that will have...

[harrisi]

Ah, I see - the sidebar is generated client-side so Netlify doesn't have the chance to remove the .html. I think it ex_doc can just generate based on the URL path since it should run after any modifications from things like Netlify. Maybe it's not the responsibility of ex_doc to worry about that, though.