issue_comments

Got a couple of TILs out of this:

• Promoting the stable version of the documentation using rel=canonical
• Linking from /latest/ to /stable/ on Read The Docs

https://sphinx-version-warning.readthedocs.io/ looks like it can show a banner for "You are looking at v0.36 but you should be looking at 0.40" but doesn't hand the case I need here which is "you are looking at /latest/ but you should be looking at /stable/".

Correction! That tool DOES support that, as can be seen in their example configuration for their own documentation:

https://github.com/humitos/sphinx-version-warning/blob/a82156c2ea08e5feab406514d0ccd9d48a345f48/docs/conf.py#L32-L38

python 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"]'

https://sphinx-version-warning.readthedocs.io/ looks like it can show a banner for "You are looking at v0.36 but you should be looking at 0.40" but doesn't hand the case I need here which is "you are looking at /latest/ but you should be looking at /stable/".

Just shipped my fix here: https://docs.datasette.io/en/latest/

Here's a jQuery recipe that seems to do the right thing: javascript jQuery(function ($) { // If this is a /latest/ doc page, show banner linking to /stable/ 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); } }); });

Turns out that banner is something that ReadTheDocs implemented - I found it using GitHub code search, it's produced by this piece of JavaScript: https://github.com/readthedocs/readthedocs.org/blob/0852d7c10d725d954d3e9a93513171baa1116d9f/readthedocs/core/static-src/core/js/doc-embed/version-compare.js#L13-L21

```javascript function init(data) { var rtd = rtddata.get();

/// Out of date message

if (data.is_highest) {
    return;
}

var currentURL = window.location.pathname.replace(rtd['version'], data.slug);
var warning = $(
    '<div class="admonition warning"> ' +
    '<p class="first admonition-title">Note</p> ' +
    '<p class="last"> ' +
    'You are not reading the most recent version of this documentation. ' +
    '<a href="#"></a> is the latest version available.' +
    '</p>' +
    '</div>');

warning
  .find('a')
  .attr('href', currentURL)
  .text(data.slug);

var body = $("div.body");
if (!body.length) {
    body = $("div.document");
}
body.prepend(warning);

} ```

And here's where that module is called from the rest of their code: https://github.com/readthedocs/readthedocs.org/blob/bc3e147770e5740314a8e8c33fec5d111c850498/readthedocs/core/static-src/core/js/doc-embed/footer.js#L66-L86

I'm tempted to imitate their JavaScript but check for /latest/ in the URL and use that to append a similar message warning about this being the documentation for the in-development version.

Huh, I had forgotten I already have a banner on older versions:

Might want to consider SEO here too - I want people from search engines to land on /stable/, I wonder if I should noindex or rel=canonical the other documentation versions? Not sure what best practices for that is.

I think I want a banner at the top of the page making it obvious which version the documentation is talking about. This can be pretty low key for the current stable release, but should be visually more prominent for the /latest/ branch and for older releases.