Merge branch 'docs/restructure-insiders'

docs/getting-started.md

@@ -23,59 +23,28 @@ In case you're running into problems, consult the [troubleshooting][4] section.
 
 Material for MkDocs can be installed with `pip`:
 
-=== "Material for MkDocs"
+```
-
+pip install mkdocs-material
-    ```
+```
-    pip install mkdocs-material
-    ```
-
-=== "Insiders"
-
-    ``` sh
-    pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
-    ```
 
 This will automatically install compatible versions of all dependencies:
 [MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
 Material for MkDocs always strives to support the latest versions, so there's
 no need to install those packages separately.
 
-_Note that in order to install [Insiders][8], you'll need to [become a
-sponsor][9], create a personal access token[^1], and set the_ `GH_TOKEN`
-_environment variable to the token's value._
-
-  [^1]:
-    In order to use `pip` to install from the private repository over HTTPS, the
-    [personal access token][14] requires the [`repo`][15] scope. The creation
-    and usage of an access token is only necessary when installing Insiders
-    over HTTPS, which is the recommended way when building from within a CI/CD
-    workflow, e.g. using [GitHub Pages][16] or [GitLab Pages][17].
-    
-
   [5]: https://python-markdown.github.io/
   [6]: https://pygments.org/
   [7]: https://facelessuser.github.io/pymdown-extensions/
-  [8]: insiders.md
-  [9]: insiders.md#how-to-become-a-sponsor
 
 ### with docker
 
-The official [Docker image][10] is a great way to get up and running in a few
+The official [Docker image][8] is a great way to get up and running in a few
 minutes, as it comes with all dependencies pre-installed. Pull the image for the 
 `latest` version with:
 
-=== "Material for MkDocs"
+```
-
+docker pull squidfunk/mkdocs-material
-    ```
+```
-    docker pull squidfunk/mkdocs-material
-    ```
-
-=== "Insiders"
-
-    ```
-    docker login -u ${GH_USERNAME} -p ${GH_TOKEN} ghcr.io
-    docker pull ghcr.io/squidfunk/mkdocs-material-insiders
-    ```
 
 The `mkdocs` executable is provided as an entry point and `serve` is the 
 default command. If you're not familiar with Docker don't worry, we have you
@@ -83,24 +52,12 @@ covered in the following sections.
 
 The following plugins are bundled with the Docker image:
 
-- [mkdocs-minify-plugin][11]
+- [mkdocs-minify-plugin][9]
-- [mkdocs-redirects][12]
+- [mkdocs-redirects][10]
 
-_Note that in order to install [Insiders][8], you'll need to [become a
+  [8]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-sponsor][9], create a personal access token[^2], and set the_ `GH_TOKEN` 
+  [9]: https://github.com/byrnereese/mkdocs-minify-plugin
-_environment variable to the token's value._
+  [10]: https://github.com/datarobot/mkdocs-redirects
-
-  [^2]:
-    If you want to use `docker` to pull the private Docker image from the
-    [GitHub Container Registry][18], the [personal access token][14] requires
-    the [`read:packages`][15] scope. Note that you need to login before pulling
-    the Docker image. As an example, see the [`publish`][19] workflow of the
-    Material for MkDocs repository. You'll also need to enable "[Improved Container Support][20]"
-    on your account.
-
-  [10]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [11]: https://github.com/byrnereese/mkdocs-minify-plugin
-  [12]: https://github.com/datarobot/mkdocs-redirects
 
 ??? question "How to add plugins to the Docker image?"
 
@@ -124,21 +81,13 @@ _environment variable to the token's value._
 
 ### with git
 
-Material for MkDocs can be directly used from [GitHub][13] by cloning the
+Material for MkDocs can be directly used from [GitHub][11] by cloning the
 repository into a subfolder of your project root which might be useful if you
 want to use the very latest version:
 
-=== "Material for MkDocs"
+```
-
+git clone https://github.com/squidfunk/mkdocs-material.git
-    ```
+```
-    git clone https://github.com/squidfunk/mkdocs-material.git
-    ```
-
-=== "Insiders"
-
-    ```
-    git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
-    ```
 
 The theme will reside in the folder `mkdocs-material/material`. When cloning
 from `git`, you must install all required dependencies yourself:
