Updated Insiders documentation

docs/insiders/getting-started.md

@@ -1,152 +1,108 @@
 ---
 template: overrides/main.html
-title: Getting started
+title: Switching to Insiders
 ---
 
-# Getting started
+# Switching to Insiders
 
-Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
+Material for MkDocs Insiders is a fully compatible drop-in replacement for 
-towards (technical) project documentation. If you're familiar with Python, you
+Material for MkDocs, and can be installed similar to the public version using
-can install Material for MkDocs with [`pip`][2], the Python package manager.
+[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
-If not, we recommended using [`docker`][3].
+account is added to the list of collaborators of the private Insiders
+repository.
 
-In case you're running into problems, consult the [troubleshooting][4] section.
+  [1]: #with-pip
+  [2]: #with-docker
+  [3]: #with-git
 
-  [1]: https://www.mkdocs.org
+## Requirements
-  [2]: #with-pip
+
-  [3]: #with-docker
+In order to access the Insiders repository programmatically (from the command
-  [4]: ../troubleshooting.md
+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 can be installed with `pip`:
+Material for MkDocs Insiders can be installed with `pip`:
-
-=== "Material for MkDocs"
-
-    ```
-    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:
+The `GH_TOKEN` environment variable must be set to the value of the personal
-[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
+access token you generated in the previous step. Note that the personal access
-Material for MkDocs always strives to support the latest versions, so there's
+token must be kept secret at all times, as it allows the owner to access your
-no need to install those packages separately.
+private repositories.
-
-_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]: index.md
-  [9]: index.md#how-to-become-a-sponsor
 
 ### with docker
 
-- Fork the Insiders repository to your private or organization account
+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
-  - https://github.com/squidfunk/mkdocs-material-insiders/fork
+for Insiders[^1], [GitHub Container Registry][7] allows for simple and
-- Got to Actions, and enable them
+comfortable self-hosting:
-  - https://github.com/stylezenbot/mkdocs-material-insiders/actions
-  - There are three actions (two of which can be deleted, but are no-op in forks)
-    - Build: the action will not be run on forks
-    - Documentaiton: build Insiders documentation
-    - publish: publish, when a new tag is pushed... (!)
-- Create a token with the write_packages scope
-- Set GHCR_TOKEN as a secret in settings
-  - 
 
-The official [Docker image][10] is a great way to get up and running in a few
+1. [Fork the Insiders repository][8]
-minutes, as it comes with all dependencies pre-installed. Pull the image for the 
+2. Enable [GitHub Actions][9] on your fork[^2]
-`latest` version with:
+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
 
-=== "Material for MkDocs"
+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 pull squidfunk/mkdocs-material
+docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
+docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
 ```
 
-=== "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
-    docker login -u ${GH_USERNAME} -p ${GH_TOKEN} ghcr.io
+    outlined and discussed in #2442. It will be removed on June 1, 2021.
-    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
-covered in the following sections.
-
-The following plugins are bundled with the Docker image:
-
-- [mkdocs-minify-plugin][11]
-- [mkdocs-redirects][12]
-
-_Note that in order to install [Insiders][8], you'll need to [become a
-sponsor][9], create a personal access token[^2], and set the_ `GH_TOKEN` 
-_environment variable to the token's value._
 
   [^2]:
-    If you want to use `docker` to pull the private Docker image from the
+    When forking a repository, GitHub will disables all workflows. While this
-    [GitHub Container Registry][18], the [personal access token][14] requires
+    is a reasonable default setting, you need to enable GitHub Actions to be
-    the [`read:packages`][15] scope. Note that you need to login before pulling
+    able to automatically build and publish a Docker image on
-    the Docker image. As an example, see the [`publish`][19] workflow of the
+    [GitHub Container Registry][7].
-    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/
+  [^3]:
-  [11]: https://github.com/byrnereese/mkdocs-minify-plugin
+    While you could just add the `write:packages` scope to the personal access
-  [12]: https://github.com/datarobot/mkdocs-redirects
+    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.
 
-??? question "How to add plugins to the Docker image?"
+  [^4]:
+    The Insiders repository contains three GitHub Actions workflows:
 
-    Material for MkDocs bundles useful and common plugins while trying not to
+    - `build.yml` – Build and lint the project (disabled on forks)
-    blow up the size of the official image. If the plugin you want to use is
+    - `documentation.yml` – Build and deploy the documentation (disabled on forks)
-    not included, create a new `Dockerfile` and extend the official Docker image
+    - `publish.yml` – Build and publish the Docker image
-    with your custom installation routine:
-
-    ``` Dockerfile
-    FROM squidfunk/mkdocs-material
-    RUN pip install ...
-    ```
-
-    Next, you can build the image with the following command:
-
-    ```
-    docker build -t squidfunk/mkdocs-material .
-    ```
-
-    The new image can be used exactly like the official image.
 
 ### with git
 
-Material for MkDocs can be directly used from [GitHub][13] by cloning the
+Of course, you can use Material for MkDocs Insiders directly from `git`:
-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
-    ```
-
-=== "Insiders"
 
 ```
 git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
@@ -159,15 +115,11 @@ 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
+  [7]: https://docs.github.com/en/packages/guides/about-github-container-registry
-sponsor][9]._
+  [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
-  [13]: https://github.com/squidfunk/mkdocs-material
+  [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
-  [14]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+  [12]: https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
-  [15]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+  [13]: https://github.com/apps/pull
-  [16]: ../publishing-your-site.md#github-pages
+  [14]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml
-  [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/index.md

@@ -1,10 +1,11 @@
 ---
 template: overrides/main.html
+title: Insiders
 ---
 
-# Material for MkDocs Insiders
+# 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].

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

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

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/

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

@@ -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-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

@@ -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

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

@@ -124,7 +124,7 @@ extra:
 ### 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 }}">

mkdocs.yml

@@ -155,7 +155,7 @@ nav:
     - License: license.md
     - Releases:
       - Changelog: changelog.md
-      - How to upgrade: upgrading.md
+      - Upgrade guide: upgrading.md
       - Deprecations: deprecations.md
   - Setup:
     - Changing the colors: setup/changing-the-colors.md
@@ -187,7 +187,7 @@ nav:
     - Meta tags: reference/meta-tags.md
     - Variables: reference/variables.md
   - Insiders:
-    - Sponsorware: insiders/index.md
+    - Sponsorship: insiders/index.md
     - Getting started:
       - Installation: insiders/getting-started.md
       - Changelog: insiders/changelog.md

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

@@ -54,12 +54,12 @@
     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.
+      > li {
         transition: color 125ms;
 
         // Darken color on target
@@ -80,6 +80,7 @@
         }
       }
     }
+  }
 
   // Footnote backreference
   .footnote-backref {