@@ -5,30 +5,40 @@ title: Switching to Insiders
55
66# Switching to Insiders
77
8- Material for MkDocs Insiders is a fully compatible drop-in replacement for
9- Material for MkDocs, and can be installed similar to the public version using
10- [ ` pip ` ] [ pip ] , [ ` docker ` ] [ docker ] or [ ` git ` ] [ git ] . When you sponsor @squidfunk ,
11- your account is added to the list of collaborators of the private Insiders
12- repository.
8+ Material for MkDocs Insiders is a fully compatible drop-in replacement[ ^ 1 ] for
9+ Material for MkDocs, and can be installed similarily using [ ` pip ` ] [ pip ] ,
10+ [ ` docker ` ] [ docker ] or [ ` git ` ] [ git ] . Note that in order to get access to the
11+ Insiders repository, you need to [ become an eligible sponsor] of @squidfunk .
12+
13+ [ ^ 1 ] :
14+ While Insiders always strives for full downward compatibility with Material
15+ for MkDocs, there are some cases which slightly deviate from the non-Insiders,
16+
17+ because
18+ configuration can't be shared due to limitations of MkDocs. This is
19+ particularly true for the ` plugins ` configuration, as Insiders provides
20+ several built-in plugins.
1321
1422 [ pip ] : #with-pip
1523 [ docker ] : #with-docker
1624 [ git ] : #with-git
25+ [ become an eligible sponsor ] : index.md#how-to-become-a-sponsor
1726
1827## Requirements
1928
20- In order to access the Insiders repository programmatically (from the command
29+ After you've been added to the list of collaborators and accepted the
30+ invitation, the Insiders repository programmatically (from the command
2131line or GitHub Actions workflows), you need to create a [ personal access
22- token] [ 4 ] :
32+ token] :
2333
24341 . Go to https://github.com/settings/tokens
25- 2 . Click on [ Generate a new token] [ 5 ]
26- 3 . Enter a name and select the [ ` repo ` ] [ 6 ] scope
35+ 2 . Click on [ Generate a new token]
36+ 3 . Enter a name and select the [ ` repo ` ] [ scopes ] scope
27374 . Generate the token and store it in a safe place
2838
29- [ 4 ] : https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
30- [ 5 ] : https://github.com/settings/tokens/new
31- [ 6 ] : https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
39+ [ personal access token ] : https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
40+ [ Generate a new token ] : https://github.com/settings/tokens/new
41+ [ scopes ] : https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
3242
3343## Installation
3444
@@ -49,27 +59,28 @@ private repositories.
4959
5060In case you want to use Material for MkDocs Insiders from within Docker, some
5161additional steps are necessary. While we cannot provide a hosted Docker image
52- for Insiders[ ^ 1 ] , [ GitHub Container Registry] [ 7 ] allows for simple and
62+ for Insiders[ ^ 2 ] , [ GitHub Container Registry] allows for simple and
5363comfortable self-hosting:
5464
55- 1 . [ Fork the Insiders repository] [ 8 ]
56- 2 . Enable [ GitHub Actions] [ 9 ] on your fork[ ^ 2 ]
57- 3 . Create a new personal access token[ ^ 3 ]
65+ 1 . [ Fork the Insiders repository]
66+ 2 . Enable [ GitHub Actions] on your fork[ ^ 3 ]
67+ 3 . Create a new personal access token[ ^ 4 ]
5868 1 . Go to https://github.com/settings/tokens
59- 2 . Click on [ Generate a new token] [ 5 ]
60- 3 . Enter a name and select the [ ` write:packages ` ] [ 10 ] scope
69+ 2 . Click on [ Generate a new token]
70+ 3 . Enter a name and select the [ ` write:packages ` ] [ scopes ] scope
6171 4 . Generate the token and store it in a safe place
62- 4 . Add a [ GitHub Actions secret] [ 11 ] on your fork
72+ 4 . Add a [ GitHub Actions secret] on your fork
6373 1 . Set the name to ` GHCR_TOKEN `
6474 2 . Set the value to the personal access token created in the previous step
65- 5 . [ Create a new release] [ 12 ] to build and publish the Docker image
66- 6 . Install [ Pull App] [ 13 ] on your fork to stay in-sync with upstream
75+ 5 . [ Create a new release] to build and publish the Docker image
76+ 6 . Install [ Pull App] on your fork to stay in-sync with upstream
6777
68- The [ ` publish ` ] [ 14 ] workflow[ ^ 4 ] is automatically run when a new tag (release)
69- is created. When a new Insiders version is released on the upstream repository,
70- the [ Pull App] [ 13 ] will create a pull request with the changes and pull in the
71- new tag, which is picked up by the [ ` publish ` ] [ 14 ] workflow that builds and
72- publishes the Docker image automatically to your private registry.
78+ The [ ` publish ` ] [ publish ] workflow[ ^ 5 ] is automatically run when a new tag
79+ (release) is created. When a new Insiders version is released on the upstream
80+ repository, the [ Pull App] will create a pull request with the changes and
81+ pull in the new tag, which is picked up by the [ ` publish ` ] [ publish ] workflow
82+ that builds and publishes the Docker image automatically to your private
83+ registry.
7384
7485Now, you should be able to pull the Docker image from your private registry:
7586
@@ -78,23 +89,23 @@ docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
7889docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
7990```
8091
81- [ ^ 1 ] :
92+ [ ^ 2 ] :
8293 Earlier, Insiders provided a dedicated Docker image which was available to
8394 all sponsors. On March 21, 2021, the image was deprecated for the reasons
8495 outlined and discussed in #2442 . It was removed on June 1, 2021.
8596
86- [ ^ 2 ] :
97+ [ ^ 3 ] :
8798 When forking a repository, GitHub will disables all workflows. While this
8899 is a reasonable default setting, you need to enable GitHub Actions to be
89100 able to automatically build and publish a Docker image on
90- [ GitHub Container Registry] [ 7 ] .
101+ [ GitHub Container Registry] .
91102
92- [ ^ 3 ] :
103+ [ ^ 4 ] :
93104 While you could just add the ` write:packages ` scope to the personal access
94105 token created to access the Insiders repository, it's safer to create a
95106 dedicated token which you'll only use for publishing the Docker image.
96107
97- [ ^ 4 ] :
108+ [ ^ 5 ] :
98109 The Insiders repository contains three GitHub Actions workflows:
99110
100111 - ` build.yml ` – Build and lint the project (disabled on forks)
@@ -117,11 +128,13 @@ plugins:
117128pip install -e mkdocs-material
118129```
119130
120- [ 7 ] : https://docs.github.com/en/packages/guides/about-github-container-registry
121- [ 8 ] : https://github.com/squidfunk/mkdocs-material-insiders/fork
122- [ 9 ] : https://docs.github.com/en/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository
123- [ 10 ] : https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
124- [ 11 ] : https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
125- [ 12 ] : https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
126- [ 13 ] : https://github.com/apps/pull
127- [ 14 ] : https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml
131+ [ GitHub Container Registry ] : https://docs.github.com/en/packages/guides/about-github-container-registry
132+ [ Fork the Insiders repository ] : https://github.com/squidfunk/mkdocs-material-insiders/fork
133+ [ GitHub Actions ] : https://docs.github.com/en/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository
134+ [ packages scope ] : https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
135+ [ GitHub Actions secret ] : https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
136+ [ Create a new release ] : https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
137+ [ Pull App ] : https://github.com/apps/pull
138+ [ publish ] : https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml
139+
140+ ## Caveats
0 commit comments