Added documentation for deploying Insiders

docs/getting-started.md

@@ -29,7 +29,7 @@ Material for MkDocs can be installed with `pip`:
     pip install mkdocs-material
     ```
 
-=== "Material for MkDocs Insiders"
+=== "Insiders"
 
     ``` sh
     pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
@@ -40,9 +40,9 @@ This will automatically install compatible versions of all dependencies:
 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 [__Material for MkDocs Insiders__][8], you'll
+_Note that in order to install [Material for MkDocs Insiders][8], you'll
-need to [become a sponsor][9], create a [personal access token][10], and set
+need to [become a sponsor][9], create a [personal access token][10][^1], and
-the `GH_TOKEN` environment variable to the token's value.
+set the_ `GH_TOKEN` _environment variable to the token's value._
 
   [5]: https://python-markdown.github.io/
   [6]: https://pygments.org/
@@ -90,7 +90,7 @@ want to use the very latest version:
     git clone https://github.com/squidfunk/mkdocs-material.git
     ```
 
-=== "Material for MkDocs Insiders"
+=== "Insiders"
 
     ```
     git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
@@ -103,7 +103,18 @@ cloning from `git`, you must install all required dependencies yourself:
 pip install -r mkdocs-material/requirements.txt
 ```
 
-Note that in order to install [__Material for MkDocs Insiders__][8], you'll
+_Note that in order to install [Material for MkDocs Insiders][8], you'll
-need to [become a sponsor][9].
+need to [become a sponsor][9]._
 
   [16]: https://github.com/squidfunk/mkdocs-material
+
+  [^1]:
+    In order to use `pip` to install from the private repository over HTTPS, the
+    personal access token requires the [`repo`][17] scope. Note that the 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][18] or [GitLab Pages][19].
+
+  [17]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+  [18]: publishing-your-site.md#github-pages
+  [19]: publishing-your-site.md#gitlab-pages

docs/publishing-your-site.md

@@ -23,7 +23,7 @@ documentation. At the root of your repository, create a new GitHub Actions
 workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
 contents:
 
-=== ".github/workflows/ci.yml"
+=== "Material for MkDocs"
 
     ``` yaml
     name: ci
@@ -43,13 +43,42 @@ contents:
           - run: mkdocs gh-deploy --force
     ```
 
+=== "Insiders"
+
+    ``` yaml
+    name: ci
+    on:
+      push:
+        branches:
+          - master
+    jobs:
+      deploy:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v2
+          - uses: actions/setup-python@v2
+            with:
+              python-version: 3.x
+          - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+          - run: mkdocs gh-deploy --force
+    env:
+      GH_TOKEN: ${{ secrets.GH_TOKEN }}
+    ```
+
 Now, when a new commit is pushed to `master`, the static site is automatically
 built and deployed. Commit and push the file to your repository to see 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 using [Material for MkDocs Insiders][4], which
+can be done 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
+  [5]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
 
 ### with MkDocs
 
@@ -62,12 +91,12 @@ mkdocs gh-deploy --force
 
 ## GitLab Pages
 
-If you're hosting your code on GitLab, deploying to [GitLab Pages][3] can be
+If you're hosting your code on GitLab, deploying to [GitLab Pages][6] can be
-done by using the [GitLab CI][4] task runner. At the root of your repository,
+done by using the [GitLab CI][7] task runner. At the root of your repository,
 create a task definition named `.gitlab-ci.yml` and copy and paste the
 following contents:
 
-=== ".gitlab-ci.yml"
+=== "Material for MkDocs"
 
     ``` yaml
     image: python:latest
@@ -83,12 +112,32 @@ following contents:
           - public
     ```
 
+=== "Insiders"
+
+    ``` yaml
+    image: python:latest
+    deploy:
+      stage: deploy
+      only:
+        - master
+      script:
+        - pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+        - mkdocs build --site-dir public
+      artifacts:
+        paths:
+          - public
+    ```
+
 Now, when a new commit is pushed to `master`, the static site is automatically
 built and deployed. Commit and push the file to your repository to see the
 workflow in action.
 
 Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.
 
-  [3]: https://gitlab.com/pages
+_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
-  [4]: https://docs.gitlab.com/ee/ci/
+[personal access token][3] when using [Material for MkDocs Insiders][4], which
+can be done using [masked custom variables][8]._
 
+  [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

docs/setup/changing-the-colors.md

@@ -190,7 +190,7 @@ color:
   :octicons-beaker-24: Experimental ·
   [:octicons-heart-fill-24:{: .tx-heart } Insiders only][6]{: .tx-insiders }
 
-[__Material for MkDocs Insiders__][6] makes it possible to define multiple color
+[Material for MkDocs Insiders][6] makes it possible to define multiple color
 palettes, including a [scheme][7], [primary][8] and [accent][9] color each, and
 let the user choose. Define them via `mkdocs.yml`: