issue_comments

It's working again now: https://docs.datasette.io/en/latest/sql_queries.html

ChatGPT prompt:

`` 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 = $(

Note

This documentation covers the development version of Datasette.

See this page for the current stable release.

` ); warning.find("a").attr("href", stableUrl); $("article[role=main]").prepend(warning); } }); });

Rewrite this to use vanilla JavaScript, no jQuery ```

Got back:

javascript document.addEventListener("DOMContentLoaded", 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 = document.createElement("div"); warning.className = "admonition warning"; warning.innerHTML = ` <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> `; var mainArticle = document.querySelector("article[role=main]"); mainArticle.insertBefore(warning, mainArticle.firstChild); } }); });

Still getting this error:

Weird because jQuery is present in the devtools console.

That didn't work, because jQuery isn't yet defined that high up the template.

I should use {% block scripts %} instead: https://github.com/pradyunsg/furo/blob/05350110cf02d033ebb57147eb54e9371a63545a/src/furo/theme/furo/base.html#L89-L102

This broke when I upgraded to the Furo theme.

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/

Or you can use https://sphinx-version-warning.readthedocs.io/! 😄

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.