From 9fbf89b1ff4c3b80a2f4dacb07a57d0c8e6f36ea Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 30 Aug 2020 11:49:05 +0200 Subject: [PATCH] Added documentation for deploying Insiders --- docs/getting-started.md | 25 +++++++++---- docs/publishing-your-site.md | 61 ++++++++++++++++++++++++++++--- docs/setup/changing-the-colors.md | 2 +- 3 files changed, 74 insertions(+), 14 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 991089269..b2ba79215 100644 --- a/docs/getting-started.md +++ b/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 -need to [become a sponsor][9], create a [personal access token][10], and set -the `GH_TOKEN` environment variable to the token's value. +_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 +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 -need to [become a sponsor][9]. +_Note that in order to install [Material for MkDocs Insiders][8], you'll +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 diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md index 87a111a03..777f623c0 100644 --- a/docs/publishing-your-site.md +++ b/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 `.github.io/`. +_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 -done by using the [GitLab CI][4] task runner. At the root of your repository, +If you're hosting your code on GitLab, deploying to [GitLab Pages][6] can be +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 `.gitlab.io/`. - [3]: https://gitlab.com/pages - [4]: https://docs.gitlab.com/ee/ci/ +_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 [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 diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 4f041d3cb..e4bb1b67c 100644 --- a/docs/setup/changing-the-colors.md +++ b/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`: