on Read The Docs#

Read The Docs has a handy feature where documentation for older versions will automatically link to the latest release, for example on this page:

A documentation page with a note that says: You are not reading the most recent version of this documentation. 0.60 is the latest version available.

That feature is enabled by a “Show version warning” check box in their Advanced Settings preference pane.

It’s implemented by this JavaScript in their default theme, called from here.

I had an extra requirement: I wanted pages on my /en/latest/ documentation (which shows documentation for the in-development main branch on GitHub) to link back to the /en/stable/ equivalent - but only if that page also existed in the stable documentation.

I ended up adding this snippet of jQuery JavaScript to my custom docs/_templates/layout.html template:

1
{% block footer %}
2
{{ super() }}
3
<script>
4
jQuery(function ($) {
5
  // Show banner linking to /stable/ if this is a /latest/ page
6
  if (!/\/latest\//.test(location.pathname)) {
7
    return;
8
  }
9
  var stableUrl = location.pathname.replace("/latest/", "/stable/");
10
  // Check it's not a 404
11
  fetch(stableUrl, { method: "HEAD" }).then((response) => {
12
    if (response.status == 200) {
13
      var warning = $(
14
        `<div class="admonition warning">
15
           <p class="first admonition-title">Note</p>
16
           <p class="last">
17
             This documentation covers the <strong>development version</strong> of Datasette.</p>
18
             <p>See <a href="${stableUrl}">this page</a> for the current stable release.
19
           </p>
20
        </div>`
21
      );
22
      warning.find("a").attr("href", stableUrl);
23
      var body = $("div.body");
24
      if (!body.length) {
25
        body = $("div.document");
26
      }
27
      body.prepend(warning);
28
    }
29
  });
30
});
31
</script>
32
{% endblock %}

The neatest piece of this solution is the way it uses an HTTP HEAD request via fetch() to confirm that the equivalent stable page exists before adding a link to it:

1
  var stableUrl = location.pathname.replace("/latest/", "/stable/");
2
  // Check it's not a 404
3
  fetch(stableUrl, { method: "HEAD" }).then((response) => {
4
    if (response.status == 200) {
5
      // Add the link

Here’s what my fix looks like, running on https://docs.datasette.io/en/latest/csv_export.html

This page has a banner that says: This documentation covers the development version of Datasette. See this page for the current stable release.

Alternative solution: sphinx-version-warning#

Just minutes after I committed my fix I was informed of the existence of sphinx-version-warning, a Sphinx plugin that can solve this problem too. There’s an example of using that to add a message to the /latest/ page in its own documentation configuration here.

1
# -- Version Warning Banner configuration ------------------------------------
2
versionwarning_messages = {
3
    'latest': 'This is a custom message only for version "latest" of this documentation.',
4
}
5
versionwarning_admonition_type = 'tip'
6
versionwarning_banner_title = 'Tip'
7
versionwarning_body_selector = 'div[itemprop="articleBody"]'

I decided to stick with my version, mainly because I like the fetch() solution I used.

GitHub issue: Documentation should clarify /stable/ vs /latest/ #1608

Newsletter

Linking from /latest/ to /stable/ on Read The Docs#

Alternative solution: sphinx-version-warning#