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:
parent
9e247dc130
commit
4e31677974
@ -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
|
||||
|
@ -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
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user