diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md index 71c98d3cd..502df4fa7 100644 --- a/docs/insiders/getting-started.md +++ b/docs/insiders/getting-started.md @@ -1,23 +1,14 @@ --- template: overrides/main.html -title: Switching to Insiders +title: Getting started with Insiders --- -# Switching to Insiders +# Getting started with Insiders -Material for MkDocs Insiders is a fully compatible drop-in replacement[^1] for -Material for MkDocs, and can be installed similarily using [`pip`][pip], -[`docker`][docker] or [`git`][git]. Note that in order to get access to the -Insiders repository, you need to [become an eligible sponsor] of @squidfunk. - - [^1]: - While Insiders always strives for full downward compatibility with Material - for MkDocs, there are some cases which slightly deviate from the non-Insiders, - - because - configuration can't be shared due to limitations of MkDocs. This is - particularly true for the `plugins` configuration, as Insiders provides - several built-in plugins. +Material for MkDocs Insiders is a compatible drop-in replacement for Material +for MkDocs, and can be installed similarily using [`pip`][pip], +[`docker`][docker] or [`git`][git]. Note that in order to access the Insiders +repository, you need to [become an eligible sponsor] of @squidfunk on GitHub. [pip]: #with-pip [docker]: #with-docker @@ -27,9 +18,9 @@ Insiders repository, you need to [become an eligible sponsor] of @squidfunk. ## Requirements After you've been added to the list of collaborators and accepted the -invitation, the Insiders repository programmatically (from the command -line or GitHub Actions workflows), you need to create a [personal access -token]: +repository invitation, the next step is to create a [personal access token] for +your GitHub account in order to access the Insiders repository programmatically +(from the command line or GitHub Actions workflows): 1. Go to https://github.com/settings/tokens 2. Click on [Generate a new token] @@ -138,3 +129,39 @@ pip install -e mkdocs-material [publish]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml ## Caveats + +This sections describes some aspects to consider when using Insiders together +with Material for MkDocs to ensure that users without access to Insiders can +still build your documentation. + +### Built-in plugins + +When using built-in plugins that are solely available via Insiders, it might be +necessary to split the `mkdocs.yml` configuration into a base configuration, and +one with plugin overrides. Note that this is a limitation of MkDocs, which can +be mitigated by using [configuration inheritance]: + +=== ":octicons-file-code-16: mkdocs.insiders.yml" + + ``` yaml + INHERIT: mkdocs.yml + plugins: + - search + - social + - tags + ``` + +=== ":octicons-file-code-16: mkdocs.yml" + + ``` yaml + # Configuration with everything except Insiders plugins + ``` + +Now, when you're in an environment with access to Insiders (e.g. in your CI +pipeline), you can build your documentation project with the following lines: + +``` +mkdocs build --config-file mkdocs.insiders.yml +``` + + [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance diff --git a/docs/insiders/index.md b/docs/insiders/index.md index b7c6ac284..5c5a2276b 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -65,10 +65,9 @@ features, bug fixing, stability improvement, issue triage and general support. The biggest bottleneck in Open Source is time.[^3] [^3]: - Making - an Open Source project sustainable is exceptionally hard: maintainers burn - out, projects are abandoned. That's not great and very unpredictable. The - sponsorware model ensures that if you decide to use Material for MkDocs, + Making an Open Source project sustainable is exceptionally hard: maintainers + burn out, projects are abandoned. That's not great and very unpredictable. + The sponsorware model ensures that if you decide to use Material for MkDocs, you can be sure that bugs are fixed quickly and new features are added regularly. @@ -340,7 +339,7 @@ be mitigated by using [configuration inheritance]. See the [getting started guide] for more information. [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance - [getting started guide]: getting-started.md + [getting started guide]: getting-started.md#caveats ### Payment