Site-wide redirects

GitHub Help GitHub Pages
#1

I’m publishing multiple versions of my docs to GitHub Pages. I did this by setting up my Pages branch with the following file structure:

index.html  # this is just a redirect to the latest version, e.g. versions/v0.1.0/
versions/v0.1.0/index.html

This works great, except that I can’t have any permanent links! For example, if I want to link to a page content.html at versions/v0.1.0/content.html, once I release v0.1.1 this link will still work, but it will forever link to an outdated version. Ideally, I would link to /content.html and it would redirect to the current version.

This feature is supported in ReadTheDocs via redirects: Automatic Redirects — Read the Docs 5.9.0 documentation

The only way I can think of to get this working is to make a custom 404.html that then runs some JavaScript to parse the URL, check if no version is present, and if so redirect to the latest version. But this seems hacky. I want to see if anyone here can think of a better way?

#2

I resolved this using symlinks. You just create a symlink like:

index.html  # redirect to latest/index.html
latest  # a symlink to versions/v0.1.0/index.html; you need some CI to update this when a new version comes out
versions/v0.1.0/index.html