# Versioned Jupyter Books
**URL:** https://forum.csdms.io/t/versioned-jupyter-books/91
**Category:** General
**Tags:** documentation
**Created:** [January 18, 2025, 7:38am UTC](https://forum.csdms.io/t/versioned-jupyter-books/91 "2025-01-18T07:38:34Z")
**Posts on this page:** 11
**Page:** 1
### Author:  [@samharrison7](https://forum.csdms.io/u/samharrison7)
#### Post date: [January 18, 2025, 7:38am UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/1 "2025-01-18T07:38:34Z")
I’ve been using Jupyter Books to write docs for a while now. E.g. for this model: [https://microplastics-cluster.github.io/fragment-mnp/](https://microplastics-cluster.github.io/fragment-mnp/). I’ve gone for hosting on GitHub Pages as this seemed like a straightforward option, but it has the downside that - as far as I can tell - it’s not possible to have versioned docs.
It looks like the only way to get versioned Jupyter Books is to use Read the Docs, which is only free if you don’t mind some low-key advertising (or pay $5/month). Does anyone have any experience using Jupyter Books with Read the Docs, or alternatively, know of any other solutions to versioned Jupyter Books? Whilst I don’t necessarily mind some low-key adverts, in an ideal world I would prefer a (free) solution without - but maybe I am asking too much there!
---
### Author:  [@wkearn](https://forum.csdms.io/u/wkearn)
#### Post date: [January 18, 2025, 12:32pm UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/2 "2025-01-18T12:32:31Z")
Do you mean versioning like you get on Read the Docs, where you can choose to look at the docs for `v1.2` or `v0.3` or `latest`?
I have wanted to do this for our sphinx-based TopoToolbox documentation, and my research a little while ago didn’t turn up anything that seemed like it would work without a ton of fiddling with sphinx and our CI setup.
However, I just looked around, and I discovered this sphinx extension that I hadn’t seen before: [GitHub - real-yfprojects/sphinx-polyversion: Build multiple versions of your sphinx docs and merge them into one website.](https://github.com/real-yfprojects/sphinx-polyversion). It is recommended in this blog post: [Sphinx Documentation: Hosting Multiple Versions for Your Project | Half-Blood Programmer](https://docs.lextudio.com/blog/hosting-multiple-versions-of-sphinx-documentation/). I might dive into this a little more and see if it would work for TopoToolbox.
---
### Author:  [@samharrison7](https://forum.csdms.io/u/samharrison7)
#### Post date: [January 19, 2025, 8:37pm UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/3 "2025-01-19T20:37:14Z")
> [@wkearn](#):
>
> Do you mean versioning like you get on Read the Docs, where you can choose to look at the docs for `v1.2` or `v0.3` or `latest`?
Yep, exactly that!
Thanks, I will take a look 🙂
---
### Author:  [@RolfHut](https://forum.csdms.io/u/RolfHut)
#### Post date: [January 20, 2025, 1:41pm UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/4 "2025-01-20T13:41:32Z")
the technology we used in the workshop in the Lake District is based on the teachbook framework ([https://teachbooks.github.io/](https://teachbooks.github.io/)). That will generate a seperate page for each branch in your repo. If you make sure that old releases are kept as branches, that would be a easy fix?
---
### Author:  [@BSchilperoort](https://forum.csdms.io/u/BSchilperoort)
#### Post date: [January 21, 2025, 8:55am UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/5 "2025-01-21T08:55:00Z")
> [@RolfHut](#):
>
> That will generate a seperate page for each branch in your repo. If you make sure that old releases are kept as branches, that would be a easy fix?
It could probably also be configured to build tags (i.e. releases) as well as branches. However, they would be rebuilt once the github cache is expired.
---
### Author:  [@samharrison7](https://forum.csdms.io/u/samharrison7)
#### Post date: [January 21, 2025, 10:05am UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/6 "2025-01-21T10:05:32Z")
Thanks both, I didn’t realise Teachbooks did this! I’ll have a look into this as an option.
---
### Author:  [@mcflugen](https://forum.csdms.io/u/mcflugen)
#### Post date: [January 21, 2025, 9:06pm UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/7 "2025-01-21T21:06:55Z")
@samharrison7 I was actually trying to figure out this exact problem just this morning! When we moved our _Landlab_ docs from _[landlab.rtfd.io](http://landlab.rtfd.io)_ to _[landlab.csdms.io](http://landlab.csdms.io)_ we lost the capability to switch between versions of the docs. This means that people now see the docs for the latest development version, not the latest release that would get from _PyPI_ or _conda-forge_.
In my searching I came across [sphinx-contrib/multiversion](http://github.com/sphinx-contrib/multiversion), which looked promising and was going to try out.
---
### Author:  [@mcflugen](https://forum.csdms.io/u/mcflugen)
#### Post date: [January 21, 2025, 9:16pm UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/8 "2025-01-21T21:16:51Z")
_sphinx-polyversion_ also sounds promising. In the blog you link to they say,
> In the past, we evaluated several existing solutions but didn’t find any that fit our needs perfectly. Without naming them…
Ugh, I wish they would just name names! I imagine one of those solutions must have been _multiversion_, which I linked to.
@wkearn If you do dive into this, please keep us updated!
---
### Author:  [@BSchilperoort](https://forum.csdms.io/u/BSchilperoort)
#### Post date: [January 27, 2025, 10:20am UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/9 "2025-01-27T10:20:39Z")
> [@mcflugen](#):
>
> In my searching I came across [sphinx-contrib/multiversion](http://github.com/sphinx-contrib/multiversion), which looked promising and was going to try out.
For docs, I know that MkDocs has a plugin that supports multiple versions; [Setting up versioning - Material for MkDocs](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/)
MkDocs is easier to work with than Sphinx in some ways, but Python API docs don’t look as clear with it sadly.
This is because it uses markdown as an intermediary format (python code → markdown → html docs). Sphinx uses RST which is more versatile, but also more of a hassle when writing normal docs.
---
### Author:  [@mcflugen](https://forum.csdms.io/u/mcflugen)
#### Post date: [January 27, 2025, 11:26pm UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/10 "2025-01-27T23:26:18Z")
> [@BSchilperoort](#):
>
> Sphinx uses RST which is more versatile, but also more of a hassle when writing normal docs.
We’ve started to switch from writing our documentation in reStructuredText to writing it in _myst_, which is really just markdown, and then using the _myst\_sphinx_ extension. The docs look the same but, in my opinion, _myst_ is so much easier to write.
---
### Author:  [@samharrison7](https://forum.csdms.io/u/samharrison7)
#### Post date: [January 28, 2025, 9:07am UTC](https://forum.csdms.io/t/versioned-jupyter-books/91/11 "2025-01-28T09:07:52Z")
> [@mcflugen](#):
>
> We’ve started to switch from writing our documentation in reStructuredText to writing it in _myst_
Same here! I’ve never got on with RST, it always felt too clunky.
I’ll have to check out MkDocs, though I do really like the Python API docs that Sphinx produces.