I’m using GitHub Pages (Jekyll) to create PREFS python library documentation. And i chose the just-the-docs theme because it easily creates a side bar, the thing is that i need to separate the documentation by version so i created a folder called versions which has as subfolders all versions and all markdown files inside the version subfolders has as permalink their name and the version before, e.g.:
permalink: v0.1.6/home/
and there is the problem, how there are multiple versions of the documentation i see the pages duplicated the time of versions in the side bar:
Right now there are two versions,
v0.1.6 and
v0.1.7, that’s because the pages are duplicated twice.
So my question is: There is a proper way to create versioned documentation? if there is how? if there is no proper way, how could i hide the other version pages when in other version?
This is the GitHub Page: PREFS documentation.
The files are public in gh-pages branch of PREFS repository.
What versioning does is to add subpath like you do with permalink but perhaps you do it as a directory
v1.1.2/
index.md
v1.1.3
index.md
Though the number of files in your repo is going to keep growing rapidly.
Jekyll alone isn’t built to handle documentation at the versioned level like you want and the theme doesn’t have anything that I can see.
My a separate Ruby plugin will help and yoi can add a switch to the menu to go between versions.
The typical way for Python docs is to host on read the docs and the code is for a docs site built in Sphinx, which uses Python.
See this page of the help.
https://docs.readthedocs.io/en/stable/versions.html
Note also the v:latest bit in the bottom left of the page to switch versions.
Or this R package which has a great variety of stable, latest and v1.x versions to choose from.
https://xgboost.readthedocs.io/en/latest/R-package/index.html#
Sphinx supports Markdown and reStructuredText so you can write your docs like before and you won’t have to worry about a theme. You’ll just have to leave Jekyll behind.
Or maybe versioned documentation is not so important - someone could always serve up an older tag docs site of yours if they really need it.
You can also try GitBook, which gives you one free public site to host and you can optionally control the site using a repo, so that is close to a Jekyll experience.
I tried to use readthedocs but i though it would be easy to version the documentation for my own (because using readthedocs the versions are tags of the repository and i don’t like that because if i misspell some word or something i can’t fix it).
Anyway, thanks for the answer. i will pass my docs to readthedocs.
1 Like
OK thanks for the update.
Check out some spellcheck in VS Code or some CLI one you can run against your entire site at build time so you can fix issues before tagging.
1 Like
Yes, i will do that but i would like that i could edit the tags manually.
If your repo is public, could you share a link?
Now the files are for readthedocs.
A shame that this is so hard to manage in Jekyll, really wish they would develop a feature for making versioned content easier. they could go the same way as docusaurus
1 Like
Does Docusaurus the same things as readthedocs? I mean if i can use it with the readthedocs files?
As long you use markdown you should be able to migrate