@@ -147,15 +96,4 @@ from `git`, you must install all required dependencies yourself:
 pip install -r mkdocs-material/requirements.txt
 ```
 
-_Note that in order to install [Insiders][8], you'll need to [become a
+  [11]: https://github.com/squidfunk/mkdocs-material
-sponsor][9]._
-
-  [13]: https://github.com/squidfunk/mkdocs-material
-
-  [14]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
-  [15]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
-  [16]: publishing-your-site.md#github-pages
-  [17]: publishing-your-site.md#gitlab-pages
-  [18]: https://docs.github.com/en/free-pro-team@latest/packages/getting-started-with-github-container-registry/about-github-container-registry
-  [19]: https://github.com/squidfunk/mkdocs-material/blob/master/.github/workflows/publish.yml
-  [20]: https://docs.github.com/en/free-pro-team@latest/packages/guides/enabling-improved-container-support

docs/insiders/getting-started.md

@@ -0,0 +1,125 @@
+---
+template: overrides/main.html
+title: Switching to Insiders
+---
+
+# Switching to Insiders
+
+Material for MkDocs Insiders is a fully compatible drop-in replacement for 
+Material for MkDocs, and can be installed similar to the public version using
+[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
+account is added to the list of collaborators of the private Insiders
+repository.
+
+  [1]: #with-pip
+  [2]: #with-docker
+  [3]: #with-git
+
+## Requirements
+
+In order to access the Insiders repository programmatically (from the command
+line or GitHub Actions workflows), you need to create a [personal access 
+token][4]:
+
+1. Go to https://github.com/settings/tokens
+2. Click on [Generate a new token][5]
+3. Enter a name and select the [`repo`][6] scope
+4. Generate the token and store it in a safe place
+
+  [4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+  [5]: https://github.com/settings/tokens/new
+  [6]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+
+## Installation
+
+### with pip
+
+Material for MkDocs Insiders can be installed with `pip`:
+
+``` 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.
+
+### with docker
+
+In case you want to use Material for MkDocs Insiders from within Docker, some additional steps are necessary. While we cannot provide a hosted Docker image
+for Insiders[^1], [GitHub Container Registry][7] allows for simple and
+comfortable self-hosting:
+
+1. [Fork the Insiders repository][8]
+2. Enable [GitHub Actions][9] on your fork[^2]
+3. Create a new personal access token[^3]
+    1. Go to https://github.com/settings/tokens
+    2. Click on [Generate a new token][5]
+    3. Enter a name and select the [`write:packages`][10] scope
+    4. Generate the token and store it in a safe place
+4. Add a [GitHub Actions secret][11] on your fork
+    1. Set the name to `GHCR_TOKEN`
+    2. Set the value to the personal access token created in the previous step
+5. [Create a new release][12] to build and publish the Docker image
+6. Install [Pull App][13] on your fork to stay in-sync with upstream
+
+The [`publish`][14] workflow[^4] is automatically run when a new tag (release)
+is created. When a new Insiders version is released on the upstream repository,
+the [Pull App][13] will create a pull request with the changes and pull in the
+new tag, which is picked up by the [`publish`][14] workflow that builds and
+publishes the Docker image automatically to your private registry.
+
+Now, you should be able to pull the Docker image from your private registry:
+
+```
+docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
+docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
+```
+
+  [^1]:
+    Earlier, Insiders provided a dedicated Docker image which was available to
+    all sponsors. On March 21, 2021, the image was deprecated for the reasons
+    outlined and discussed in #2442. It will be removed on June 1, 2021.
+
+  [^2]:
+    When forking a repository, GitHub will disables all workflows. While this
+    is a reasonable default setting, you need to enable GitHub Actions to be
+    able to automatically build and publish a Docker image on
+    [GitHub Container Registry][7].
+
+  [^3]:
+    While you could just add the `write:packages` scope to the personal access
+    token created to access the Insiders repository, it's safer to create a
+    dedicated token which you'll only use for publishing the Docker image.
+
+  [^4]:
+    The Insiders repository contains three GitHub Actions workflows:
+
+    - `build.yml` – Build and lint the project (disabled on forks)
+    - `documentation.yml` – Build and deploy the documentation (disabled on forks)
+    - `publish.yml` – Build and publish the Docker image
+
+### with git
+
+Of course, you can use Material for MkDocs Insiders directly from `git`:
+
+```
+git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
+```
+
+The theme will reside in the folder `mkdocs-material/material`. When cloning
+from `git`, you must install all required dependencies yourself:
+
+```
+pip install -r mkdocs-material/requirements.txt
+```
+
+  [7]: https://docs.github.com/en/packages/guides/about-github-container-registry
+  [8]: https://github.com/squidfunk/mkdocs-material-insiders/fork
+  [9]: https://docs.github.com/en/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository
+  [10]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+  [11]: https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
+  [12]: https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
+  [13]: https://github.com/apps/pull
+  [14]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml

