1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00

Updated Insiders guide

This commit is contained in:
squidfunk 2021-11-07 18:59:18 +01:00
parent 9e247dc130
commit 4e31677974
2 changed files with 49 additions and 23 deletions

View File

@ -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

View File

@ -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