Book: Broken anchor-links because of HTML base-tag

[benediktwerner]

All the anchor links in the book are broken because of the base tag that is inserted on every page.

When a base tag is present the anchor link will be relative to the base address instead of the current page so, for example, clicking on a heading on this page redirects to the index page.

I'm not sure why there even is a base tag in the first place but it seems to be added by this CI script according to the value from here.

The easiest fix would be to remove the base tag. I don't think there is a reason for it. Other rust books also don't use one and since mdBook pages are all on the root level stuff like CSS will still be loaded from the correct path.

[benediktwerner]

Looking into this some more it seems the base tag was just added today by 335f930 in #186.

I still don't understand why this was required but it looks like mdBook had some issues with this before and this change removed all base tags. The recommended way seems to be to always use relative URLs and if necessary prepend URLs with {{ path_to_root }}. See also: https://rust-lang.github.io/mdBook/format/theme/index-hbs.html.

[baszalmstra]

Aj that is a problem.

We inserted the base tag because we host both the v0.2 and the master docs on the same website. But we proxy everything from v0.2 to https://release-v0-2.docs.mun-lang.org/ which is the subdomain that hosts the v0.2 docs (which is auto updated on pushes to the release/v0.2 branch). However, that caused all links on the v0.2 pages to point to pages without v0.2 in the urls. Thats why we added the base tag.

We'll have to find a better way to do this because its already kind of a hack.

[benediktwerner]

Hm, I still don't quite get the problem. If I'm on a /v0.2/... page and all links are relative (which they are as far as I can see) shouldn't you always stay on /v0.2/...? A proxy shouldn't really matter since the link address is determined by the browser.

[baszalmstra]

Im not sure whats happening but if you remove the base tag from the html all links point to a non v0.2 url. You can try it by removing the tag from your browsers development tools. Even if I change the href to ./some_link.html. I guess this has something to do with netlify redirects but I cant figure out why if I look at the response. Do you have an idea?

[baszalmstra]

Okay so I figured out what the issues is:

When browsing https://docs.mun-lang.org/v0.2 all relative urls are relative to the parent path of that url which in this case is: https://docs.mun-lang.org. However, if I add a slash behind the url (https://docs.mun-lang.org/v0.2/) the parent path url stays the same https://docs.mun-lang.org/v0.2/.

However, these is an issue with netlify where it is currently impossible to add a slash to the url. (https://community.netlify.com/t/bug-in-non-trailing-slash-rewrite/452/38)

For now, I will remove the base tag and see if I can add this snippet of javascript code to the index page:

if(!window.location.pathname.endsWith("/")) {
  window.location = window.location + "/"
}

Then we also no longer need the silly mdbook workaround and we can speed up the generation of the book drastically. (Related to #190)

[benediktwerner]

Ok, that makes sense. It only happens on https://docs.mun-lang.org/v0.2 which you can only get to when using an external link or typing the URL in by hand since all the actual links on the page are https://docs.mun-lang.org/v0.2/xxx.html but of course, if you start on /v0.2 all the links will be broken and you can't get to the pages that work. But this also explains why I didn't notice any problems before since I actually tried deleting the base tag but only after I was already on a .html page.

Well, the JavaScript is quite hacky but at least it works now, and hopefully, Netlify will fix this soon.