link-from-latest-to-stable.md

Linking from /latest/ to /stable/ 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:

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:

{% block footer %}
{{ super() }}
<script>
jQuery(function ($) {
  // Show banner linking to /stable/ if this is a /latest/ page
  if (!/\/latest\//.test(location.pathname)) {
    return;
  }
  var stableUrl = location.pathname.replace("/latest/", "/stable/");
  // Check it's not a 404
  fetch(stableUrl, { method: "HEAD" }).then((response) => {
    if (response.status == 200) {
      var warning = $(
        `<div class="admonition warning">
           <p class="first admonition-title">Note</p>
           <p class="last">
             This documentation covers the <strong>development version</strong> of Datasette.</p>
             <p>See <a href="${stableUrl}">this page</a> for the current stable release.
           </p>
        </div>`
      );
      warning.find("a").attr("href", stableUrl);
      var body = $("div.body");
      if (!body.length) {
        body = $("div.document");
      }
      body.prepend(warning);
    }
  });
});
</script>
{% 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:

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

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

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.

# -- Version Warning Banner configuration ------------------------------------
versionwarning_messages = {
    'latest': 'This is a custom message only for version "latest" of this documentation.',
}
versionwarning_admonition_type = 'tip'
versionwarning_banner_title = 'Tip'
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