Some software documentation websites I’ve seen use two folders, a version directory (e.g., “v1.5”) and a “latest” directory so that users can use a URL to always get the latest docs (e.g., http://docs.example.com/latest/). I’m wondering if there is a best practice for handling this, where the latest doc version is often changing. Could I use the new symbolic link support in Hugo to create a symbolic link for “latest” which always points to the latest version of the generated docs?
If this is reasonable, how would I do this in Hugo?
I’ve thought long and hard about this problem, having built several documentation sites using Hugo, but I honestly haven’t found a better path than simply having separate subdirectories for each version (with the contents of the latest directory being identical with the most up-to-date version). Everything else I’ve tried was too much work, led to maintainability issues, required people to read a lot of docs just to contribute, etc. Would love a more elegant solution but I have my doubts that it’s out there.
@lucperkins is right. You may try to be clever, but you will end up painting yourself into a corner. Hugo, with its static binary (you can version the binary used for a particular version of the docs) comes closer to an alternative solution than the others, but I think the work flow would be:
On release, do a
hugo -d public
hugo -d public/v1.23
Or something like that. The designs will change as time go, but the above is some of the beauty of static. It will survive the next 1000 years.