OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated Insiders documentation

Browse Source
This commit is contained in:
squidfunk 2021-03-21 17:14:32 +01:00
parent 185f037fbc
commit 076946713c
18 changed files with 136 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
docs/insiders/getting-started.md
View File

@ -1,156 +1,112 @@
---
template: overrides/main.html
title: Getting started
title: Switching to Insiders
---
# Getting started
# Switching to Insiders
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
towards (technical) project documentation. If you're familiar with Python, you
can install Material for MkDocs with [`pip`][2], the Python package manager.
If not, we recommended using [`docker`][3].
Material for MkDocs Insiders is a fully compatible drop-in replacement for
Material for MkDocs, and can be installed similar to the public version using
[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
account is added to the list of collaborators of the private Insiders
repository.
In case you're running into problems, consult the [troubleshooting][4] section.
[1]: #with-pip
[2]: #with-docker
[3]: #with-git
[1]: https://www.mkdocs.org
[2]: #with-pip
[3]: #with-docker
[4]: ../troubleshooting.md
## Requirements
In order to access the Insiders repository programmatically (from the command
line or GitHub Actions workflows), you need to create a [personal access
token][4]:
1. Go to https://github.com/settings/tokens
2. Click on [Generate a new token][5]
3. Enter a name and select the [`repo`][6] scope
4. Generate the token and store it in a safe place
[4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[5]: https://github.com/settings/tokens/new
[6]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
## Installation
### with pip
Material for MkDocs can be installed with `pip`:
Material for MkDocs Insiders can be installed with `pip`:
=== "Material for MkDocs"
``` sh
pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
```
```
pip install mkdocs-material
```
=== "Insiders"
``` sh
pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
```
This will automatically install compatible versions of all dependencies:
[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][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 [Insiders][8], you'll need to [become a
sponsor][9], create a personal access token[^1], and set the_ `GH_TOKEN`
_environment variable to the token's value._
[^1]:
In order to use `pip` to install from the private repository over HTTPS, the
[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].
[5]: https://python-markdown.github.io/
[6]: https://pygments.org/
[7]: https://facelessuser.github.io/pymdown-extensions/
[8]: index.md
[9]: index.md#how-to-become-a-sponsor
The `GH_TOKEN` environment variable must be set to the value of the personal
access token you generated in the previous step. Note that the personal access
token must be kept secret at all times, as it allows the owner to access your
private repositories.
### with docker
- Fork the Insiders repository to your private or organization account
- https://github.com/squidfunk/mkdocs-material-insiders/fork
- Got to Actions, and enable them
- https://github.com/stylezenbot/mkdocs-material-insiders/actions
- There are three actions (two of which can be deleted, but are no-op in forks)
- Build: the action will not be run on forks
- Documentaiton: build Insiders documentation
- publish: publish, when a new tag is pushed... (!)
- Create a token with the write_packages scope
- Set GHCR_TOKEN as a secret in settings
-
In case you want to use Material for MkDocs Insiders from within Docker, some additional steps are necessary. While we cannot provide a hosted Docker image
for Insiders[^1], [GitHub Container Registry][7] allows for simple and
comfortable self-hosting:
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:
1. [Fork the Insiders repository][8]
2. Enable [GitHub Actions][9] on your fork[^2]
3. Create a new personal access token[^3]
1. Go to https://github.com/settings/tokens
2. Click on [Generate a new token][5]
3. Enter a name and select the [`write:packages`][10] scope
4. Generate the token and store it in a safe place
4. Add a [GitHub Actions secret][11] on your fork
1. Set the name to `GHCR_TOKEN`
2. Set the value to the personal access token created in the previous step
5. [Create a new release][12] to build and publish the Docker image
6. Install [Pull App][13] on your fork to stay in-sync with upstream
=== "Material for MkDocs"
The [`publish`][14] workflow[^4] is automatically run when a new tag (release)
is created. When a new Insiders version is released on the upstream repository,
the [Pull App][13] will create a pull request with the changes and pull in the
new tag, which is picked up by the [`publish`][14] workflow that builds and
publishes the Docker image automatically to your private registry.
```
docker pull squidfunk/mkdocs-material
```
Now, you should be able to pull the Docker image from your private registry:
=== "Insiders"
```
docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
docker pull ghcr.io/${GH_USERNAME}/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
covered in the following sections.
The following plugins are bundled with the Docker image:
- [mkdocs-minify-plugin][11]
- [mkdocs-redirects][12]
_Note that in order to install [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._
[^1]:
Earlier, Insiders provided a dedicated Docker image which was available to
all sponsors. On March 21, 2021, the image was deprecated for the reasons
outlined and discussed in #2442. It will be removed on June 1, 2021.
[^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. You'll also need to enable "[Improved Container Support][20]"
on your account.
When forking a repository, GitHub will disables all workflows. While this
is a reasonable default setting, you need to enable GitHub Actions to be
able to automatically build and publish a Docker image on
[GitHub Container Registry][7].
[10]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[11]: https://github.com/byrnereese/mkdocs-minify-plugin
[12]: https://github.com/datarobot/mkdocs-redirects
[^3]:
While you could just add the `write:packages` scope to the personal access
token created to access the Insiders repository, it's safer to create a
dedicated token which you'll only use for publishing the Docker image.
??? question "How to add plugins to the Docker image?"
[^4]:
The Insiders repository contains three GitHub Actions workflows:
Material for MkDocs bundles useful and common plugins while trying not to
blow up the size of the official image. If the plugin you want to use is
not included, create a new `Dockerfile` and extend the official Docker image
with your custom installation routine:
``` Dockerfile
FROM squidfunk/mkdocs-material
RUN pip install ...
```
Next, you can build the image with the following command:
```
docker build -t squidfunk/mkdocs-material .
```
The new image can be used exactly like the official image.
- `build.yml` – Build and lint the project (disabled on forks)
- `documentation.yml` – Build and deploy the documentation (disabled on forks)
- `publish.yml` – Build and publish the Docker image
### with git
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:
Of course, you can use Material for MkDocs Insiders directly from `git`:
=== "Material for MkDocs"
```
git clone https://github.com/squidfunk/mkdocs-material.git
```
=== "Insiders"
```
git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
```
```
git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
```
The theme will reside in the folder `mkdocs-material/material`. When cloning
from `git`, you must install all required dependencies yourself:
@ -159,15 +115,11 @@ from `git`, you must install all required dependencies yourself:
pip install -r mkdocs-material/requirements.txt
```
_Note that in order to install [Insiders][8], you'll need to [become a
sponsor][9]._
[13]: https://github.com/squidfunk/mkdocs-material
[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
[20]: https://docs.github.com/en/free-pro-team@latest/packages/guides/enabling-improved-container-support
[7]: https://docs.github.com/en/packages/guides/about-github-container-registry
[8]: https://github.com/squidfunk/mkdocs-material-insiders/fork
[9]: https://docs.github.com/en/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository
[10]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
[11]: https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
[12]: https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
[13]: https://github.com/apps/pull
[14]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/publish.yml

5
docs/insiders/index.md
View File

@ -1,10 +1,11 @@
---
template: overrides/main.html
title: Insiders
---
# Material for MkDocs Insiders
# Insiders
Material for MkDocs uses the _sponsorware_ release strategy, which means
Material for MkDocs follows the _sponsorware_ release strategy, which means
that _new features are first exclusively released to sponsors_ as part of
__Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
to [get access to Insiders][2].

2
docs/publishing-your-site.md
View File

@ -56,7 +56,7 @@ contents:
jobs:
deploy:
runs-on: ubuntu-latest
if: github.event.pull_request.head.repo.fork == false
if: github.event.repository.fork == false
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2

1
docs/reference/admonitions.md
View File

@ -386,6 +386,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
### Changing the icons
[:octicons-file-code-24: Source][13] ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][13]{ .mdx-insiders }
Each of the supported admonition types has a distinct icon, which can be changed

4
docs/reference/code-blocks.md
View File

@ -103,8 +103,8 @@ configuring syntax highlighting of code blocks:
`pymdownx.inline` is recommended.
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but can also yield weird results. Use
them at your own risk._
this extension, so they may be supported but might yield unexpected results.
Use them at your own risk._
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/

8
docs/setup/adding-a-git-repository.md
View File

@ -159,8 +159,8 @@ The following options are supported:
```
_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._
this plugin, so they may be supported but might yield unexpected results.
Use them at your own risk._
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html
[14]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
@ -212,7 +212,7 @@ The following options are supported:
```
_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._
this plugin, so they may be supported but might yield unexpected results.
Use them at your own risk._
[15]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin

11
docs/setup/changing-the-fonts.md
View File

@ -88,21 +88,22 @@ corresponding `@font-face` definition:
```
The font can then be applied to specific elements, e.g. only headlines, or
globally to be used as the site-wide regular or monospaced font:
globally to be used as the site-wide regular or monospaced font (with fallback
fonts being added automatically):
=== "Regular font"
``` css
body, input {
font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
:root {
--md-text-font-family: "<font>";
}
```
=== "Monospaced font"
``` css
pre, code, kbd {
font-family: "<font>", SFMono-Regular, Consolas, Menlo, monospace;
:root {
--md-code-font-family: "<font>";
}
```

4
docs/setup/changing-the-language.md
View File

@ -177,8 +177,8 @@ Click on a tile to change the directionality:
[:octicons-file-code-24: Source][1] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to customize some (or all) of the translations for your language,
you may follow the guide on [theme extension][9] and create a new partial in
If you want to customize some of the translations for your language, just follow
the guide on [theme extension][9] and create a new partial in
`partials/languages`, e.g. `en-custom.html`. Next, look up the translation you
want to change in the [base translation][1] and add it to the partial.

2
docs/setup/changing-the-logo-and-icons.md
View File

@ -100,7 +100,7 @@ If you want to add [additional icons][1], read on.
### Additional icons
[:octicons-file-code-24: Source][4] ·
:octicons-mortar-board-24: Difficulty: _moderate_
:octicons-mortar-board-24: Difficulty: _easy_
In order to add additional icons, [extend the theme][12], and create a folder
named `.icons` in the [`custom_dir`][13] you want to use for overrides. Next,

4
docs/setup/setting-up-navigation.md
View File

@ -339,8 +339,8 @@ customize its appearance:
```
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but can also yield weird results. Use
them at your own risk._
this extension, so they may be supported but might yield unexpected results.
Use them at your own risk._
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[22]: https://python-markdown.github.io/extensions/toc/

4
docs/setup/setting-up-site-search.md
View File

@ -122,8 +122,8 @@ The following options are supported:
deployment is recommended.
_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._
this plugin, so they may be supported but might yield unexpected results.
Use them at your own risk._
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
[3]: https://www.mkdocs.org/user-guide/configuration/#search

2
docs/setup/setting-up-the-footer.md
View File

@ -124,7 +124,7 @@ extra:
### Custom icons
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _moderate_
:octicons-mortar-board-24: Difficulty: _easy_
The social links feature uses the standard [icon integration][5] of Material for
MkDocs. If you want to use custom icons, follow the guide explaining how to

4
material/assets/stylesheets/main.7a40789f.min.css → material/assets/stylesheets/main.49bb2ee9.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.49bb2ee9.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.7a40789f.min.css.map
View File

File diff suppressed because one or more lines are too long

2
material/base.html
View File

@ -39,7 +39,7 @@
{% endif %}
{% endblock %}
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.7a40789f.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.49bb2ee9.min.css' | url }}">
{% if config.theme.palette %}
{% set palette = config.theme.palette %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.7fa14f5b.min.css' | url }}">

4
mkdocs.yml
View File

@ -155,7 +155,7 @@ nav:
- License: license.md
- Releases:
- Changelog: changelog.md
- How to upgrade: upgrading.md
- Upgrade guide: upgrading.md
- Deprecations: deprecations.md
- Setup:
- Changing the colors: setup/changing-the-colors.md
@ -187,7 +187,7 @@ nav:
- Meta tags: reference/meta-tags.md
- Variables: reference/variables.md
- Insiders:
- Sponsorware: insiders/index.md
- Sponsorship: insiders/index.md
- Getting started:
- Installation: insiders/getting-started.md
- Changelog: insiders/changelog.md

9
src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
View File

@ -54,12 +54,12 @@
font-size: px2rem(12.8px);
// Footnote list - omit left indentation
ol {
> ol {
margin-left: 0;
}
// Footnote list item
li {
// Footnote item - footnote items can contain lists, so we need to scope
// the spacing adjustments to the top-level footnote item.
> li {
transition: color 125ms;
// Darken color on target
@ -80,6 +80,7 @@
}
}
}
}
// Footnote backreference
.footnote-backref {