From e0401cb9fa29c50acb30fa497f93c505f3eb3fbd Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 22 Nov 2020 14:52:08 +0100 Subject: [PATCH] Added documentation for pulling the Insiders Docker image --- docs/getting-started.md | 54 +++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 2b4a566c6..dfa0a2eae 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -41,7 +41,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 [Material for MkDocs Insiders][8], you'll -need to [become a sponsor][9], create a [personal access token][10][^1], and +need to [become a sponsor][9], create a personal access token[^1], and set the_ `GH_TOKEN` _environment variable to the token's value._ [5]: https://python-markdown.github.io/ @@ -49,17 +49,25 @@ set the_ `GH_TOKEN` _environment variable to the token's value._ [7]: https://facelessuser.github.io/pymdown-extensions/ [8]: insiders.md [9]: insiders.md#how-to-become-a-sponsor - [10]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token ### with docker -The official [Docker image][11] is a great way to get up and running in a few +The official [Docker image][10] 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: -``` -docker pull squidfunk/mkdocs-material -``` +=== "Material for MkDocs" + + ``` + 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 @@ -67,12 +75,16 @@ covered in the following sections. The following plugins are bundled with the Docker image: -- [mkdocs-minify-plugin][12] -- [mkdocs-redirects][13] +- [mkdocs-minify-plugin][11] +- [mkdocs-redirects][12] - [11]: https://hub.docker.com/r/squidfunk/mkdocs-material/ - [12]: https://github.com/byrnereese/mkdocs-minify-plugin - [13]: https://github.com/datarobot/mkdocs-redirects +_Note that in order to install [Material for MkDocs 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._ + + [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 can I add plugins to the Docker image?" @@ -96,7 +108,7 @@ The following plugins are bundled with the Docker image: ### with git -Material for MkDocs can be directly used from [GitHub][14] by cloning the +Material for MkDocs can be directly used from [GitHub][13] by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version: @@ -122,15 +134,25 @@ pip install -r mkdocs-material/requirements.txt _Note that in order to install [Material for MkDocs Insiders][8], you'll need to [become a sponsor][9]._ - [14]: https://github.com/squidfunk/mkdocs-material + [13]: 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`][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 + [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]. + [^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. + + [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#L72-L77