docs/insiders/index.md

@@ -1,10 +1,11 @@
 ---
 template: overrides/main.html
+title: Insiders
 ---
 
-# <span hidden>Insiders</span> :logo: :material-plus: :octicons-heart-fill-24:{ .mdx-heart }
+# Insiders
 
-Material for MkDocs uses the _sponsorware_ release strategy, which means
+Material for MkDocs follows the _sponsorware_ release strategy, which means
 that _new features are first exclusively released to sponsors_ as part of
 __Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
 to [get access to Insiders][2].
@@ -146,9 +147,9 @@ the public for general availability.
 - [x] [Color palette toggle][16]
 - [x] [Back-to-top button][17]
 
-  [15]: setup/adding-a-git-repository.md#latest-release
+  [15]: ../setup/adding-a-git-repository.md#latest-release
-  [16]: setup/changing-the-colors.md#color-palette-toggle
+  [16]: ../setup/changing-the-colors.md#color-palette-toggle
-  [17]: setup/setting-up-navigation.md#back-to-top-button
+  [17]: ../setup/setting-up-navigation.md#back-to-top-button
 
 #### $ 2,500 – Biquinho Vermelho
 
@@ -156,9 +157,9 @@ the public for general availability.
 - [x] [Search highlighting][19]
 - [x] [Search sharing][20]
 
-  [18]: setup/setting-up-site-search.md#search-suggestions
+  [18]: ../setup/setting-up-site-search.md#search-suggestions
-  [19]: setup/setting-up-site-search.md#search-highlighting
+  [19]: ../setup/setting-up-site-search.md#search-highlighting
-  [20]: setup/setting-up-site-search.md#search-sharing
+  [20]: ../setup/setting-up-site-search.md#search-sharing
 
 #### $ 3,000 – Caribbean Red
 
@@ -166,9 +167,9 @@ the public for general availability.
 - [x] [Section index pages][22]
 - [x] [Remove generator notice][23]
 
-  [21]: setup/setting-up-navigation.md#sticky-navigation-tabs
+  [21]: ../setup/setting-up-navigation.md#sticky-navigation-tabs
-  [22]: setup/setting-up-navigation.md#section-index-pages
+  [22]: ../setup/setting-up-navigation.md#section-index-pages
-  [23]: setup/setting-up-the-footer.md#remove-generator
+  [23]: ../setup/setting-up-the-footer.md#remove-generator
 
 #### $ 4,000 – Ghost Pepper
 
@@ -176,8 +177,8 @@ the public for general availability.
 - [x] [Code block annotations][25]
 - [ ] Non-latest version warning
 
-[24]: setup/setting-up-navigation.md#anchor-tracking
+[24]: ../setup/setting-up-navigation.md#anchor-tracking
-[25]: reference/code-blocks.md#adding-annotations
+[25]: ../reference/code-blocks.md#adding-annotations
 
 #### $ 5,000 – Aji Panca
 
@@ -185,7 +186,7 @@ the public for general availability.
 - [ ] List of last searches
 - [ ] Advanced routing for versioning
 
-  [26]: reference/diagrams.md
+  [26]: ../reference/diagrams.md
 
 #### $ 6,000 – Trinidad Scorpion
 
@@ -205,7 +206,7 @@ the public for general availability.
 - [ ] TBA
 - [ ] TBA
 
-  [27]: reference/admonitions.md#changing-the-icons
+  [27]: ../reference/admonitions.md#changing-the-icons
 
 #### Future
 
@@ -231,11 +232,11 @@ the public for general availability.
 - [x] [Table of contents in navigation][10]
 - [x] [Header hides on scroll][11]
 
-  [7]: setup/setting-up-navigation.md#navigation-sections
+  [7]: ../setup/setting-up-navigation.md#navigation-sections
-  [8]: setup/setting-up-navigation.md#navigation-expansion
+  [8]: ../setup/setting-up-navigation.md#navigation-expansion
-  [9]: setup/setting-up-navigation.md#hide-the-sidebars
+  [9]: ../setup/setting-up-navigation.md#hide-the-sidebars
-  [10]: setup/setting-up-navigation.md#navigation-integration
+  [10]: ../setup/setting-up-navigation.md#navigation-integration
-  [11]: setup/setting-up-the-header.md#automatic-hiding
+  [11]: ../setup/setting-up-the-header.md#automatic-hiding
 
 #### $ 1,500 – Bhut Jolokia
 
@@ -243,9 +244,9 @@ the public for general availability.
 - [x] [Site language selection][13]
 - [x] [Versioning][14]
 
-  [12]: reference/admonitions.md#inline-blocks
+  [12]: ../reference/admonitions.md#inline-blocks
-  [13]: setup/changing-the-language.md#site-language-selector
+  [13]: ../setup/changing-the-language.md#site-language-selector
-  [14]: setup/setting-up-versioning.md#versioning
+  [14]: ../setup/setting-up-versioning.md#versioning
 
 ## Frequently asked questions
 
@@ -262,7 +263,7 @@ it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
 recommended to [install Insiders][29] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [29]: publishing-your-site.md#github-pages
+  [29]: ../publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -284,5 +285,5 @@ guidelines:
   version__ that's available to you __as long as you like__. Just remember that
   [GitHub deletes private forks][31].
 
-  [30]: license.md
+  [30]: ../license.md
   [31]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/publishing-your-site.md

@@ -56,7 +56,7 @@ contents:
     jobs:
       deploy:
         runs-on: ubuntu-latest
-        if: github.event.pull_request.head.repo.fork == false
+        if: github.event.repository.fork == false
         steps:
           - uses: actions/checkout@v2
           - uses: actions/setup-python@v2
