docs Normalize links

We receive many issues about not working links, e.g. #187 #189 #191 If you look at how we create the links - sometimes it's an absolute and sometimes it's a relative reference. We should use one single, normalised convention for the links and ideally automate checking that none of the links are "dead"

Oct 05 '20 09:10 theimowski

I think the issue is with absolute references - when previewing the docs locally, you get e.g. http://localhost:8000/recipes/build/add-build-script/ vs the docs url is https://safe-stack.github.io/docs/recipes/build/add-build-script/ (note the additional docs/). https://github.com/SAFE-Stack/docs/commit/864695898c79c73ada61c13ec8cc65785468d9a6 is an example of how to fix this by using relative references - that works both for local preview and the "production" docs

/cc @isaacabraham @functionalprogrammer

Oct 05 '20 09:10 theimowski

Serving the docs from http://localhost:8000/docs/ rather than http://localhost:8000/ would probably help with catching broken absolute links during development. Is it possible to get mkdocs serve to do that?

Oct 05 '20 11:10 olivercoad