Add outdated version warning

[danyeaw]

As suggested by @kattni (ty!) during a community call, it is currently easy for users to find a version of our docs that aren't the latest version. This PR adds an outdated mkdocs extension to show a warning with a link to view the latest version. I was trying to go for clear but slightly playful on the message - open to different wording as well.

I tested this locally with:

mike deploy 2025.7.1 latest
mike deploy 2024.12.1 old
mike set-default latest
mike serve

[WebReflection]

Thank you!

[danyeaw]

Thanks @WebReflection for reviewing. I don't have write access to this repo, so you'll have to merge it as well.

[danyeaw]

In order to update all previous versions:

#!/bin/bash
export PYTHONWARNINGS="ignore::UserWarning"

echo "Current versions:"
mike list

versions=$(mike list | grep -v "latest")

for version in $versions; do
    echo "Processing version: $version"
    mike deploy $version
    if [ $? -eq 0 ]; then
        echo "  ✓ Successfully rebuilt $version"
    else
        echo "  ✗ Failed to rebuild $version"
    fi
done

echo "Setting default version..."
mike set-default latest

echo "Final versions:"
mike list

Then git push origin gh-pages or mike deploy --push latest main`.

[WebReflection]

@danyeaw is this something we need to do manually and/or ASAP or just a reminder for the next time we release?

[danyeaw]

Sorry, context is that although this PR updates versions going forward with this logic to show the old version warning. It doesn't update versions that were already released.

After sleeping on it, I don't think that script will work. It will update the previous versions, but will rebuild them all with the content in the current version.

I'll keep thinking about this.

[ntoll]

Hi @danyeaw - I'm finally getting to this PR (stacked on other docs related work I'm currently doing).

I see the changes in #187 - please can you confirm how you did this? I assume some variation of the bash script found in the comments to this PR?

I also notice that config.site_url doesn't resolve so all the links to the latest are ../ (I can easily change this).

I think, given the amount of time since this work was done, I should create a new (stacked-on-current-work) PR and redo these changes for all the versions up to this point in time. Furthermore, I'll confirm such updating of a docs version will work moving forward. I have a sneaky feeling our docs are hosted on S3 so we'll need to (re) copy all the files into the right bucket.

[danyeaw]

Hey @ntoll - ya I think I created a script to go through and update them all. Since we have the version warning on all the versions since the summer already, we shouldn't need to add any additional changes. If you want to try to redo the changes that's ok. I can also rebase the changes or push other updates if needed.