Hrm, having the links be root-relative is really handy as it makes it easy to find places which link to a given document.

I wonder if there's a configuration option to prefix the links suitably during the build?

The site URL is set to include /runbook in the path, which I was expecting to sort this, although I guess mkdocs doesnt do any kind of link cleaning like this. Unfortunately simply changing the links will break local development, so I suspect we'll need some kind of automated approach.

Hrm, so it looks like mkdocs has explored this in the past, but I'm not really sure of the outcomes of their discussions. Relevant issues I found:

• Allow absolute URLs mkdocs/mkdocs#192
• relative url's can cause bad links mkdocs/mkdocs#77

I think this may mean that we need to use relative urls in the source

I think it's important to fix this and set a precedent for how to do links, ideally before we get too far down the line on this.

I'd therefore like to solicit opinions on whether we want to continue using root-relative links (and roll our own validation, likely with some other tool), or switch to relative links. If we do switch to relative links, input on how we validate that links are spelled properly such that they are validated would also be welcome.

Once we have a conclusion, I'm happy to do the work to migrate us to whatever we choose.

Personally, i'd take the same approach as I do with imports in Python. If the target is lower in the tree, and shares all the same parents (ie you can start it with a ./), it's fine to be relative. Otherwise, make it root relative.

Doing 100% relative is going to lead to craziness if things traverse large sections of the site. Root-relative is annoying, but it's far more sustainable in the longer term IMO.

As I see it, root-relative links have the following advantages:

• they're really easily greppable -- if you want to know all the places that reference some other page, that's a trivial thing to find
• they're super easily spellable -- if you want to link to a page, you can either copy an existing link and/or copy the file's path (and strip the filesystem prefix)
• if you move a page around:
• you don't need to update any of the links within that page
• updating links to that page can (pretty much) be done with a blind find & replace

However, they have the disadvantages that:

• there doesn't seem to be a way to get mkdocs to validate them (even adding the file extension doesn't do it), so we'd need to add some extra checking of our own

They're also verbose, though I can see arguments for this being an advantage as well as a disadvantage (I see it as an advantage).

Location relative links have the following advantages:

• if spelled suitably (i.e: you include the .md file extension), mkdocs will validate the link goes somewhere
• if you do move a whole hierarchy (or sub-hierarchy) around, you don't need to update the "internal" links within that hierarchy (though you still need to update the links from elsewhere or to elsewhere)

Location relative links have the following disadvantages:

• (in general) you can't copy/paste links between documents, meaning that you can't copy/paste blocks of text between documents if you want to move things around
• you can't be entirely sure what the link target is without looking at the actual target document (i.e: the link target is no longer usable as a document id because there might be more than one ./foo.md in different contexts)
• you can have the sense of security that your links are being validated, but them still be broken (if you forget to include the .md file extension); as a result we'd likely want to add some checking of our own anyway

I've just raised mkdocs/mkdocs#1853 regarding a gap in the validation for links which otherwise look internal and mkdocs/mkdocs#1854 for a possible general solution. Neither of these move in the direction we'd wanted (root-relative links), but might yield a compromise we can live with (fully validated relative links).

The changes suggested by #58 should fix this issue. mkdocs doesn't seem to like being hosted on a sub path much, and I think using the GitHub Pages domain doesn't look great, anyway!

I agree plain github pages doesn't look great. We should bear in mind that that could trivially be fixed by proxying the same way the docs (etc.) are proxied. That approach has the benefit that anyone can see how it works and submit patches to change it. As I understand it, the same is not true for a DNS based approach. edit: looks like our dns config is more open than I'd realised.

(sorry, got off track there, will cross post)

we should note that the DNS approach doesn't necessarily fix this as links will still need to be changed to being relative if we want validation.

@RealOrangeOne unfortunately I don't think this is fixed. Consider the link "judge" on https://studentrobotics.org/runbook/competition/matches/commentating/.

I concur.

I think for the sake of mkdocs, we need to be explicitly adding the .md suffix to links, and ensuring they are relative. mkdocs seems to nicely resolve resolve the urls into what they should be come the final output (still relative). When doing this, it also nicely validates links for you, and will fail CI with a bad link.

Going to spend some time going through the pages, and making sure they all work.