added instructions for checking out and updating specific releases (#6095)

* added instructions for checking out specific releases and also moved the bit about $GH_TOKEN to a place above
the pip install instructions
* separated out update instructions, revised git instructions
* bumped version number that insiders is based on
* removed --upgrade from update command
* made insiders changelog a section
* changed instructions for upgrading via git

docs/insiders/changelog/index.md

@@ -1,4 +1,3 @@
-# Changelog
 
 ## Material for MkDocs Insiders
 

docs/insiders/getting-started.md

@@ -30,20 +30,38 @@ your GitHub account in order to access the Insiders repository programmatically
   [Generate a new token]: https://github.com/settings/tokens/new
   [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
 
+Some of the instructions below require that the `GH_TOKEN` environment
+variable is set to the value of the personal access token you
+generated in the previous step. Note that the personal access token
+must be kept secret at all times, as it allows the owner to access
+your private repositories.
+
 ## Installation
 
 ### with pip
 
-Material for MkDocs Insiders can be installed with `pip`:
+Material for MkDocs Insiders can be installed with `pip`. You will
+normally want to install the latest release but can also install a
+specific older release or even the latest development version. 
+Make sure you have the `GH_TOKEN` variable set as instructed above.
+
+=== "Specific release"
+
+    Pick the corresponding tag from the [list of tags] for the Insiders 
+    repository. In the `pip` command below, replace the tag at the 
+    end of the URL with the one you want.
+
+    ``` sh
+    pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
+    ```
+
+=== "Latest"
 
     ``` sh
     pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
     ```
 
-The `GH_TOKEN` environment variable must be set to the value of the personal
-access token you generated in the previous step. Note that the personal access
-token must be kept secret at all times, as it allows the owner to access your
-private repositories.
+[list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags
 
 ### with docker
 
@@ -129,27 +147,6 @@ pip install -e mkdocs-material
   [Pull App]: https://github.com/apps/pull
   [publish]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml
 
-## Upgrading
-
-When upgrading Insiders, you should always check the version of Material for
-MkDocs which makes up the first part of the version qualifier, e.g.Insiders
-`4.x.x` is currently based on `8.x.x`:
-
-```
-8.x.x-insiders-4.x.x
-```
-
-If the major version increased, it's a good idea to consult the [upgrade
-guide] and go through the steps to ensure your configuration is up to date and
-all necessary changes have been made. If you installed Insiders via `pip`, you
-can upgrade your installation with the following command:
-
-```
-pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
-```
-
-  [upgrade guide]: ../upgrade.md
-
 ## Built-in plugins
 
 When you're using built-in plugins that are solely available via Insiders,

docs/insiders/upgrade.md

@@ -0,0 +1,74 @@
+# How to upgrade
+
+When upgrading Insiders, you should always check the version of Material for
+MkDocs which makes up the first part of the version qualifier, e.g., Insiders
+`4.x.x` is currently based on `9.x.x`:
+
+```
+9.x.x-insiders-4.x.x
+```
+
+If the major version increased, it's a good idea to consult the [upgrade
+guide] and go through the steps to ensure your configuration is up to date and
+all necessary changes have been made. 
+
+  [upgrade guide]: ../upgrade.md
+  [list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags
+
+Depending on how you installed and what you want to upgrade to you
+need to run different commands:
+
+=== "pip upgrade to release"
+
+    If you installed Insiders via `pip` and you want to upgrade to a
+    specific release, pick the tag from the [list of tags] and replace 
+    the tag at the end of the URL of the command given below:
+
+    ```
+    pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
+    ```
+
+=== "pip upgrade to latest development"
+
+    If you installed Insiders via `pip` and want to upgrade to the
+    latest development version, run:
+
+    ```
+    pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+    ```
+
+=== "git upgrade"
+
+    If you installed Insiders via `git`, you will first need to check
+    out the version you want to install into your workspace. After
+    this is done, you can run `pip` to install that version.
+
+    First, make sure that your local clone is up-to-date with the
+    upstream repository by running `git pull`.
+
+    You can look up the tags using `git tag --sort -refname` or you
+    can consult the [list of tags]. Then, checkout the tag you want to
+    use by replacing the one given in the command below (twice)and running 
+    it from your workspace[^detached]:
+      
+      [^detached]:
+        The `--detach` argument serves to tell `git` that you are ok to
+        have your workspace in the [detached head] state, which is
+        perfectly fine to have here.
+        
+      [detached head]: https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit/
+
+    ``` 
+    cd mkdocs-material 
+    git checkout --detach tags/9.4.2-insiders-4.42.0 
+    ```
+
+    Now, change back to the parent directory in which your Git
+    repository lives and run `pip`:
+
+    ```
+    cd .. 
+    pip install -e mkdocs-material
+    ```
+
+

mkdocs.yml

@@ -252,8 +252,9 @@ nav:
     - Tooltips: reference/tooltips.md
   - Insiders:
     - insiders/index.md
-    - Getting started:
-      - Installation: insiders/getting-started.md
-      - Changelog: insiders/changelog.md
+    - Getting started: insiders/getting-started.md
+    - Changelog: 
+      - insiders/changelog/index.md
+      - How to upgrade: insiders/upgrade.md
   - Blog:
     - blog/index.md

src/overrides/hooks/shortcodes.py

@@ -145,7 +145,7 @@ def _badge_for_version(text: str, page: Page, files: Files):
 # Create badge for version of Insiders
 def _badge_for_version_insiders(text: str, page: Page, files: Files):
     spec = text.replace("insiders-", "")
-    path = f"insiders/changelog.md#{spec}"
+    path = f"insiders/changelog/index.md#{spec}"
 
     # Return badge
     icon = "material-tag-heart-outline"