From 80eca3507743e4c7d615957f96b30ff00a3f70e5 Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Thu, 17 Jun 2021 08:51:16 +0200
Subject: [PATCH] Added more code block annotations

---
 docs/publishing-your-site.md        | 48 +++++++++++++++++++----------
 docs/setup/setting-up-versioning.md | 10 ++++--
 2 files changed, 40 insertions(+), 18 deletions(-)

diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md
index de8e7b050..aa054ce36 100644
--- a/docs/publishing-your-site.md
+++ b/docs/publishing-your-site.md
@@ -25,11 +25,11 @@ contents:
 
 === "Material for MkDocs"
 
-    ``` yaml
-    name: ci
+    ``` { .yaml .annotate }
+    name: ci # (1)
     on:
       push:
-        branches:
+        branches: # (2)
           - master
           - main
     jobs:
@@ -40,10 +40,25 @@ contents:
           - uses: actions/setup-python@v2
             with:
               python-version: 3.x
-          - run: pip install mkdocs-material
+          - run: pip install mkdocs-material # (3)
           - run: mkdocs gh-deploy --force
     ```
 
+    1. You can change the name to your liking.
+
+    2. At some point, GitHub renamed `master` to `main`. If your default branch
+       is named `master`, you can safely remove `main`, vice versa.
+
+    3. This is the place to install further [MkDocs plugins][3] or Markdown
+       extensions with `pip` to be used during the build:
+
+        ``` sh
+        pip install \
+          mkdocs-material \
+          mkdocs-awesome-pages-plugin \
+          ...
+        ```
+
 === "Insiders"
 
     ``` yaml
@@ -75,13 +90,14 @@ the workflow in action.
 Your documentation should shortly appear at `<username>.github.io/<repository>`.
 
 _Remember to set the_ `GH_TOKEN` _environment variable to the value of your
-[personal access token][3] when deploying [Insiders][4], which can be done
-using [secrets][5]._
+[personal access token][4] when deploying [Insiders][5], which can be done
+using [secrets][6]._
 
   [2]: https://github.com/features/actions
-  [3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
-  [4]: insiders/index.md
-  [5]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
+  [3]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+  [4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+  [5]: insiders/index.md
+  [6]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
 
 ### with MkDocs
 
@@ -94,8 +110,8 @@ mkdocs gh-deploy --force
 
 ## GitLab Pages
 
-If you're hosting your code on GitLab, deploying to [GitLab Pages][6] can be
-done by using the [GitLab CI][7] task runner. At the root of your repository,
+If you're hosting your code on GitLab, deploying to [GitLab Pages][7] can be
+done by using the [GitLab CI][8] task runner. At the root of your repository,
 create a task definition named `.gitlab-ci.yml` and copy and paste the
 following contents:
 
@@ -138,9 +154,9 @@ workflow in action.
 Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.
 
 _Remember to set the_ `GH_TOKEN` _environment variable to the value of your
-[personal access token][3] when deploying [Insiders][4], which can be done
-using [masked custom variables][8]._
+[personal access token][4] when deploying [Insiders][5], which can be done
+using [masked custom variables][9]._
 
-  [6]: https://gitlab.com/pages
-  [7]: https://docs.gitlab.com/ee/ci/
-  [8]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
+  [7]: https://gitlab.com/pages
+  [8]: https://docs.gitlab.com/ee/ci/
+  [9]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md
index 2feaa0597..404881960 100644
--- a/docs/setup/setting-up-versioning.md
+++ b/docs/setup/setting-up-versioning.md
@@ -75,15 +75,21 @@ If you're using versioning, you might want to display a warning when the user
 visits any other version than the latest version. Using [theme extension][8],
 you can [define the `outdated` block][9]:
 
-``` html
+``` { .html .annotate }
 {% block outdated %}
   You're not viewing the latest version.
-  <a href="{{ '../' ~ base_url }}">
+  <a href="{{ '../' ~ base_url }}"> <!-- (1) -->
     <strong>Click here to go to latest.</strong>
   </a>
 {% endblock %}
 ```
 
+1. Given this value for the `href` attribute, the link will always redirect to 
+   the root of your site, which will then redirect to the latest version. This
+   ensures that older versions of your site do not depend on a specific alias,
+   e.g. `latest`, to allow for changing the alias later on without breaking
+   earlier versions.
+
 This will render a version warning above the header:
 
 [![Version warning][10]][10]