@@ -80,7 +80,7 @@ using [secrets][5]._
 
   [2]: https://github.com/features/actions
   [3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
-  [4]: insiders.md
+  [4]: insiders/index.md
   [5]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
 
 ### with MkDocs

docs/reference/admonitions.md

@@ -386,6 +386,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
 
 ### Changing the icons
 
+[:octicons-file-code-24: Source][13] ·
 [:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders }
 
 Each of the supported admonition types has a distinct icon, which can be changed
@@ -445,7 +446,7 @@ a valid icon in `mkdocs.yml`:
 
     [![Admonition with FontAwesome icons][15]][15]
 
-  [13]: ../insiders.md
+  [13]: ../insiders/index.md
   [14]: ../assets/screenshots/admonition-octicons.png
   [15]: ../assets/screenshots/admonition-fontawesome.png
 

docs/reference/code-blocks.md

@@ -103,8 +103,8 @@ configuring syntax highlighting of code blocks:
     `pymdownx.inline` is recommended.
 
 _Material for MkDocs doesn't provide official support for the other options of
-this extension, so they may be supported but can also yield weird results. Use
+this extension, so they may be supported but might yield unexpected results.
-them at your own risk._
+Use them at your own risk._
 
   [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
   [3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
@@ -261,7 +261,7 @@ _Annotations require syntax highlighting with [Pygments][24] – they're current
 not compatible with other JavaScript-based syntax highlighters. Support may be
 added later on._
 
-  [18]: ../insiders.md
+  [18]: ../insiders/index.md
   [19]: ../assets/screenshots/annotations.png
   [20]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/#adding-annotations
 

docs/reference/diagrams.md

@@ -57,7 +57,7 @@ ensures interoperability with all Material for MkDocs features._
     in conjunction with the [mkdocs-minify-plugin][9] and doesn't adapt to
     dark mode.
 
-  [2]: ../insiders.md
+  [2]: ../insiders/index.md
   [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
   [4]: https://facelessuser.github.io/pymdown-extensions/
   [5]: #usage

docs/setup/adding-a-git-repository.md

@@ -93,7 +93,7 @@ A demo is worth a thousand words — check it out at
   </figcaption>
 </figure>
 
-  [5]: ../insiders.md
+  [5]: ../insiders/index.md
   [6]: ../assets/screenshots/repository.png
   [7]: https://squidfunk.github.io/mkdocs-material-insiders/setup/adding-a-git-repository/
 
@@ -159,8 +159,8 @@ The following options are supported:
     ```
 
 _Material for MkDocs doesn't provide official support for the other options of
-this plugin, so they may be supported but can also yield weird results. Use
+this plugin, so they may be supported but might yield unexpected results.
-them at your own risk._
+Use them at your own risk._
 
   [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html
   [14]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
@@ -212,7 +212,7 @@ The following options are supported:
     ```
 
 _Material for MkDocs doesn't provide official support for the other options of
-this plugin, so they may be supported but can also yield weird results. Use
+this plugin, so they may be supported but might yield unexpected results.
-them at your own risk._
+Use them at your own risk._
 
   [15]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin

docs/setup/changing-the-colors.md

@@ -258,7 +258,7 @@ color palettes:
     This field is used as the toggle's `title` attribute and should be set to a
     discernable name to improve accessibility.
 
-  [6]: ../insiders.md
+  [6]: ../insiders/index.md
   [7]: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors
   [8]: #color-scheme
   [9]: #primary-color

docs/setup/changing-the-fonts.md

@@ -88,21 +88,22 @@ corresponding `@font-face` definition:
 ```
 
 The font can then be applied to specific elements, e.g. only headlines, or 
-globally to be used as the site-wide regular or monospaced font:
+globally to be used as the site-wide regular or monospaced font (with fallback
+fonts being added automatically):
 
 === "Regular font"
 
     ``` css
-    body, input {
+    :root {
-      font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
+      --md-text-font-family: "<font>";
     }
     ```
 
 === "Monospaced font"
 
     ``` css
-    pre, code, kbd {
+    :root {
-      font-family: "<font>", SFMono-Regular, Consolas, Menlo, monospace;
+      --md-code-font-family: "<font>";
     }
     ```
 

docs/setup/changing-the-language.md

@@ -177,8 +177,8 @@ Click on a tile to change the directionality:
 [:octicons-file-code-24: Source][1] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
-If you want to customize some (or all) of the translations for your language,
+If you want to customize some of the translations for your language, just follow
-you may follow the guide on [theme extension][9] and create a new partial in
+the guide on [theme extension][9] and create a new partial in
 `partials/languages`, e.g. `en-custom.html`. Next, look up the translation you
 want to change in the [base translation][1] and add it to the partial.
 

docs/setup/changing-the-logo-and-icons.md

@@ -100,7 +100,7 @@ If you want to add [additional icons][1], read on.
 ### Additional icons
 
 [:octicons-file-code-24: Source][4] · 
-:octicons-mortar-board-24: Difficulty: _moderate_
+:octicons-mortar-board-24: Difficulty: _easy_
 
 In order to add additional icons, [extend the theme][12], and create a folder
 named `.icons` in the [`custom_dir`][13] you want to use for overrides. Next,

docs/setup/setting-up-navigation.md

@@ -118,7 +118,7 @@ theme:
 
     [![Without sticky tabs][11]][11]
 
-  [9]: ../insiders.md
+  [9]: ../insiders/index.md
   [10]: ../assets/screenshots/navigation-tabs-sticky.png
   [11]: ../assets/screenshots/navigation-tabs-collapsed.png
 
@@ -339,8 +339,8 @@ customize its appearance:
         ```
 
 _Material for MkDocs doesn't provide official support for the other options of
-this extension, so they may be supported but can also yield weird results. Use
+this extension, so they may be supported but might yield unexpected results.
-them at your own risk._
+Use them at your own risk._
 
   [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
   [22]: https://python-markdown.github.io/extensions/toc/

docs/setup/setting-up-site-search.md

@@ -122,8 +122,8 @@ The following options are supported:
     deployment is recommended.
 
 _Material for MkDocs doesn't provide official support for the other options of
-this plugin, so they may be supported but can also yield weird results. Use
+this plugin, so they may be supported but might yield unexpected results.
-them at your own risk._
+Use them at your own risk._
 
   [2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
   [3]: https://www.mkdocs.org/user-guide/configuration/#search
@@ -165,7 +165,7 @@ A demo is worth a thousand words — check it out at
   </figcaption>
 </figure>
 
-  [8]: ../insiders.md
+  [8]: ../insiders/index.md
   [9]: ../assets/screenshots/search-suggestions.png
   [10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?q=code+high
 

docs/setup/setting-up-the-footer.md

@@ -117,14 +117,14 @@ extra:
   generator: false
 ```
 
-  [4]: ../insiders.md
+  [4]: ../insiders/index.md
 
 ## Customization
 
 ### Custom icons
 
 [:octicons-file-code-24: Source][2] ·
-:octicons-mortar-board-24: Difficulty: _moderate_
+:octicons-mortar-board-24: Difficulty: _easy_
 
 The social links feature uses the standard [icon integration][5] of Material for
 MkDocs. If you want to use custom icons, follow the guide explaining how to

material/base.html

@@ -39,7 +39,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.7a40789f.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.49bb2ee9.min.css' | url }}">
       {% if config.theme.palette %}
         {% set palette = config.theme.palette %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.7fa14f5b.min.css' | url }}">

material/overrides/main.html

@@ -22,7 +22,7 @@
   <meta name="twitter:title" content="{{ title }}">
   <meta name="twitter:description" content="{{ config.site_description }}">
   <meta name="twitter:image" content="{{ image }}">
-  <link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.0220c4ec.min.css' | url }}">
+  <link rel="stylesheet" href="{{ 'overrides/assets/stylesheets/main.a40a2e23.min.css' | url }}">
 {% endblock %}
 {% block announce %}
   <a href="https://twitter.com/squidfunk">
@@ -33,24 +33,6 @@
     <strong>Twitter</strong>
   </a>
 {% endblock %}
-{% block content %}
-  {{ super() }}
-  <footer class="mdx-content__footer md-typeset">
-    <a href="{{ 'insiders/' | url }}" title="Material for MkDocs Insiders">
-      <hr>
-      <span class="twemoji">
-        {% include ".icons/logo.svg" %}
-      </span>
-      <span class="twemoji">
-        {% include ".icons/material/plus.svg" %}
-      </span>
-      <span class="twemoji mdx-heart">
-        {% include ".icons/octicons/heart-fill-24.svg" %}
-      </span>
-      <hr>
-    </a>
-  </footer>
-{% endblock %}
 {% block scripts %}
   {{ super() }}
   <script src="{{ 'overrides/assets/javascripts/bundle.25e8c307.min.js' | url }}"></script>

mkdocs.yml

@@ -82,7 +82,7 @@ plugins:
         releases/5.md: upgrading.md #upgrading-from-3x-to-4x
         releases/changelog.md: changelog.md
         setup/adding-social-links.md: setup/setting-up-the-footer.md
-        sponsorship.md: insiders.md
+        sponsorship.md: insiders/index.md
   - minify:
       minify_html: true
 
@@ -152,8 +152,11 @@ nav:
     - Customization: customization.md
     - Troubleshooting: troubleshooting.md
     - Data privacy: data-privacy.md
-    - Insiders: insiders.md
     - License: license.md
+    - Releases:
+      - Changelog: changelog.md
+      - Upgrade guide: upgrading.md
+      - Deprecations: deprecations.md
   - Setup:
     - Changing the colors: setup/changing-the-colors.md
     - Changing the fonts: setup/changing-the-fonts.md
@@ -183,12 +186,11 @@ nav:
     - MathJax: reference/mathjax.md
     - Meta tags: reference/meta-tags.md
     - Variables: reference/variables.md
-  - Changelog:
+  - Insiders:
-    - Material for MkDocs: changelog.md
+    - Sponsorship: insiders/index.md
-    - Material for MkDocs Insiders: changelog/insiders.md
+    - Getting started:
-    - Guides:
+      - Installation: insiders/getting-started.md
-      - Upgrading: upgrading.md
+      - Changelog: insiders/changelog.md
-      - Deprecations: deprecations.md
 
 # Google Analytics
 google_analytics:

src/assets/stylesheets/main/extensions/markdown/_footnotes.scss

@@ -54,29 +54,30 @@
     font-size: px2rem(12.8px);
 
     // Footnote list - omit left indentation
-    ol {
+    > ol {
       margin-left: 0;
-    }
 
-    // Footnote list item
+      // Footnote item - footnote items can contain lists, so we need to scope
-    li {
+      // the spacing adjustments to the top-level footnote item.
-      transition: color 125ms;
+      > li {
+        transition: color 125ms;
 
-      // Darken color on target
+        // Darken color on target
-      &:target {
+        &:target {
-        color: var(--md-default-fg-color);
+          color: var(--md-default-fg-color);
-      }
+        }
 
-      // Show backreferences on footnote hover
+        // Show backreferences on footnote hover
-      &:hover  .footnote-backref,
+        &:hover  .footnote-backref,
-      &:target .footnote-backref {
+        &:target .footnote-backref {
-        transform: translateX(0);
+          transform: translateX(0);
-        opacity: 1;
+          opacity: 1;
-      }
+        }
 
-      // Adjust spacing on first child
+        // Adjust spacing on first child
-      > :first-child {
+        > :first-child {
-        margin-top: 0;
+          margin-top: 0;
+        }
       }
     }
   }

src/overrides/assets/stylesheets/main.scss

@@ -39,7 +39,6 @@
 @import "main/typeset";
 
 @import "main/layout/announce";
-@import "main/layout/content";
 @import "main/layout/hero";
 @import "main/layout/iconsearch";
 @import "main/layout/sponsorship";

src/overrides/assets/stylesheets/main/layout/_content.scss

@@ -1,56 +0,0 @@
-////
-/// Copyright (c) 2016-2021 Martin Donath <martin.donath@squidfunk.com>
-///
-/// Permission is hereby granted, free of charge, to any person obtaining a
-/// copy of this software and associated documentation files (the "Software"),
-/// to deal in the Software without restriction, including without limitation
-/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
-/// and/or sell copies of the Software, and to permit persons to whom the
-/// Software is furnished to do so, subject to the following conditions:
-///
-/// The above copyright notice and this permission notice shall be included in
-/// all copies or substantial portions of the Software.
-///
-/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
-/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-/// DEALINGS
-////
-
-// ----------------------------------------------------------------------------
-// Rules
-// ----------------------------------------------------------------------------
-
-// Content footer
-.mdx-content__footer {
-  margin-top: px2rem(20px);
-  text-align: center;
-
-  // Link to Insiders
-  a {
-    display: inline-block;
-    color: $clr-pink-500;
-    transition:
-      transform 250ms cubic-bezier(0.1, 0.7, 0.1, 1),
-      color     125ms;
-
-    // Link to Insiders on focus/hover
-    &:focus,
-    &:hover {
-      transform: scale(1.2);
-    }
-  }
-
-  // Horizontal separator
-  hr {
-    display: inline-block;
-    width: px2rem(40px);
-    margin: px2em(16px);
-    vertical-align: middle;
-    background-color: currentColor;
-    border: none;
-  }
-}

src/overrides/main.html

@@ -70,28 +70,6 @@
   </a>
 {% endblock %}
 
-<!-- Content -->
-{% block content %}
-  {{ super() }}
-
-  <!-- Content footer -->
-  <footer class="mdx-content__footer md-typeset">
-    <a href="{{ 'insiders/' | url }}" title="Material for MkDocs Insiders">
-      <hr />
-      <span class="twemoji">
-        {% include ".icons/logo.svg" %}
-      </span>
-      <span class="twemoji">
-        {% include ".icons/material/plus.svg" %}
-      </span>
-      <span class="twemoji mdx-heart">
-        {% include ".icons/octicons/heart-fill-24.svg" %}
-      </span>
-      <hr />
-    </a>
-  </footer>
-{% endblock %}
-
 <!-- Theme-related JavaScript -->
 {% block scripts %}
   {{ super() }}