Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00
Code Issues Releases Wiki Activity

Merge branch 'master' into feature/add-codeberg-pages-guide-link

Browse Source
This commit is contained in:
Andre601 2024-01-22 00:50:42 +01:00
commit 5954ecd2fd
No known key found for this signature in database
GPG Key ID: 90E82BD59347A86C
2972 changed files with 11800 additions and 9666 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.dockerignore
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
.editorconfig
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
.eslintignore
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
.github/FUNDING.yml vendored
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

BIN
.github/assets/sponsors/sponsor-datadog.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

BIN
.github/assets/sponsors/sponsor-manticore-games.png vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 11 KiB

BIN
.github/assets/sponsors/sponsor-spotware.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.3 KiB

BIN
.github/assets/sponsors/sponsor-trendpop.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

2
.github/dependabot.yml vendored
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

4
.github/workflows/build.yml vendored
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -98,7 +98,7 @@ jobs:
uses: actions/checkout@v4
- name: Set up Python runtime
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: ${{ env.PYTHON_VERSION }}
cache: pip

8
.github/workflows/documentation.yml vendored
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -49,7 +49,7 @@ jobs:
src/templates/partials/languages
- name: Set up Python runtime
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: ${{ env.PYTHON_VERSION }}
cache: pip
@ -104,12 +104,12 @@ jobs:
done
- name: Upload to GitHub Pages
uses: actions/upload-pages-artifact@v2
uses: actions/upload-pages-artifact@v3
with:
path: site
- name: Deploy to GitHub Pages
uses: actions/deploy-pages@v2
uses: actions/deploy-pages@v4
- name: Save build cache
uses: actions/cache/save@v3

2
.gitignore vendored
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
.stylelintignore
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

155
CHANGELOG
View File

@ -1,3 +1,156 @@
mkdocs-material-9.5.4+insiders-4.50.0 (2024-01-19)
* Added configurable logging capabilities to privacy plugin
mkdocs-material-9.5.4 (2024-01-15)
* Fixed #6645: Local storage with invalid value can break site
* Fixed #6635: Tags icons before default ignored if default is set
mkdocs-material-9.5.3+insiders-4.49.2 (2024-01-09)
* Fixed missing attribute lists extension for tags plugin
* Fixed #6627: New tags plugin crashes on Python 3.8
mkdocs-material-9.5.3+insiders-4.49.1 (2024-01-07)
* Improved interop of new tags plugin with other plugins
* Fixed #6594: Tags plugin doesn't work with mkdocs-macros plugin
* Fixed #6569: Social plugin crashes if in different file system location
mkdocs-material-9.5.3+insiders-4.49.0 (2023-12-29)
* Added support for exporting tags and mappings
* Added support for disabling tags and/or listings or both
* Fixed tag links from pages to listings on homepage
mkdocs-material-9.5.3+insiders-4.48.0 (2023-12-23)
* Rewrite of tags plugin, now much more powerful
* Added support for nested tags (tag hierarchies, e.g. foo/bar)
* Added support for shadow tags (by list, prefix or suffix)
* Added support for custom tag layouts and templates
* Added support for hiding tags in table of contents
* Added support for configurable inline tag listings
* Added support for automatically linking to closest tag listing
* Added support for scoped listings (limit to subsection of site)
* Added support for multiple instances of tags plugin
* Added support for changing front matter property and template variable
* Added support for tag slugification format strings
* Fixed #6510: Projects plugin out of memory on Linux (4.47.1 regression)
* Fixed projects plugin not notifying plugins about serve mode
* Fixed projects plugin skipping projects on prefix match
* Deprecated tags_file and tags_extra_files settings
* Modernized tags plugin code base
mkdocs-material-9.5.3 (2023-12-23)
* Limited version range of MkDocs to < 1.6
* Updated Macedonian translations
* Fixed #6520: Group plugin crashes when using mike
* Fixed #6494: Hide author's email address if disabled in git-authors plugin
mkdocs-material-9.5.2+insiders-4.47.1 (2023-12-11)
* Improved editing experience for projects plugin
* Improved resilience of optimize and social plugin
* Fixed race condition when writing manifest in optimize and social plugin
* Fixed #6475: Logo not taking precedence over icon in social card
* Fixed #6399: Projects plugin doesn't pick up added/removed projects
* Fixed #6306: Projects plugin cache not correctly updated
mkdocs-material-9.5.2 (2023-12-11)
* Fixed types for slugify settings in blog plugin config
* Fixed #6469: Horizontal scrollbars on MathJax containers
mkdocs-material-9.5.1+insiders-4.47.0 (2023-12-08)
* Added support for staying on page when switching languages
* Added configurable logging capabilities to projects plugin
* Removed temporary warning on blog plugin authors file format change
* Fixed projects plugin logging messages twice on Linux systems
* Fixed projects plugin trying to hoist theme assets of divergent themes
* Fixed compatibility of optimize plugin and projects plugin
* Fixed compatibility of social plugin and projects plugin
* Fixed #6448: Code line selection broken for code blocks with custom ids
* Fixed #6437: Projects plugin crashing for certain site URL configurations
* Fixed #6414: Projects plugin doesn't prefix messages coming from projects
mkdocs-material-9.5.1 (2023-12-08)
* Updated Greek translations
* Fixed #6464: Privacy plugin cannot be enabled
* Fixed #6461: Sorting blog posts ignores time component in date
mkdocs-material-9.5.0 (2023-12-07)
Merged Insiders features of 'Goat's Horn' funding goal
* Added privacy plugin: automatic downloading of external assets
* Added support for card grids and grid layouts
* Added support for improved tooltips
* Added support for content tabs anchor links (deep linking)
* Added support for automatic dark/light mode
* Added support for document contributors
mkdocs-material-9.4.14+insiders-4.46.0 (2023-11-26)
* Added support for author profiles in blog plugin
* Fixed custom index pages yielding two navigation items (4.45.0 regression)
mkdocs-material-9.4.14 (2023-11-26)
* Added support for linking authors in blog posts
mkdocs-material-9.4.13 (2023-11-26)
* Fixed #6365: Blog plugin pagination links to previous pages broken
* Fixed #5758: Updated Mermaid.js to version 10.6.1 (latest)
mkdocs-material-9.4.12+insiders-4.45.0 (2023-11-24)
* Added support for sorting blog categories by post count or custom function
* Improved tags plugin to generate Unicode-aware slugs by default
* Fixed non-deterministic order of multiple authors in blog plugin
mkdocs-material-9.4.12 (2023-11-24)
* Improved blog plugin to generate Unicode-aware slugs by default
* Fixed non-deterministic order of categories in blog plugin
mkdocs-material-9.4.11+insiders-4.44.0 (2023-11-23)
* Added pagination settings for archive pages in blog plugin
* Added pagination settings for category pages in blog plugin
mkdocs-material-9.4.11 (2023-11-23)
* Fixed #6364: Search plugin crashing when enabling theme while serving
* Fixed blog plugin crashing when disabling pagination
mkdocs-material-9.4.10+insiders-4.43.1 (2023-11-19)
* Added third-party theme support in projects plugin, improving editing
* Fixed #6360: Projects plugin crashes when theme is not Material for MkDocs
* Fixed #6306: Projects plugin not reloading nested project configuration
mkdocs-material-9.4.10 (2023-11-19)
* Fixed #6356: Version selector can't be disabled via mike's configuration
* Fixed #6281: Navigation not rendering due to Safari bug (9.4.2 regression)
* Fixed #6261: Navigation expansion animates on first load (9.4.2 regression)
mkdocs-material-9.4.9 (2023-11-17)
* Fixed #6344: Long entries cutoff in table of contents
* Fixed #6336: Custom template for glob archive not working with pagination
* Fixed #6328: Blog plugin crashes for locales with dashes, e.g. pt-BR
* Fixed #6327: Copy-to-clipboard button doesn't trim trailing line feed
* Fixed #6302: Version strings not matched when using mike, only aliases
* Fixed instant navigation progress indicator for gzipped content in Chrome
* Fixed rendering bug on details marker rotation in Firefox
mkdocs-material-9.4.8+insiders-4.43.0 (2023-11-05)
* Added support for GitLab committers (document contributors)
@ -2420,7 +2573,7 @@ mkdocs-material-4.0.0 (2019-02-13)
mkdocs-material-3.3.0 (2019-01-29)
* Moved Google Analytics integration into `head` using Google Tag Manager
* Moved Google Analytics integration into head using Google Tag Manager
* Fixed #972: Unicode slugifier breaks table of contents blur on scroll
* Fixed #974: Additional links in table of contents break blur on scroll

12
Dockerfile
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -83,11 +83,11 @@ RUN \
find ${PACKAGES} \
-type f \
-path "*/__pycache__/*" \
-exec rm -f {} \;
# Trust directory, required for git >= 2.35.2
RUN git config --global --add safe.directory /docs &&\
git config --global --add safe.directory /site
-exec rm -f {} \; \
&& \
git config --system --add safe.directory /docs \
&& \
git config --system --add safe.directory /site
# Set working directory
WORKDIR /docs

2
LICENSE
View File

@ -1,4 +1,4 @@
Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to

18
README.md
View File

@ -28,6 +28,10 @@
src="https://img.shields.io/docker/pulls/squidfunk/mkdocs-material"
alt="Docker Pulls"
/></a>
<a href="https://github.com/sponsors/squidfunk"><img
src="https://img.shields.io/github/sponsors/squidfunk"
alt="Sponsors"
/></a>
</p>
<p align="center">
@ -58,6 +62,9 @@
<a href="https://fastapi.tiangolo.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-fastapi.png" height="120"
/></a>
<a href="https://www.trendpop.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-trendpop.png" height="120"
/></a>
</p>
<p>&nbsp;</p>
<p align="center"><strong>Bronze sponsors</strong></p>
@ -71,15 +78,9 @@
<a href="https://kx.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kx.png" height="58"
/></a>
<a href="https://www.manticoregames.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-manticore-games.png" height="58"
/></a>
<a href="https://orion-docs.prefect.io/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-prefect.png" height="58"
/></a>
<a href="https://datadoghq.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-datadog.png" height="58"
/></a>
<a href="https://www.zenoss.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-zenoss.png" height="58"
/></a>
@ -164,6 +165,9 @@
<a href="https://3dr.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-3dr.png" height="58"
/></a>
<a href="https://spotware.com/" target=_blank><img
src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-spotware.png" height="58"
/></a>
</p>
<p>&nbsp;</p>
@ -284,7 +288,7 @@ For detailed installation instructions, configuration options, and a demo, visit
**MIT License**
Copyright (c) 2016-2023 Martin Donath
Copyright (c) 2016-2024 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to

2
docs/blog/.authors.yml
View File

@ -3,7 +3,9 @@ authors:
name: Martin Donath
description: Creator
avatar: https://avatars.githubusercontent.com/u/932156
url: https://github.com/squidfunk
alexvoss:
name: Alex Voss
description: Community support
avatar: https://avatars.githubusercontent.com/u/4134224
url: https://github.com/alexvoss

37
docs/blog/posts/adding-a-badge-to-your-project.md Normal file
View File

@ -0,0 +1,37 @@
---
title: Adding a badge to your project
date: 2023-11-30
authors: [squidfunk]
slug: adding-a-badge-to-your-project
description: >
Share the love – you can now add a badge to your README, showing that your
project is built with Material for MkDocs
categories:
- General
---
# Adding a :simple-materialformkdocs: badge to your project
__You enjoy working with Material for MkDocs? Share the love! You can now add
a badge to your project's README, showing that your project is built with
Material for MkDocs.__
Material for MkDocs' logo was just added to [Simple Icons], which is used by
[Shields.io] to include logos in badges. We generated a badge for you, which
you can add to your project's README:
[![Material for MkDocs][badge]](#usage)
<!-- more -->
## Usage
Just copy the following snippet and paste it into your project's `README.md`:
``` markdown
[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
```
[Simple Icons]: https://simpleicons.org/
[Shields.io]: https://shields.io/
[badge]: https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white

69
docs/changelog/index.md
View File

@ -2,6 +2,75 @@
## Material for MkDocs
### 9.5.4 <small>January 15, 2024</small> { id="9.5.4" }
- Fixed #6645: Local storage with invalid value can break site
- Fixed #6635: Tags icons before default ignored if default is set
### 9.5.3 <small>December 23, 2023</small> { id="9.5.3" }
- Limited version range of MkDocs to < 1.6
- Updated Macedonian translations
- Fixed #6520: Group plugin crashes when using mike
- Fixed #6494: Hide author's email address if disabled in git-authors plugin
### 9.5.2 <small>December 11, 2023</small> { id="9.5.2" }
- Fixed types for `slugify` settings in blog plugin config
- Fixed #6469: Horizontal scrollbars on MathJax containers
### 9.5.1 <small>December 8, 2023</small> { id="9.5.1" }
- Updated Greek translations
- Fixed #6464: Privacy plugin cannot be enabled
- Fixed #6461: Sorting blog posts ignores time component in date
### 9.5.0 <small>December 7, 2023</small> { id="9.5.0" }
Merged Insiders features of 'Goat's Horn' funding goal
- Added privacy plugin: automatic downloading of external assets
- Added support for card grids and grid layouts
- Added support for improved tooltips
- Added support for content tabs anchor links (deep linking)
- Added support for automatic dark/light mode
- Added support for document contributors
### 9.4.14 <small>November 26, 2023</small> { id="9.4.14" }
- Added support for linking authors in blog posts
### 9.4.13 <small>November 26, 2023</small> { id="9.4.13" }
- Fixed #6365: Blog plugin pagination links to previous pages broken
- Fixed #5758: Updated Mermaid.js to version 10.6.1 (latest)
### 9.4.12 <small>November 24, 2023</small> { id="9.4.12" }
- Improved blog plugin to generate Unicode-aware slugs by default
- Fixed non-deterministic order of categories in blog plugin
### 9.4.11 <small>November 23, 2023</small> { id="9.4.11" }
- Fixed #6364: Search plugin crashing when enabling theme while serving
- Fixed blog plugin crashing when disabling pagination
### 9.4.10 <small>November 19, 2023</small> { id="9.4.10" }
- Fixed #6356: Version selector can't be disabled via mike's configuration
- Fixed #6281: Navigation not rendering due to Safari bug (9.4.2 regression)
- Fixed #6261: Navigation expansion animates on first load (9.4.2 regression)
### 9.4.9 <small>November 17, 2023</small> { id="9.4.9" }
- Fixed #6344: Long entries cutoff in table of contents
- Fixed #6336: Custom template for glob archive not working with pagination
- Fixed #6328: Blog plugin crashes for locales with dashes, e.g. `pt-BR`
- Fixed #6327: Copy-to-clipboard button doesn't trim trailing line feed
- Fixed #6302: Version strings not matched when using mike, only aliases
- Fixed instant navigation progress indicator for gzipped content in Chrome
- Fixed rendering bug on details marker rotation in Firefox
### 9.4.8 <small>November 5, 2023</small> { id="9.4.8" }
- Fixed invalid local address replacement when using instant loading

419
docs/contributing/making-a-pull-request.md Normal file
View File

@ -0,0 +1,419 @@
# Pull Requests
You can contribute to Material for MkDocs by making a [pull request] that
will be reviewed by maintainers and integrated into the main repository when
the changes made are approved. You can contribute bug fixes, changes to the
documentation, or new functionality you have developed.
[pull request]: https://docs.github.com/en/pull-requests
!!! note "Considering a pull request"
Before deciding to spend effort on making changes and creating a pull
request, please discuss what you intend to do. If you are responding to
what you think might be a bug, please issue a [bug report] first. If you
indend to work on documentation, create a [documentation issue]. If you
want to work on a new feature, please create a [change request].
Keep in mind the guidance given and let people advise you. It might be that
there are easier solutions to the problem you perceive and want to address.
It might be that what you want to achieve can already be done by
configuration or [customization].
[bug report]: reporting-a-bug.md
[documentation issue]: reporting-a-docs-issue.md
[change request]: requesting-a-change.md
[customization]: ../customization.md
## Learning about pull requests
Pull requests are a concept layered on top of Git by services that provide Git
hosting. Before you consider making a pull request, you should familiarize
yourself with the documentation on GitHub, the service we are using. The
following articles are of particular importance:
1. [Forking a repository]
2. [Creating a pull request from a fork]
3. [Creating a pull request]
Note that they provide tailored documentation for different operating systems
and different ways of interacting with GitHub. We do our best in the
documentation here to describe the process as it applies to Material for MkDocs
but cannot cover all possible combinations of tools and ways of doing things.
It is also important that you understand the concept of a pull-request in
general before continuing.
[Forking a repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
[Creating a pull request from a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork
[Creating a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
## Pull request process
In the following, we describe the general process for making pull requests. The
aim here is to provide the 30k ft overview before describing details later on.
### Preparing changes and draft PR
The diagram below describes what typically happens to repositories in the
process or preparing a pull request. We will be discussing the review-revise
process below. It is important that you understand the overall process first
before you worry about specific commands. This is why we cover this first before
providing instructions below.
``` mermaid
sequenceDiagram
autonumber
participant mkdocs-material
participant PR
participant fork
participant local
mkdocs-material ->> fork: fork on GitHub
fork ->> local: clone to local
local ->> local: branch
loop prepare
loop push
loop edit
local ->> local: commit
end
local ->> fork: push
end
mkdocs-material ->> fork: merge in any changes
fork ->>+ PR: create draft PR
PR ->> PR: review your changes
end
```
1. The first step is that you create a fork of the Material for MkDocs
repository, either [mkdocs-material] or [mkdocs-material-insiders]
(only accessible to sponsors). This provides you with a repository that you
can push changes to. Note that it is not possible to have more than one fork
of a given repository at any point in time. So, the fork you create will be
*the* fork you have.
2. Once it is made, clone it to your local machine so you can start working on
your changes.
3. All contributions should be made through a 'topic branch' with a name that
describes the work being done. This allows you to have more than one piece
of work in progress and, if you are working with the public version, also
shows others clearly that the code contained is work in progress. The topic
branch will be relatively short-lived and will disappear at the end, when
your changes have been incorporated into the codebase.
4. Next comes the iterative process of making edits, committing them to your
clone. Please commit in sensible chunks that constitute a piece of work
instead of committing everything in one go.
Remember that fine-grained, incremental commits are much easier to
review in than large changes all over the place and with many files involved.
Try to keep your changes as small and localized as possible and keep the
reviewer in mind when committing. In particular, make sure to write
meaningful commit messages.
5. Push your work up to your fork regularly.
6. You should also keep an eye on changes in the Material for MkDocs repository
you cloned. This is especially important if you work takes a while. Please
try and merge any concurrent changes into your fork and into your branch
regularly. You *must* do this at least once before creating a pull request,
so make your life easier and do it more often so as to minimize the risk of
conflicting changes.
7. Once you are happy that your changes are in a state that you can describe
them in a *draft* pull request, you should create this. Make sure to
reference any previous discussions or issues that gave rise to your work.
Creating a draft is a good way to get *early* feedback on your work from the
maintainer or others. You can explicitly request reviews at points where you
think this would be important.
8. Review your work as if you were the reviewer and fix any issues with your
work so far. Look critically at the diffs of the files that you have changed.
In particular, pay attention to whether the changes are as small as possible
and whether you have follow the general coding style used in the project.
If you received feedback, iterate over the process so far as necessary.
You should choose a number of projects to test your changes with. You should
definitely make sure that the changes do not break the building of the
documentation for Material for MkDocs, which you can find in the `docs`
folder. You may also want to make sure that relevant examples from the
[examples repository] still build fine.
[mkdocs-material]: https://github.com/squidfunk/mkdocs-material
[mkdocs-material-insiders]: https://github.com/squidfunk/mkdocs-material-insiders/
[examples repository]: https://github.com/mkdocs-material/examples
### Finalizing
Once you are happy with your changes, you can move to the next step, finalizing
your pull request and asking for a more formal and detailed review. The diagram
below shows the process:
``` mermaid
sequenceDiagram
autonumber
participant mkdocs-material
participant PR
participant fork
participant local
activate PR
PR ->> PR : finalize PR
loop review
loop discuss
PR ->> PR: request review
PR ->> PR: discussion
local ->> fork: push futher changes
end
PR ->> mkdocs-material: merge (and squash)
deactivate PR
fork ->> fork: delete branch
mkdocs-material ->> fork: pull
local ->> local: delete branch
fork ->> local: pull
end
```
1. When you are happy that the changes you made amount to a contribution that
the maintainer(s) could integrate into the codebase, finalize the pull
request. This signals to everyone that consider the work 'done' and that it
can be reviewed with a view to accepting and integrating it.
2. Request a review from the maintainer, `@squidfunk`.
3. The maintainer may make comments on your code, which you should discuss with
them. Bear in mind when doing this that the maintainer may have a different
point of view compared to yours. They will often take a more long-term
perspective of maintaining the project in the years to come while you may be
more focused on the specific issue or feature that you worked on. Please keep
the discussion respectful at all times.
It is important to note that not all pull requests get incorporated int the
codebase. The reasons can vary. The work may bring to light other issues that
block integration of the pull request. Sometimes it helps uncover better ways of
doing things or shows that a more general approach is needed. All of this is
fine and helps the project progress, even if specific changes are not,
ultimately, accepted.
4. Make any requested changes by committing them to your local clone and
pushing them up to your fork. This will automatically update the pull request.
It may well take a few iterations to get your contributions to an acceptable
state. You can help the process along by carefully reading comments made and
making changes with care.
5. Once the reviewer is fully satisfied with the changes, they can merge them
into the main branch (or 'master'). In the process, they may 'squash' your
commits together into a smaller number of commits and may edit the messages
that describe them. Congratulations, you have now contributed to this project
and should see the changes in the main branch under your name.
6. You can now delete the fork and your local repository and start afresh again
next time around. Alternatively, you can keep the repository and local clone
around but it is important that you keep them in sync with the upstream
repository for any subsequent work. We recommend that you start by deleting
the branch you used on your fork.
7. To make sure you have the changes you produced, pull them from the main
repository into the main branch of your fork.
8. Similarly, delete the topic branch from your local clone and...
9. pull the changes to its master branch.
## Steps
Now that the overall process is outlined, here are specific instructions and
tips. There are many choices to be made when describing a process for
contributing to a project via a pull request. In the following, we assume that
you are working with the Git command-line tools. For most alternatives (such as
using IDEs or using functionality provided through the GitHub web interface),
the translation from the command-line instructions should be simple enough. We
will add notes only where really necessary to keep the complexity of this to a
reasonable level.
### Forking the repository
To make changes to Material for MkDocs, you would first fork one of its
repositories on GitHub. This is so that you have a repository on GitHub that
you can push changes to (only maintainers and collaborators have write access
to the original repositories).
Fork the [repository for the public version] if you want to make changes to
code that is in the public version or if you want to make changes to the
documentation. It is a good idea to change the name of the repository by
appending `-fork` so that people who come across it know that they have found a
temporary fork rather then the original or a permanent fork of the project.
You may also want to add a description that clarifies what the repository is for.
[repository for the public version]: https://github.com/squidfunk/mkdocs-material
To make changes to functionality available only within the Insiders version,
fork [the Insiders repository]. Note that the fork will be a private repository.
Please respect the [terms of the Insiders program] and the spirit of the
Sponsorware approach used to maintain and develop Material for MkDocs.
[the Insiders repository]: https://github.com/squidfunk/mkdocs-material-insiders/
[terms of the Insiders program]: http://localhost:8000/mkdocs-material/insiders/faq/sponsoring/#licensing
### Setting up a development environment
From this point onwards, please follow the [instructions for setting up the
development environment]. They will take you through the process of setting up
an environment in which you can make changes and review/test them.
[instructions for setting up the development environment]: ../customization.md#environment-setup
### Making changes
When you make changes to the code or the documentation please follow the
established style used in the project. Doing so increases readability and
also helps with making diffs easier to read for those who will review the pull
request. Avoid making any large-scale style changes such as asking your IDE
to re-format all code.
Study the code that you are modifying well to ensure that you fully understand
how it works before you try to change it. This will not only help you solve the
problem you are trying to address but also minimize the risks of creating
unintended side effects.
### Committing to a branch
Development for pull requests is best done in a topic branch separate from the
`master` branch. Create a new local branch with `git switch -c <name>` and
commit your changes to this branch.
When you want to push commits to your fork, you can do so with
`git push -u origin <name>`. The `-u` argument is the short version of
`--set-upstream`, which makes the newly created branch 'track' the branch with
the same `<name>` in your fork. This means that then `pull` and `push` commands
will work against that branch in your fork by default.
### Merging concurrent changes
If the work you do takes some time then the chances increase that changes will
be made to the main repository while you work.It is probably a good idea to set
up the original Material for MkDocs repository as an `upstream` repository for
your local clone.
This is what it might look like:
```bash hl_lines="4"
$ git remote -v
origin git@github.com:<your_username>/mkdocs-material-fork.git (fetch)
origin git@github.com:<your_username>/mkdocs-material-fork.git (push)
$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
$ git remote -v
origin git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
origin git@github.com:alexvoss/mkdocs-material-fork.git (push)
upstream https://github.com/squidfunk/mkdocs-material.git (fetch)
upstream https://github.com/squidfunk/mkdocs-material.git (push)
```
After you have done this, you can pull any concurrent changes from the upstream
repository directly into your clone and do any necessary merges there, then push
them up to your fork. You will need to be explicit about which remote repository
you want to use when you are doing a `pull`:
```bash
# making and committing some local changes
push pull upstream master
```
This fetches changes from the `master` branch into your topic branch and merges
them.
### Testing and reviewing changes
Before you commit any changes, you should make sure that they work as expected
and do not create any unintended side effects. You should test them on at least
these three [smoke tests]:
- The documentation of Material for MkDocs itself. If you set up and run the
development environment as outlined in the [instructions for setting up the
development environment], `mkdocs serve` should be running and continuously
building the documentation. Check that there are no error messages and, ideally,
no (new) warnings.
- Test on a project that represents the problem or a test for a newly developed
feature. You may already have this if you have filed a bug report and created
a [minimal reproduction]. If you are working on a new feature then you may need
to build a project to serve as a test suite. It can double as documentation that
shows how your new feature is meant to work.
- Test with relevant examples from the [Material for MkDocs Examples]
repository. Note that to build all examples in one go you need the projects
plugin from Insiders but you can always build the examples individually
using the public version.
[smoke tests]: https://en.wikipedia.org/wiki/Smoke_testing_(software)
[minimal reproduction]: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/
[Material for MkDocs Examples]: https://github.com/mkdocs-material/examples
- Ideally, also test the examples in the [examples repository]. If you are
working on the Insiders edition of Material for MkDocs, you can simply start a
build at the top level and the [projects plugin] will build all of the examples
for you. If you are on the public version, you will need to build each
sub-project individually. We appreciate that this is a growing collection of
examples and you may want to prioritize those that are most relevant to the
functionality you change.
[examples repository]: https://github.com/mkdocs-material/examples
[projects plugin]: https://squidfunk.github.io/mkdocs-material/plugins/projects/
### Creating the pull request
Initially, create the pull request **as a draft**. You do this [through the
various interfaces that GitHub provides]. Which one you use is entirely up to
you. We do not provide specific instructions for using the interfaces as GitHub
provide all the information that should be necessary.
[through the various interfaces that GitHub provides]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
### Commits, messages, mistakes and 'squash'
### Deleting branches
Once the pull request has been merged into the master branch of the Material
for MkDocs repository, you should remove the branch both from the fork on
GitHub and from the local clone on your computer. This avoids possible
confusion about the state of development.
First, switch back to the `master` branch with `git switch master` and then
delete the branch used for the PR using `git branch -d <name>`.
### Subsequent Pull Requests
It is important that subsequent pull requests are started from an up-to-date
history of the `master` branch. One way to achieve this is to delete the fork
and start with an entirely new one next time round.
If you contribute to Material for MkDocs more often or just happen to be
doing two or more pull requests in succession, you can also just make sure
to sync your fork (using the GitHub UI) and pull from it into your local
repository. So, just delete the topic branch you created (both locally and in
your fork) and pull from the main repository's `master` branch into your
`master` branch before starting work on a new pull request.
## Dos and Don'ts
1. **Don't** just create a pull request with changes that are not explained.
2. **Do** discuss what you intend to do with people in the discussions so that the
rational for any changes is clear before you write or modify code.
3. **Do** link to the discussion or any issues to provide the context for a pull
request.
4. **Do** ask questions if you are uncertain about anything.
5. **Do** ask yourself if what you are doing benefits the wider community and
makes Material for MkDocs a better product.
6. **Do** ask yourself if the cost of making the changes stands in a good
relation to the benefits they will bring. Some otherwise sensible changes can
add complexity for comparatively little gain, might break existing behaviour
or might be brittle when other changes need to be made.
7. **Do** merge in concurrent changes frequently to minimize the chance of
conflicting changes that may be difficult to resolve.

2
docs/conventions.md
View File

@ -33,7 +33,7 @@ explicitly define them. The default value of the property is always included.
#### <!-- md:default computed --> – Default value is computed { #default data-toc-label="is computed" }
Some default values are not set to static values but computed form other values,
Some default values are not set to static values but computed from other values,
like the site language, repository provider, or other settings.
#### <!-- md:default none --> – Default value is empty { #default data-toc-label="is empty" }

3
docs/creating-your-site.md
View File

@ -16,7 +16,7 @@ Alternatively, if you're running Material for MkDocs from within Docker, use:
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
```
=== "Windows"
=== "Windows (cmd)"
```
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
@ -66,6 +66,7 @@ theme:
"yaml.customTags": [ // (1)!
"!ENV scalar",
"!ENV sequence",
"!relative scalar",
"tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"

31
docs/enterprise-support.md
View File

@ -1,5 +1,32 @@
---
template: redirect.html
location: https://calendly.com/squidfunk/enterprise
status: new
---
# Enterprise Feedback
We highly value the insights of our enterprise users, and we're eager to hear
from you. Your feedback is immensely valuable to us. If you're utilizing
Material for MkDocs in an enterprise context and would like to share your
experiences with us, we'd love to connect and discuss:
- What you are building with it
- What aspects you like about it
- What challenges you are facing
- What could be improved
## Let's Connect
To schedule a convenient appointment, please reach out to us via email at
contact@squidfunk.com and provide us with the following details:
- Your company's name
- How you are using Material for MkDocs
- Any specific questions or topics you'd like to address
Once we have this information, we'll promptly get in touch with you to arrange
a 30-minute call. Please note that this call is exclusively intended for
enterprise users and is not meant for technical support. Instead, it's an
opportunity for us to engage in a casual conversation to better understand your
unique needs.
We look forward to our discussion!

84
docs/insiders/changelog/index.md
View File

@ -2,6 +2,90 @@
## Material for MkDocs Insiders
### 4.50.0 <small>January 19, 2024</small> { id="4.50.0" }
- Added configurable logging capabilities to privacy plugin
### 4.49.2 <small>January 9, 2024</small> { id="4.49.2" }
- Fixed missing attribute lists extension for tags plugin
- Fixed #6627: New tags plugin crashes on Python 3.8
### 4.49.1 <small>January 7, 2024</small> { id="4.49.1" }
- Improved interop of new tags plugin with other plugins
- Fixed #6594: Tags plugin doesn't work with mkdocs-macros plugin
- Fixed #6569: Social plugin crashes if in different file system location
### 4.49.0 <small>December 29, 2023</small> { id="4.49.0" }
- Added support for exporting tags and mappings
- Added support for disabling tags and/or listings or both
- Fixed tag links from pages to listings on homepage
### 4.48.0 <small>December 23, 2023</small> { id="4.48.0" }
- Rewrite of tags plugin, now much more powerful
- Added support for nested tags (tag hierarchies, e.g. foo/bar)
- Added support for shadow tags (by list, prefix or suffix)
- Added support for custom tag layouts and templates
- Added support for hiding tags in table of contents
- Added support for configurable inline tag listings
- Added support for automatically linking to closest tag listing
- Added support for scoped listings (limit to subsection of site)
- Added support for multiple instances of tags plugin
- Added support for changing front matter property and template variable
- Added support for tag slugification format strings
- Fixed #6510: Projects plugin out of memory on Linux (4.47.1 regression)
- Fixed projects plugin not notifying plugins about serve mode
- Fixed projects plugin skipping projects on prefix match
- Deprecated tags_file and tags_extra_files settings
- Modernized tags plugin code base
### 4.47.1 <small>December 11, 2023</small> { id="4.47.1" }
- Improved editing experience for projects plugin
- Improved resilience of optimize and social plugin
- Fixed race condition when writing manifest in optimize and social plugin
- Fixed #6475: Logo not taking precedence over icon in social card
- Fixed #6399: Projects plugin doesn't pick up added/removed projects
- Fixed #6306: Projects plugin cache not correctly updated
### 4.47.0 <small>December 8, 2023</small> { id="4.47.0" }
- Added support for staying on page when switching languages
- Added configurable logging capabilities to projects plugin
- Removed temporary warning on blog plugin authors file format change
- Fixed projects plugin logging messages twice on Linux systems
- Fixed projects plugin trying to hoist theme assets of divergent themes
- Fixed compatibility of optimize plugin and projects plugin
- Fixed compatibility of social plugin and projects plugin
- Fixed #6448: Code line selection broken for code blocks with custom ids
- Fixed #6437: Projects plugin crashing for certain site URL configurations
- Fixed #6414: Projects plugin doesn't prefix messages coming from projects
### 4.46.0 <small>November 26, 2023</small> { id="4.46.0" }
- Added support for author profiles in blog plugin
- Fixed custom index pages yielding two navigation items (4.45.0 regression)
### 4.45.0 <small>November 24, 2023</small> { id="4.45.0" }
- Added support for sorting blog categories by post count or custom function
- Improved tags plugin to generate Unicode-aware slugs by default
- Fixed non-deterministic order of multiple authors in blog plugin
### 4.44.0 <small>November 23, 2023</small> { id="4.44.0" }
- Added pagination settings for archive pages in blog plugin
- Added pagination settings for category pages in blog plugin
### 4.43.1 <small>November 19, 2023</small> { id="4.43.1" }
- Added third-party theme support in projects plugin, improving editing
- Fixed #6360: Projects plugin crashes when theme is not Material for MkDocs
- Fixed #6306: Projects plugin not reloading nested project configuration
### 4.43.0 <small>November 5, 2023</small> { id="4.43.0" }
- Added support for GitLab committers (document contributors)

148
docs/insiders/community-experts-program/index.md Normal file
View File

@ -0,0 +1,148 @@
---
title: Community Experts Program
status: new
---
# Calling for Community Experts
Interested in joining the Material for MkDocs team as a Community Expert?
We're on the lookout for individuals who are passionate about supporting our
awesome community. In return for your valuable contributions, time, and
insights, __you'll gain free access to the Insiders edition__.
## Why we need you
As our project and community continue to grow, so do the questions and needs of
our users on our discussion board. Our discussion board is a vital part of our
project, serving as a hub for our community to connect and a valuable knowledge
base to complement our documentation.
We're eager to keeping it well-maintained, organized, easy to search and address
all queries which is why we need extra hands to keep up with the demand.
That's why we're bulding a team of Community Experts!
## Your role
As a Community Expert, your role primarily involves active participation on
our [discussion board], where we'd expect you to be:
- Answering discussions to help users with their questions
- Providing guidance regarding implementations
- Sharing insights into customizations and workarounds
- Optimizing searchability by adjusting discussion titles with relevant keywords
## Your benefits
Here is a list of the benefits we offer to our Community Experts:
- __Free access to Material for MkDocs Insiders__ – Exclusive Access to all of
our Material for MkDocs Insiders features for _non-commercial use_.[^1]
- __Close communication with the team__ – Stay connected with us through various
channels, including calls and internal project management tools.
- __GitHub profile boost__ – Enhance your GitHub profile's visibility and
credibility as your activity increases, earning you valuable badges that can
enhance your credibility.
[^1]:
Access to Insiders is granted to your primary account, i.e., the account
with which you're contributing to the project. It cannot be transferred to
another account. Additionally, it cannot be used for commercial purposes.
## Your knowledge & skills
To be a successful Community Expert, your skills should include the following:
- __Material and MkDocs allrounder__ – You have an understanding of Material
for MkDocs and the MkDocs ecosystem, including many of its extensions and
plugins.
- __Great communicator__ – You enjoy helping others in a productive,
constructive and friendly manner and use inclusive and welcoming language.
- __Independent worker__ – You are self-motivated, stay up-to-date with
project developments, regularly check the discussion board, and respond to
notifications in reasonable time.
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
[documentation]: https://squidfunk.github.io/mkdocs-material/
[contribution guides]: ../contributing/index.md
## Your time commitment
We don't require a fixed number of hours each week; instead, we ask for a
minimum of __five answered discussions per month[^2]__, which amounts to
slightly more than one per week. Your active interaction within the community is
highly valued.
To do this effectively, it's best to regularly check the discussion board to see
where you can offer help. The time you invest may vary depending on the
complexity of the topics and questions.
Upon joining, you'll receive access to the Insiders' edition for as long as you
continue to assist us. Access will be renewed every three months, allowing you
the flexibility to continue your contributions or take a break as needed.
[^2]:
An answered discussion is a collaborative interaction where knowledge and
expertise are shared, resulting in resolutions or clarifications that benefit
the user and our entire community. In essence, it embodies the spirit of
cooperation and support within our community, highlighting the power of
collective wisdom and the willingness to assist and uplift one another.
## Ready to get started?
Since we have a limited number of seats for these roles[^3], we would like to
get to know you before you become one of our Community Experts. Here's how to
get started:
[^3]:
Please note that we're currently limiting the number of seats on the
Community Experts program to three. We will update this page when we'll
expand the team, which is when we'll be accepting new applications.
### Step 1: Get in touch
Send us an email introducing yourself, sharing a bit about your background, and
include a link to your GitHub profile. Additionally, provide links to three
previous discussions you've answered on the discussion board, where you've
assisted another community member.
Please use the following email template to reach out to us at
community@squidfunk.com:
```
Subject: Community Expert
Intro: Tell us a bit about yourself.
- Name:
- Background:
- Profession:
- GitHub profile:
Answered discussions
- Link 1:
- Link 2:
- Link 3:
```
### Step 2: Evaluation
After receiving and reviewing your application, we will get in touch with you
to discuss everything you need to know to get started. If you get selected, we
will set you up as a collaborator and provide you immediate access to the
Insiders edition for three months.
### Step 3: Dive in
Let's get started! You can actively begin participating in five discussions per
month. We trust you to take the lead, and we won't do strict monitoring. Simply
ensure that you are consistently listed on the _Most Helpful_ list, located on
the discussion board's left side, under the categories.
---
__Ready to join us?__
Sounds good? Let's give it a try!

359
docs/faq/sponsoring.md → docs/insiders/faq/sponsoring.md
View File

@ -1,12 +1,12 @@
# Sponsoring FAQs
Do you have questions about Material for MkDocs Insiders? We do our best to
answer all of your questions on this page. If you can't find your question
answer all of your questions on this page. If you can't find your question
below, ask it on our [discussion board]!
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions/new/chooses
## General
## General
[__Why is the Insiders edition offered as a subscription model?__](#insiders-subscription){ #insiders-subscription }
@ -19,23 +19,23 @@ In order to sustain the project and add new and useful features more frequently,
we decided to create the [Insiders] edition, with early access to the latest and
greatest features of Material for MkDocs. The subscription-based model of the
Insiders edition allows us to dedicate more time and resources to the project,
which benefits all
users of Material for MkDocs. Once our funding goals based on monthly
subscriptions are hit, the Insiders features of those^ funding goals are released
to the community edition, letting everyone benefit from them.
which benefits all
users of Material for MkDocs. Once our funding goals based on monthly
subscriptions are hit, the Insiders features of those^ funding goals are released
to the community edition, letting everyone benefit from them.
Maintaining both the community and Insiders editions is an ongoing process, and
we rely on our sponsors to support us on a monthly basis, which makes this whole
Maintaining both the community and Insiders editions is an ongoing process, and
we rely on our sponsors to support us on a monthly basis, which makes this whole
project possible.
[__What features are included in the Insiders edition?__](#insiders-features){ #insiders-features }
The Insiders edition includes more than 20 additional features. You can find an
The Insiders edition includes more than 20 additional features. You can find an
overview of these features on our [Insiders page], which is updated when new
features are added and released.
[Insiders]: ../insiders/index.md
[Insiders page]: ../insiders/index.md#whats-in-it-for-me
[Insiders]: ../index.md
[Insiders page]: ../index.md#whats-in-it-for-me
[__How often is the Insiders edition updated?__](#insiders-updates){ #insiders-updates }
@ -43,25 +43,25 @@ We try to keep our open issue count low, fixing known bugs quickly. Both our
repositories, the community and Insiders edition, are constantly updated with
bug fixes and new features.
## Sponsorship
## Sponsorship
[__Can I sponsor the project without a GitHub account?__](#sponsorship-account){ #sponsorship-account }
Yes. You can support Material for MkDocs by sponsoring us on [Ko-fi], regardless
of whether you have a GitHub account or not. However, please note that Insiders
is provided as a private repository on GitHub. If after sponsoring, you'd like to
gain access to the repository, you'll need to have a GitHub individual or bot
account that can be added as a collaborator. If your organization doesn't use
GitHub or/and host its repositories on other platforms, you can mirror the
Insiders repository in your environment once you have access.
No, you can't support Material for MkDocs if you don't have a GitHub account.
GitHub Sponsors handles all transactions and access management for us. Please
also note that the private Insiders repository is on GitHub, so in order to gain
access, you'll need to have a GitHub individual or bot account that can be added
as a collaborator. If your organization doesn't use GitHub or hosts its
repositories on other platforms, you can mirror the Insiders repository in your
environment once you have access.
[__Which sponsoring tier should I choose?__](#sponsorship-tier){ #sponsorship-tier }
The sponsoring tiers are divided into non-commercial and commercial tiers. If
The sponsoring tiers are divided into non-commercial and commercial tiers. If
you are an individual or organization using Material for MkDocs for private or
__non-commercial__ Open Source projects, you have two tiers to choose from,
depending on the number of sites you want to build. For companies using
Material for MkDocs, we offer three different __commercial__ tiers, from which
__non-commercial__ Open Source projects, you have two tiers to choose from,
depending on the number of sites you want to build. For companies using
Material for MkDocs, we offer three different __commercial__ tiers, from which
you can choose depending on your requirements.
Also, please read what is considered [commercial use].
@ -108,7 +108,7 @@ No, there are no limitations on the number of sponsors for any tier. You can
sponsor the project at any tier regardless of how many other sponsors are
already there.
## Payment & billing
## Payment & billing
[__Is there a trial period for the Insiders edition?__](#insiders-trial){ #insiders-trial }
@ -118,57 +118,54 @@ first give the Insiders edition a try, you can sponsor on the [$15] tier with a
personal account for non-commercial evaluation purposes.
Additionally, our subscription model allows you to cancel your sponsorship
anytime. If you decide to cancel, your sponsorship will remain active until
anytime. If you decide to cancel, your sponsorship will remain active until
the end of your billing cycle.
[__What payment options do you accept?__](#insiders-payment){ #insiders-payment }
We manage all our transactions and sponsorships through [GitHub Sponsors] and
[Ko-fi]. To become a sponsor of Material for MkDocs on GitHub, visit
[our sponsors' page]. On there, you can choose from five different sponsorship
tiers and pay by credit card. Please note that as of the beginning of 2023,
[GitHub no longer supports PayPal] payments. If you wish to pay with PayPal,
you can find a selection of our sponsorship tiers on [Ko-fi]. Both platforms
provide you with a payment receipt once your purchase is successful.
We manage all our transactions and sponsorships through [GitHub Sponsors]. To
become a sponsor of Material for MkDocs on GitHub, visit [our sponsors' page].
On there, you can choose from five different sponsorship tiers and pay by credit
card. Please note that as of the beginning of 2023,
[GitHub no longer supports PayPal] payments.
If you're a company and need assistance choosing the right payment method,
please don't hesitate to reach out to sponsors@squidfunk.com.
[Ko-fi]: https://ko-fi.com/squidfunk
[GitHub Sponsors]: https://github.com/sponsors
[GitHub no longer supports PayPal]: https://github.blog/changelog/2023-01-23-github-sponsors-will-stop-supporting-paypal/
[our sponsors' page]: https://github.com/sponsors/squidfunk/
[__Are discounts available for the Insiders edition, such as student discounts?__](#insiders-discounts){ #insiders-discounts }
Unfortunately, we are not able to offer any discounts for the Material for
MkDocs Insiders program. To ensure that everyone can afford the Insiders program
Unfortunately, we are not able to offer any discounts for the Material for
MkDocs Insiders program. To ensure that everyone can afford the Insiders program
and keep the barrier as low as possible, we have set prices as low as [$15] a
month for non-commercial use.
[__Do you offer free access to Insiders for Open Source projects?__](#insiders-open-source){ #insiders-open-source }
No, we do not offer free access to our Material for MkDocs Insiders edition.
We understand that non-profit organizations may have limited budgets and may
No, we do not offer free access to our Material for MkDocs Insiders edition.
We understand that non-profit organizations may have limited budgets and may
need to prioritize their spending on other projects or organizations. However,
it's important to note that Material for MkDocs is maintained by a small team,
investing a lot of time and resources into constantly improving this project.
Material for MkDocs and its core features are free to the community through our
it's important to note that Material for MkDocs is maintained by a small team,
investing a lot of time and resources into constantly improving this project.
Material for MkDocs and its core features are free to the community through our
Open Source model. Therefore, Material for MkDocs itself is already free.
However, we do offer an affordable sponsorship tier starting at [$15] a month,
which is meant for individuals and non-profit organizations using Material for
MkDocs to build 1-2 sites for non-commercial purposes. This tier provides access
However, we do offer an affordable sponsorship tier starting at [$15] a month,
which is meant for individuals and non-profit organizations using Material for
MkDocs to build 1-2 sites for non-commercial purposes. This tier provides access
to all new features, benefiting you from our ongoing development efforts.
[__Is Insiders free for those who contribute to this project?__](#insiders-contributors){ #insiders-contributors }
Great question! We can not offer free access to "drive-by" contributors that
only fix minor issues like typos or add new languages. These contributions are
always welcome, but as we need to review them, they result in a higher time
investment from our side and don't compensate for this work. However, as this
project keeps growing, we always seek for individuals to support us. In return,
we offer financial compensation or/and Insiders access. If you are interested
Great question! We can not offer free access to "drive-by" contributors that
only fix minor issues like typos or add new languages. These contributions are
always welcome, but as we need to review them, they result in a higher time
investment from our side and don't compensate for this work. However, as this
project keeps growing, we always seek for individuals to support us. In return,
we offer financial compensation or/and Insiders access. If you are interested
and have experience in the technologies and paradigms listed below, please get
in touch with us at sponsors@squidfunk.com:
@ -184,12 +181,12 @@ users with access to Insiders.
[__How can I set my billing to monthly or yearly?__](#insiders-billing-cycle){ #insiders-billing-cycle }
You can sponsor Material for MkDocs on a monthly or yearly basis. Depending on
your billing cycle you automatically become a monthly or yearly sponsor. Your
[billing cycle] is an account-level setting that you can easily change in your
account. If, for some reason, you cannot make this change, you can create a
dedicated bot account with a yearly billing cycle on GitHub, which you only use
for sponsoring (some sponsors already do that). If you have any problems or
You can sponsor Material for MkDocs on a monthly or yearly basis. Depending on
your billing cycle you automatically become a monthly or yearly sponsor. Your
[billing cycle] is an account-level setting that you can easily change in your
account. If, for some reason, you cannot make this change, you can create a
dedicated bot account with a yearly billing cycle on GitHub, which you only use
for sponsoring (some sponsors already do that). If you have any problems or
further questions, please contact us at sponsors@squidfunk.com.
[billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
@ -197,21 +194,21 @@ further questions, please contact us at sponsors@squidfunk.com.
[__Can I get an invoice for my sponsorship payment?__](#insiders-invoice){ #insiders-invoice}
Right now, we can't provide you with an invoice for your sponsoring transaction,
as [GitHub Sponsors] handles all transactions for us. However, both payment
platforms, [GitHub] and [Ko-Fi], automatically send you a payment receipt
via mail once the sponsorship is active.
as [GitHub Sponsors] handles all transactions for us. However, [GitHub Sponsors]
automatically sends you a payment receipt via mail once the sponsorship is
active.
Furthermore, we are working on a solution to optimize access management and more
features. If you are interested in this, please get in touch with us via mail at
sponsors@squidfunk.com or turn on all notifications for MkDocs, and we will
reach out as soon as we are live.
[GitHub]: https://github.com/sponsors/squidfunk/
[GitHub Sponsors]: https://github.com/sponsors/squidfunk/
[__Can I switch between different sponsoring tiers?__](#insiders-switch-tiers){ #insiders-switch-tiers }
Yes, you can switch between different sponsoring tiers at any time. Simply go
to the [GitHub Sponsors] page and change your sponsoring tier. Once you make
Yes, you can switch between different sponsoring tiers at any time. Simply go
to the [GitHub Sponsors] page and change your sponsoring tier. Once you make
that change, you will immediately change to the new tier.
If you change to a higher tier, the amount will be prorated according to your
@ -220,62 +217,62 @@ billing cycle.
[__Can I sponsor the project for a specific feature or development goal?__](#insiders-goals){ #insiders-goals }
While sponsoring specific goals directly is not possible, our sponsoring goals
are connected to specific features or development goals aligned with the
project's roadmap. You can find an [overview of these sponsoring goals] and their
associated features on our website. Insider users have early access to all
already developed features, including those associated with higher funding goals
that will be reached at a later stage. If you're interested in accessing these
features, becoming a sponsor is the way to go. If you have a feature in mind
that you would like to see on the list, we encourage you to
are connected to specific features or development goals aligned with the
project's roadmap. You can find an [overview of these sponsoring goals] and their
associated features on our website. Insider users have early access to all
already developed features, including those associated with higher funding goals
that will be reached at a later stage. If you're interested in accessing these
features, becoming a sponsor is the way to go. If you have a feature in mind
that you would like to see on the list, we encourage you to
[initiate a new discussion] to evaluate it with others.
[overview of these sponsoring goals]: ../insiders/index.md#goals
[overview of these sponsoring goals]: ../index.md#goals
[initiate a new discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new/chooses
[__What happens if I reach my sponsoring limit for my current tier?__](#insiders-limit){ #insiders-limit }
If you extend the number of sites that are in your current sponsoring limit,
please [upgrade your sponsorship] to a higher tier to continue using the
If you extend the number of sites that are in your current sponsoring limit,
please [upgrade your sponsorship] to a higher tier to continue using the
Insiders version and build more sites. The change will be effective immediately.
[upgrade your sponsorship]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship
[__Do you offer refunds for sponsoring payments?__](#insiders-refunds){ #insiders-refunds }
Unfortunately, we cannot offer any refund for sponsorship payments.
[GitHub Sponsors] and [Ko-Fi] manage all sponsoring transactions. Because of
that, we do not have any insights into the details of the funds and cannot access
them. If you have any payment issues, please get in touch with the GitHub
or Ko-Fi support team, as they can help you.
Unfortunately, we cannot offer any refund for sponsorship payments.
[GitHub Sponsors] manages all sponsoring transactions. Because of that, we do
not have any insights into the details of the funds and cannot access them. If
you have any payment issues, please get in touch with the GitHub Sponsors
support team, as they can help you.
## Access management
## Access management
[__How do I gain access to the private Insiders repository?__](#access-account){ #access-account }
If you sponsored with your __individual account__, you should have received an
email invitation to the private Material for MkDocs Insiders repository right
after you initiated your sponsorship. Simply accept the invitation within seven
If you sponsored with your __individual account__, you should have received an
email invitation to the private Material for MkDocs Insiders repository right
after you initiated your sponsorship. Simply accept the invitation within seven
days to gain access.
If you sponsored using an __organization account__, please note we need
an individual account that we can list as a collaborator of the private Insiders
repository. After you initiate your sponsorship, please email us at
sponsors@squidfunk.com with the name of the individual or bot account. Once you
provide us with this information, we will add the account as a collaborator, and
If you sponsored using an __organization account__, please note we need
an individual account that we can list as a collaborator of the private Insiders
repository. After you initiate your sponsorship, please email us at
sponsors@squidfunk.com with the name of the individual or bot account. Once you
provide us with this information, we will add the account as a collaborator, and
after you accept the invitation, you will gain access to the repository.
If you have yet to receive the email or the invitation link has expired, please
If you have yet to receive the email or the invitation link has expired, please
contact us, the maintainers, at sponsors@squidfunk.com. We're working on a
solution that will allow you to manage collaborator status yourself.
[__Why can't our whole organization get access to Insiders?__](#access-organization){ #access-organization }
Currently, it is not possible to grant access to an organizational account, as
GitHub only allows for adding individual user accounts. We are working on a
solution ourselves to simplify access for organizations. For now, to ensure that
access is not tied to a particular individual, we recommend creating a bot
account, i.e., a GitHub account that does not belong to a specific individual
but is listed as the owner of the organizational account and using this account
Currently, it is not possible to grant access to an organizational account, as
GitHub only allows for adding individual user accounts. We are working on a
solution ourselves to simplify access for organizations. For now, to ensure that
access is not tied to a particular individual, we recommend creating a bot
account, i.e., a GitHub account that does not belong to a specific individual
but is listed as the owner of the organizational account and using this account
for sponsorship.
[__Do I need to fork the repository to use it?__](#access-fork){ #access-fork }
@ -289,12 +286,12 @@ your fork.
[__Can I share my Insiders access with others?__](#access-share){ #access-share }
At the moment, it is not possible to directly share your collaborator status
for the private Insiders repository with other accounts. However, if you are
working with a team and would like them to access Insiders, you can share the
Insiders repository by utilizing options such as [cloning], [forking], or
[mirroring]. By doing so, you can start collaborating with your team members on
the new repository you have shared. This way, you can collectively benefit
At the moment, it is not possible to directly share your collaborator status
for the private Insiders repository with other accounts. However, if you are
working with a team and would like them to access Insiders, you can share the
Insiders repository by utilizing options such as [cloning], [forking], or
[mirroring]. By doing so, you can start collaborating with your team members on
the new repository you have shared. This way, you can collectively benefit
from the Insiders features and work together on the project.
[cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
@ -302,30 +299,30 @@ from the Insiders features and work together on the project.
[mirroring]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository
## Runtime & cancellation
## Runtime & cancellation
[__How long is my sponsorship valid?__](#sponsorship-runtime){ #sponsorship-runtime }
Your sponsorship is valid for as long as your monthly or yearly subscription
is valid. If you choose to cancel your sponsorship, you will lose access to
the Insiders edition once your cancelation is active and will be automatically
removed by GitHub as a collaborator from the private repository.
is valid. If you choose to cancel your sponsorship, you will lose access to
the Insiders edition once your cancelation is active and will be automatically
removed by GitHub as a collaborator from the private repository.
[__How do I cancel my sponsorship?__](#sponsorship-cancellation){ #sponsorship-cancellation }
To cancel your sponsorship, follow the [step-by-step guide] provided by GitHub.
If you sponsored using an organizational account, please ensure that you cancel
your sponsorship using the same organizational account rather than your
To cancel your sponsorship, follow the [step-by-step guide] provided by GitHub.
If you sponsored using an organizational account, please ensure that you cancel
your sponsorship using the same organizational account rather than your
individual account.
[step-by-step guide]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship
[__What happens when I cancel my sponsorship?__](#sponsorship-cancellation-effective){ #sponsorship-cancellation-effective }
If you choose to cancel your subscription to Insiders, you will be
automatically removed by GitHub as a collaborator on the day your cancellation is
effective. From that day on, you will no longer receive future updates. However,
you are __welcome to continue using the latest version__ that was available to
If you choose to cancel your subscription to Insiders, you will be
automatically removed by GitHub as a collaborator on the day your cancellation is
effective. From that day on, you will no longer receive future updates. However,
you are __welcome to continue using the latest version__ that was available to
you at the time of your cancellation for as long as you like.
Please note that [GitHub deletes private forks], so you may want to take steps to ensure
@ -333,15 +330,15 @@ that you have a backup of the software if necessary and use the locally installe
[GitHub deletes private forks]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository#deleting-forks-of-private-repositories
## Licensing
## Licensing
[__What constitutes commercial use of the Insiders version?__](#commercial-use){ #commercial-use }
Commercial use refers to any use of the software for a business or for-profit
purpose. This includes any use by a corporation or other organization, whether
or not they generate revenue directly from the software. We offer different
pricing tiers for commercial use, each tailored to the needs of different
businesses. It's important to note that internal use of the software within your
Commercial use refers to any use of the software for a business or for-profit
purpose. This includes any use by a corporation or other organization, whether
or not they generate revenue directly from the software. We offer different
pricing tiers for commercial use, each tailored to the needs of different
businesses. It's important to note that internal use of the software within your
organization is also considered commercial use, as with all commercial software.
[__What constitutes non-commercial use of the Insiders version?__](#non-commercial-use){ #non-commercial-use }
@ -349,62 +346,62 @@ organization is also considered commercial use, as with all commercial software.
Non-commercial use of our Material for MkDocs refers to private use. This
includes individuals using the Insiders edition for private or purely
non-commercial Open Source projects. We offer two different tiers for
non-commercial use, depending on the number of sites you want to build.
non-commercial use, depending on the number of sites you want to build.
[__What is your fair use policy?__](#fair-use-policy){ #fair-use-policy }
Our fair use policy includes the following guidelines:
- Please refrain from __distributing the source code__ of Insiders. While you
may use the software for public, private, or commercial projects and may
privately fork or mirror it, we ask that you keep the source code private. This
is important to our sponsorware strategy, which helps us fund ongoing
- Please refrain from __distributing the source code__ of Insiders. While you
may use the software for public, private, or commercial projects and may
privately fork or mirror it, we ask that you keep the source code private. This
is important to our sponsorware strategy, which helps us fund ongoing
development and support of the software. If this guidelines is violated,
everybody loses, as it will reduce the time of us maintainers we can set aside
to push this project forward.
- As our sponsoring tiers are based on the number of sites you want to build,
please make sure to [upgrade your sponsorship] once your current sponsoring tier
limit has been reached.
- As our sponsoring tiers are based on the number of sites you want to build,
please make sure to [upgrade your sponsorship] once your current sponsoring tier
limit has been reached.
[__Does the Insiders version have a different license?__](#insiders-license){ #insiders-license }
No. Whether you're an individual or a company, you may use Material for
MkDocs Insiders precisely under the same terms as Material for MkDocs, which are
No. Whether you're an individual or a company, you may use Material for
MkDocs Insiders precisely under the same terms as Material for MkDocs, which are
given by the [MIT license].
[MIT license]: ../license.md
[MIT license]: ../../license.md
[__Can outside collaborators build and run the documentation locally without access to Insiders?__](#insiders-outside-collaborators){ #insiders-outside-collaborators }
Yes. Insiders is compatible with Material for MkDocs. Almost all new features
and configuration options are either backward-compatible or implemented behind
feature flags. When working with outside collaborators, changing the general
appearance of your site should be optional. Most Insiders features enhance the
overall experience, e.g., by adding icons to pages or providing a feedback
widget. While these features add value for your site's users, they should be
optional for previewing when making changes to content. Currently, the only
content-related feature in Insiders that non-Insiders users can't properly
feature flags. When working with outside collaborators, changing the general
appearance of your site should be optional. Most Insiders features enhance the
overall experience, e.g., by adding icons to pages or providing a feedback
widget. While these features add value for your site's users, they should be
optional for previewing when making changes to content. Currently, the only
content-related feature in Insiders that non-Insiders users can't properly
preview are [Card grids].
This means that outside collaborators can build the documentation locally with
Material for MkDocs, and when they push their changes, your CI pipeline will
build it with Insiders. When using built-in plugins exclusive to Insiders, it's
recommended to split configuration into a base `mkdocs.yml` and one with plugin
This means that outside collaborators can build the documentation locally with
Material for MkDocs, and when they push their changes, your CI pipeline will
build it with Insiders. When using built-in plugins exclusive to Insiders, it's
recommended to split configuration into a base `mkdocs.yml` and one with plugin
overrides via [configuration inheritance].
See the [getting started guide] for more information.
[configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
[getting started guide]: ../insiders/getting-started.md#caveats
[Card grids]: ../reference/grids.md?h=grids#using-card-grids
[getting started guide]: ../getting-started.md#caveats
[Card grids]: ../../reference/grids.md?h=grids#using-card-grids
## Support
## Support
[__How can I contact support if I have questions about becoming a sponsor?__ ](#support-contact){ #support-contact }
If you have any questions and would like to contact us before starting your
sponsorship, we are happy to answer all your non-technical questions about the
If you have any questions and would like to contact us before starting your
sponsorship, we are happy to answer all your non-technical questions about the
Insiders program via email at sponsors@squidfunk.com.
All technical questions should be asked openly on our [discussion board].
@ -414,15 +411,15 @@ All technical questions should be asked openly on our [discussion board].
[__Is additional support available for Material for MkDocs Insiders users?__](#support-additional){ #support-additional }
Yes, we provide non-technical support related to sponsoring at
sponsors@squidfunk.com. For technical questions, please submit an issue openly
on our [issue tracker] or start a discussion on our [discussion board]. Issues
and discussions from our organizational sponsors, sponsoring on
sponsors@squidfunk.com. For technical questions, please submit an issue openly
on our [issue tracker] or start a discussion on our [discussion board]. Issues
and discussions from our organizational sponsors, sponsoring on
__The Organization__ tier or higher will be prioritized.[^1]
[^1]:
Priority support means we will prioritize your issue, meaning we will look
into it and do our best to solve your issue asap. However, the prioritized bug
support does not mean that we can solve your issue before any others since
Priority support means we will prioritize your issue, meaning we will look
into it and do our best to solve your issue asap. However, the prioritized bug
support does not mean that we can solve your issue before any others since
some issues might take more time to solve.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
@ -433,49 +430,75 @@ If your sponsorship tier includes logo placement, and you would like us to
display your logo in the [list of premium sponsors] and have it linked to your
site, please contact us via mail. Simply send us a horizontal SVG or PNG version
of your logo making sure it displays the name of your company and the logo to
sponsors@squidfunk.com.
sponsors@squidfunk.com.
[list of premium sponsors]: https://github.com/squidfunk/mkdocs-material#user-content-premium-sponsors
[__Is logo placement optional?__](#sponsorship-logo-placement-optional){ #sponsorship-logo-placement-optional }
Yes, all of our commercial benefits, such as logo placement and backlinks, are
Yes, all of our commercial benefits, such as logo placement and backlinks, are
optional and can be opted in or out at any time. You can keep your sponsorship
completely private.
[__How can I report a bug in the Insiders version?__](#insiders-bugs){ #insiders-bugs }
If you encounter a bug in the Insiders edition, we kindly request that you
report it on our [issue tracker] in the public community repository. When
submitting the bug report, please ensure that you do not include any private
Insiders' source code, as we want to uphold our fair use policy.
If you encounter a bug in the Insiders edition, we kindly request that you
report it on our [issue tracker] in the public community repository. When
submitting the bug report, please ensure that you do not include any private
Insiders' source code, as we want to uphold our fair use policy.
[__How can I report an issue in my customizations?__](#customizations-issues){ #costumisations-issues }
## Privacy
Please note, that we do not offer support for customizations as they vary
widely and are specific to individual cases. Our support is primarily focused on
assisting with our core features. When reporting an issue, please remove all
customizations to ensure effective problem diagnosis with a minimal reproduction
[.zip file], as described in our bug reporting guide. Our [built-in info plugin],
which is essential when creating a reproduction, will not function correctly
with customizations in place. For questions and issues with customizations,
please use our [discussion board] to engage with the community.
[.zip file]: ../../guides/creating-a-reproduction.md
[built-in info plugin]: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/#creating-a-zip-file
## Privacy
[__Will you sign an NDA for sponsorships?__](#nda){ #nda }
Unfortunately, we cannot sign any NDA or vendor agreement form. As a small team
working on Material for MkDocs, we have limited resources and cannot review
working on Material for MkDocs, we have limited resources and cannot review
and sign agreements.
[__Will you fill out our companys forms?__](#forms){ #forms }
To dedicate more time and resources to the development of our projects, we have
implemented measures to minimize administrative overhead for our small team. As
part of this approach, we have adopted GitHub Sponsors to efficiently handle all
transactions for us. Consequently, we have decided to introduce a setup fee for
any additional administrative tasks other than those handled by GitHub Sponsors
that require our attention and involve the completion of forms or adherence to
company processes when purchasing Material for MkDocs Insiders. If your purchase
departmenz requires additional time and effort from our team, please be aware
that the setup fee will apply. For detailed information and specific inquiries,
please reach out to us at sponsors@squidfunk.com.
[__Can I sponsor privately?__](#sponsorship-private){ #sponsorship-private }
Yes, you can. GitHub gives you the option to set your sponsorship to [private]
when you set up your sponsorship. Additionally, we have a recommended workflow
for you: We suggest you create a new GitHub bot account. This bot account should
not be tied to a particular individual and should be privately listed as an
owner of your GitHub organization. This account can then be used to sponsor
Material for MkDocs privately. As a bot account, it will automatically be listed
as a collaborator of the private Insiders repository. You can clone, fork, or
mirror using this account. All information will be kept confidential; only the
bot account and us maintainers will have insights into his sponsorship.
Yes, you can. GitHub gives you the option to set your sponsorship to [private]
when you set up your sponsorship. Additionally, we have a recommended workflow
for you: We suggest you create a new GitHub bot account. This bot account should
not be tied to a particular individual and should be privately listed as an
owner of your GitHub organization. This account can then be used to sponsor
Material for MkDocs privately. As a bot account, it will automatically be listed
as a collaborator of the private Insiders repository. You can clone, fork, or
mirror using this account. All information will be kept confidential; only the
bot account and us maintainers will have insights into his sponsorship.
[private]: https://docs.github.com/en/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship#managing-the-privacy-setting-for-your-sponsorship
[__Are there any geographical restrictions on becoming a sponsor?__](#sponsorship-geo){ #sponsorship-geo }
No, there are no geographical restrictions for becoming a sponsor. We welcome
sponsorships from individuals and organizations worldwide. As long as your
credit card is valid and accepted by GitHub or Ko-Fi, you are eligible to become
a sponsor and support the project, regardless of your location.
No, there are no geographical restrictions for becoming a sponsor. We welcome
sponsorships from individuals and organizations worldwide. As long as your
credit card is valid and accepted by GitHub you are eligible to become
a sponsor and support the project, regardless of your location.

157
docs/insiders/index.md
View File

@ -93,13 +93,19 @@ which are currently exclusively available to sponsors:
<div class="mdx-columns" markdown>
- [x] [Projects plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
- [x] [Instant prefetching] :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
- [x] [Social plugin: custom layouts] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
- [x] [Social plugin: background images] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
- [x] [Tags plugin: advanced settings] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
- [x] [Tags plugin: nested tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
- [x] [Tags plugin: shadow tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
- [x] [Stay on page when switching languages]
- [x] [Blog plugin: author profiles]
- [x] [Blog plugin: advanced settings]
- [x] [Projects plugin]
- [x] [Instant prefetching]
- [x] [Social plugin: custom layouts]
- [x] [Social plugin: background images]
- [x] [Code range selection]
- [x] [Code annotations: custom selectors]
- [x] [Privacy plugin: optimization support]
- [x] [Privacy plugin: advanced settings]
- [x] [Optimize plugin]
- [x] [Navigation path] (Breadcrumbs)
- [x] [Typeset plugin]
@ -109,13 +115,7 @@ which are currently exclusively available to sponsors:
- [x] [Blog plugin: custom index pages]
- [x] [Blog plugin: related links]
- [x] [Meta plugin]
- [x] [Tags plugin: additional indexes]
- [x] [Document contributors]
- [x] [Automatic light / dark mode]
- [x] [Content tabs: anchor links]
- [x] [Tooltips]
- [x] [Card grids]
- [x] [Privacy plugin]
- [x] [Tags plugin: configurable listings]
</div>
@ -166,15 +166,14 @@ You can cancel your sponsorship anytime.[^5]
**Silver sponsors**:
[![FastAPI]{ style="height: 120px" }](https://fastapi.tiangolo.com/){ target=_blank title="FastAPI" }
[![Trendpop]{ style="height: 120px" }](https://www.trendpop.com/){ target=_blank title="Trendpop" }
**Bronze sponsors**:
[![Cirrus CI]](https://cirrus-ci.org/){ target=_blank title="Cirrus CI" }
[![Basler]](https://docs.baslerweb.com/){ target=_blank title="Basler" }
[![KX]](https://kx.com/){ target=_blank title="KX Systems" }
[![Manticore Games]](https://www.manticoregames.com/){ target=_blank title="Manticore Games" }
[![Prefect]](https://orion-docs.prefect.io/){ target=_blank title="Prefect" }
[![Datadog]](https://datadoghq.com/){ target=_blank title="Datadog" }
[![Zenoss]](https://zenoss.com/){ target=_blank title="Zenoss" }
[![Posit]](https://docs.posit.co){ target=_blank title="Posit" }
[![n8n]](https://n8n.io){ target=_blank title="n8n" }
@ -202,16 +201,16 @@ You can cancel your sponsorship anytime.[^5]
[![Bühler Group]](https://www.buhlergroup.com/){ target=_blank title="Bühler Group" }
[![Transformation Flow]](https://transformationflow.io/){ target=_blank title="Transformation Flow" }
[![3DR]](https://3dr.com/){ target=_blank title="3DR" }
[![Spotware]](https://spotware.com/){ target=_blank title="Spotware" }
</div>
[FastAPI]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-fastapi.png
[Trendpop]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-trendpop.png
[Cirrus CI]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cirrus-ci.png
[Basler]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-basler.png
[KX]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kx.png
[Manticore Games]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-manticore-games.png
[Prefect]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-prefect.png
[Datadog]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-datadog.png
[Zenoss]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-zenoss.png
[Posit]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-posit.png
[n8n]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-n8n.png
@ -240,6 +239,7 @@ You can cancel your sponsorship anytime.[^5]
[Bühler Group]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-buhler.png
[Transformation Flow]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-transformationflow.png
[3DR]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-3dr.png
[Spotware]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-spotware.png
<hr />
@ -266,6 +266,75 @@ features prefixed with a checkmark symbol, denoting whether a feature is
:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features
are released for general availability.
#### $ 16,000 – Chipotle
- [x] [Meta plugin]
- [x] [Blog plugin: related links]
- [x] [Blog plugin: custom index pages]
- [x] [Tags plugin: configurable listings]
- [x] [Tags plugin: allow list] + [custom sorting]
- [x] [Navigation subtitles]
[Meta plugin]: ../plugins/meta.md
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
[Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
[Tags plugin: configurable listings]: ../setup/setting-up-tags.md#configurable-listings
[Tags plugin: allow list]: ../plugins/tags.md#config.tags_allowed
[custom sorting]: ../plugins/tags.md#config.tags_sort_by
[Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
#### $ 20,000 – Jalapeño
- [x] [Optimize plugin]
- [x] [Typeset plugin]
- [x] [Navigation path] (Breadcrumbs)
- [x] [Privacy plugin: advanced settings]
- [x] [Privacy plugin: external links]
- [x] [Instant prefetching]
- [x] [Blog plugin: advanced settings]
- [x] [Blog plugin: author profiles]
[Optimize plugin]: ../plugins/optimize.md
[Typeset plugin]: ../plugins/typeset.md
[Privacy plugin: external links]: ../plugins/privacy.md#external-links
[Privacy plugin: advanced settings]: ../setup/ensuring-data-privacy.md#advanced-settings
[Navigation path]: ../setup/setting-up-navigation.md#navigation-path
[Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
[Blog plugin: advanced settings]: ../setup/setting-up-a-blog.md#advanced-settings
[Blog plugin: author profiles]: ../setup/setting-up-a-blog.md#adding-author-profiles
#### $ 24,000 – Blockpaprika
- [x] [Projects plugin]
- [x] [Social plugin: custom layouts]
- [x] [Social plugin: background images]
- [x] [Code range selection]
- [x] [Code annotations: custom selectors]
- [x] [Stay on page when switching languages]
- [x] [Tags plugin: nested tags]
- [x] [Tags plugin: shadow tags]
[Projects plugin]: ../plugins/projects.md
[Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
[Social plugin: background images]: ../plugins/social.md#option.background_image
[Code range selection]: ../reference/code-blocks.md#code-selection-button
[Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
[Stay on page when switching languages]: ../setup/changing-the-language.md#stay-on-page
[Tags plugin: nested tags]: ../setup/setting-up-tags.md#nested-tags
[Tags plugin: shadow tags]: ../setup/setting-up-tags.md#shadow-tags
#### $ 28,000 – Lemon Drop
- [x] [Tags plugin: advanced settings]
[Tags plugin: advanced settings]: ../setup/setting-up-tags.md#advanced-settings
### Goals completed
This section lists all funding goals that were previously completed, which means
that those features were part of Insiders, but are now generally available and
can be used by all users.
#### $ 14,000 – Goat's Horn
- [x] [Privacy plugin]
@ -275,67 +344,13 @@ are released for general availability.
- [x] [Automatic light / dark mode]
- [x] [Document contributors]
[Privacy plugin]: ../setup/ensuring-data-privacy.md
[Privacy plugin]: ../setup/ensuring-data-privacy.md#built-in-privacy-plugin
[Card grids]: ../reference/grids.md
[Tooltips]: ../reference/tooltips.md
[Content tabs: anchor links]: ../reference/content-tabs.md#anchor-links
[Automatic light / dark mode]: ../setup/changing-the-colors.md#automatic-light-dark-mode
[Document contributors]: ../setup/adding-a-git-repository.md#document-contributors
#### $ 16,000 – Chipotle
- [x] [Meta plugin]
- [x] [Blog plugin: related links]
- [x] [Blog plugin: custom index pages]
- [x] [Tags plugin: additional indexes]
- [x] [Tags plugin: allow list] + [custom sorting]
- [x] [Navigation subtitles]
[Meta plugin]: ../plugins/meta.md
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
[Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
[Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
[Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed
[custom sorting]: ../setup/setting-up-tags.md#+tags.tags_compare
[Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
#### $ 20,000 – Jalapeño
- [x] [Optimize plugin]
- [x] [Typeset plugin]
- [x] [Navigation path] (Breadcrumbs)
- [x] [Privacy plugin: optimization support]
- [x] [Privacy plugin: external links]
- [x] [Instant prefetching]
[Optimize plugin]: ../plugins/optimize.md
[Typeset plugin]: ../plugins/typeset.md
[Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
[Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
[Navigation path]: ../setup/setting-up-navigation.md#navigation-path
[Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
#### $ 24,000 – Blockpaprika
- [x] [Projects plugin]
- [x] [Social plugin: custom layouts]
- [x] [Social plugin: background images]
- [x] [Code range selection]
- [x] [Code annotations: custom selectors]
- [ ] Code line wrap button
[Projects plugin]: ../plugins/projects.md
[Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
[Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
[Code range selection]: ../reference/code-blocks.md#code-selection-button
[Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
### Goals completed
This section lists all funding goals that were previously completed, which means
that those features were part of Insiders, but are now generally available and
can be used by all users.
#### $ 12,000 – Piri Piri
- [x] [Blog plugin]

2
docs/license.md
View File

@ -2,7 +2,7 @@
**MIT License**
Copyright (c) 2016-2023 Martin Donath
Copyright (c) 2016-2024 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to

520
docs/plugins/blog.md
View File

@ -153,6 +153,35 @@ installed.
[blog]: blog.md
[built-in plugins]: index.md
### Navigation
If you do not have site navigation configured in your `mkdocs.yml` then there is
nothing more to do. The blog [archive] and [category] pages will automatically
appear underneath the automatically generated navigation.
If you do have a navigation structure defined then you will need to specify
where the blog should appear in this. Create a [navigation section with an index
page] for the blog:
```yaml
theme:
name: material
features:
- navigation.indexes
nav:
- ...
- Blog:
- blog/index.md
```
The [archive] and [category] pages will appear within that section as
subsections beneath pages in the blog section. In this case, they would appear
after `index.md`. The path to the `index.md` file must match
[blog_dir][config.blog_dir]. This means that you can name the blog navigation
entry anything you like: 'Blog' or 'News' or perhaps 'Tips'.
[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages
### General
The following settings are available:
@ -213,9 +242,8 @@ The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
<!-- md:default `false` -->
Use this setting to leverage the table of contents to display post titles in
views. The value of this setting is inherited by [`archive_toc`]
[config.archive_toc] and [`categories_toc`][config.categories_toc],
unless they are explicitly set:
views. This might be useful, if your post excerpts are rather long. If you want
to enable it, use:
``` yaml
plugins:
@ -265,7 +293,7 @@ Use this setting to change the date format of posts. This plugin uses [babel]
to render dates in the configured [site language]. You can use [babel]'s
[pattern syntax] or the following shortcodes:
=== "Monday, January 31, 2023"
=== "Monday, January 31, 2024"
``` yaml
plugins:
@ -273,7 +301,7 @@ to render dates in the configured [site language]. You can use [babel]'s
post_date_format: full
```
=== "January 31, 2023"
=== "January 31, 2024"
``` yaml
plugins:
@ -281,7 +309,7 @@ to render dates in the configured [site language]. You can use [babel]'s
post_date_format: long
```
=== "Jan 31, 2023"
=== "Jan 31, 2024"
``` yaml
plugins:
@ -289,7 +317,7 @@ to render dates in the configured [site language]. You can use [babel]'s
post_date_format: medium
```
=== "1/31/22"
=== "1/31/24"
``` yaml
plugins:
@ -315,7 +343,7 @@ Use this setting to change the date format used in post URLs. The format string
must adhere to [babel]'s [pattern syntax] and should not contain whitespace.
Some popular choices:
=== ":material-link: blog/2023/01/31/:material-dots-horizontal:/"
=== ":material-link: blog/2024/01/31/:material-dots-horizontal:/"
``` yaml
plugins:
@ -323,7 +351,7 @@ Some popular choices:
post_url_date_format: yyyy/MM/dd
```
=== ":material-link: blog/2023/01/:material-dots-horizontal:/"
=== ":material-link: blog/2024/01/:material-dots-horizontal:/"
``` yaml
plugins:
@ -331,7 +359,7 @@ Some popular choices:
post_url_date_format: yyyy/MM
```
=== ":material-link: blog/2023/:material-dots-horizontal:/"
=== ":material-link: blog/2024/:material-dots-horizontal:/"
``` yaml
plugins:
@ -354,7 +382,7 @@ Use this setting to change the format string that is used when generating post
URLs. You can freely combine placeholders, and join them with slashes or other
characters:
=== ":material-link: blog/2023/:material-dots-horizontal:/"
=== ":material-link: blog/2024/:material-dots-horizontal:/"
``` yaml
plugins:
@ -406,35 +434,24 @@ If more than one category is given, they are joined with `/` after slugifying.
#### <!-- md:setting config.post_slugify -->
<!-- md:version 9.2.0 -->
<!-- md:default [`toc.slugify`][toc.slugify] -->
<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
Use this setting to change the function to use for generating URL-compatible
slugs from post titles. [Python Markdown Extensions] comes with a Unicode-aware
[`slugify`][pymdownx.slugs.slugify] function:
Use this setting to change the function for generating URL-compatible slugs
from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
from [Python Markdown Extensions] is used as follows:
=== "Unicode"
``` yaml
plugins:
- blog:
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
``` yaml
plugins:
- blog:
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
The default configuration is Unicode-aware and should produce good slugs for all
languages. Of course, you can also provide a custom slugification function for
more granular control.
=== "Unicode, case-sensitive"
``` yaml
plugins:
- blog:
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
When your project features non-European languages, it's advisable to use this
configuration. Of course, you can also provide a custom slugification function
for more granular control.
[toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
[pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
@ -652,7 +669,7 @@ plugins:
Use this setting to change the date format used for archive page titles. The
format string must adhere to [babel]'s [pattern syntax]. Some popular choices:
=== "2023"
=== "2024"
``` yaml
plugins:
@ -660,7 +677,7 @@ format string must adhere to [babel]'s [pattern syntax]. Some popular choices:
archive_date_format: yyyy
```
=== "January 2023"
=== "January 2024"
``` yaml
plugins:
@ -682,7 +699,7 @@ Use this setting to change the date format used for archive page URLs. The
format string must adhere to [babel]'s [pattern syntax] and should not contain
whitespace. Some popular choices:
=== ":material-link: blog/archive/2023/"
=== ":material-link: blog/archive/2024/"
``` yaml
plugins:
@ -690,7 +707,7 @@ whitespace. Some popular choices:
archive_url_date_format: yyyy
```
=== ":material-link: blog/archive/2023/01/"
=== ":material-link: blog/archive/2024/01/"
``` yaml
plugins:
@ -709,7 +726,7 @@ Use this setting to change the format string that is used when generating
archive page URLs. You can freely combine placeholders, and join them with
slashes or other characters:
=== ":material-link: blog/archive/2023/"
=== ":material-link: blog/archive/2024/"
``` yaml
plugins:
@ -717,7 +734,7 @@ slashes or other characters:
archive_url_format: "archive/{date}"
```
=== ":material-link: blog/2023/"
=== ":material-link: blog/2024/"
``` yaml
plugins:
@ -731,6 +748,42 @@ The following placeholders are available:
---
#### <!-- md:setting config.archive_pagination -->
<!-- md:sponsors -->
<!-- md:version insiders-4.44.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable pagination for archive pages. The value
of this setting is inherited from [`pagination`][config.pagination], unless it's
explicitly set. To disable pagination, use:
``` yaml
plugins:
- blog:
archive_pagination: false
```
---
#### <!-- md:setting config.archive_pagination_per_page -->
<!-- md:sponsors -->
<!-- md:version insiders-4.44.0 -->
<!-- md:default `10` -->
Use this setting to change the number of posts rendered per archive page. The
value of this setting is inherited from [`pagination_per_page`]
[config.pagination_per_page], unless it's explicitly set. To change it, use:
``` yaml
plugins:
- blog:
archive_pagination_per_page: 5
```
---
#### <!-- md:setting config.archive_toc -->
<!-- md:version 9.2.0 -->
@ -738,7 +791,7 @@ The following placeholders are available:
Use this setting to leverage the table of contents to display post titles on all
archive pages. The value of this setting is inherited from [`blog_toc`]
[config.blog_toc], unless its explicitly set:
[config.blog_toc], unless it's explicitly set. To change it, use
``` yaml
plugins:
@ -820,31 +873,23 @@ The following placeholders are available:
#### <!-- md:setting config.categories_slugify -->
<!-- md:version 9.2.0 -->
<!-- md:default [`toc.slugify`][toc.slugify] -->
<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
Use this setting to change the function to use for generating URL-compatible
slugs from categories. [Python Markdown Extensions] comes with a Unicode-aware
[`slugify`][pymdownx.slugs.slugify] function:
Use this setting to change the function for generating URL-compatible slugs
from categories. By default, the [`slugify`][pymdownx.slugs.slugify] function
from [Python Markdown Extensions] is used as follows:
=== "Unicode"
``` yaml
plugins:
- blog:
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
``` yaml
plugins:
- blog:
categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
=== "Unicode, case-sensitive"
``` yaml
plugins:
- blog:
categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
When your project features non-European languages, it's advisable to use this
configuration.
The default configuration is Unicode-aware and should produce good slugs for all
languages. Of course, you can also provide a custom slugification function for
more granular control.
---
@ -865,6 +910,46 @@ plugins:
---
#### <!-- md:setting config.categories_sort_by -->
<!-- md:sponsors -->
<!-- md:version insiders-4.45.0 -->
<!-- md:default `material.plugins.blog.view_name` -->
Use this setting to specify a custom function for sorting categories. For
example, if you want to sort categories by the number of posts they contain,
use the following configuration:
``` yaml
plugins:
- blog:
categories_sort_by: !!python/name:material.plugins.blog.view_post_count
```
Don't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].
You can define your own comparison function, which must return something
that can be compared while sorting, i.e., a string or number.
---
#### <!-- md:setting config.categories_sort_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.45.0 -->
<!-- md:default `false` -->
Use this setting to reverse the order in which categories are sorted. By
default, categories are sorted in ascending order, but you can reverse ordering
as follows:
``` yaml
plugins:
- blog:
categories_sort_reverse: true
```
---
#### <!-- md:setting config.categories_allowed -->
<!-- md:version 9.2.0 -->
@ -888,6 +973,42 @@ this list. Posts can be assigned to categories by using the [`categories`]
---
#### <!-- md:setting config.categories_pagination -->
<!-- md:sponsors -->
<!-- md:version insiders-4.44.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable pagination for category pages. The value
of this setting is inherited from [`pagination`][config.pagination], unless it's
explicitly set. To disable pagination, use:
``` yaml
plugins:
- blog:
categories_pagination: false
```
---
#### <!-- md:setting config.categories_pagination_per_page -->
<!-- md:sponsors -->
<!-- md:version insiders-4.44.0 -->
<!-- md:default `10` -->
Use this setting to change the number of posts rendered per category page. The
value of this setting is inherited from [`pagination_per_page`]
[config.pagination_per_page], unless it's explicitly set. To change it, use:
``` yaml
plugins:
- blog:
categories_pagination_per_page: 5
```
---
#### <!-- md:setting config.categories_toc -->
<!-- md:version 9.2.0 -->
@ -895,7 +1016,7 @@ this list. Posts can be assigned to categories by using the [`categories`]
Use this setting to leverage the table of contents to display post titles on all
category pages. The value of this setting is inherited from [`blog_toc`]
[config.blog_toc], unless its explicitly set:
[config.blog_toc], unless it's explicitly set. To change it, use:
``` yaml
plugins:
@ -903,6 +1024,195 @@ plugins:
categories_toc: true
```
### Authors
The following settings are available for authors:
---
#### <!-- md:setting config.authors -->
<!-- md:version 9.2.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable post authors. If this setting is enabled,
the plugin will look for a file named [`.authors.yml`][config.authors_file] and
render authors in posts and views. Disable this behavior with:
``` yaml
plugins:
- blog:
authors: false
```
---
#### <!-- md:setting config.authors_file -->
<!-- md:version 9.2.0 -->
<!-- md:default `{blog}/.authors.yml` -->
Use this setting to change the path of the file where the author information for
your posts resides. It's normally not necessary to change this setting, but if
you need to, use:
``` yaml
plugins:
- blog:
authors_file: "{blog}/.authors.yml"
```
The following placeholders are available:
- `blog` – [`blog` directory][config.blog_dir]
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
!!! info "Format of author information"
The `.authors.yml` file must adhere to the following format:
``` yaml title=".authors.yml"
authors:
<author>:
name: string # Author name
description: string # Author description
avatar: url # Author avatar
slug: url # Author profile slug
url: url # Author website URL
```
Note that `<author>` must be set to an identifier for associating authors
with posts, e.g., a GitHub username like `squidfunk`. This identifier can
then be used in the [`authors`][meta.authors] metadata property of
a post. Multiple authors are supported. As an example, see
[the `.authors.yml` file][.authors.yml] we're using for our blog.
[.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
---
#### <!-- md:setting config.authors_profiles -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `false` -->
Use this setting to enable or disable automatically generated author profiles.
An author profile shows all posts by an author in reverse chronological order.
You can enable author profiles with:
``` yaml
plugins:
- blog:
authors_profiles: true
```
---
#### <!-- md:setting config.authors_profiles_name -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default computed -->
Use this setting to change the title of the authors section the plugin adds to
the navigation. If this setting is omitted, it's sourced from the translations.
If you want to change it, use:
``` yaml
plugins:
- blog:
authors_profiles_name: Authors
```
---
#### <!-- md:setting config.authors_profiles_url_format -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `author/{slug}` -->
Use this setting to change the format string that is used when generating
author profile URLs. You can freely combine placeholders, and join them with
slashes or other characters:
=== ":material-link: blog/author/:material-dots-horizontal:/"
``` yaml
plugins:
- blog:
authors_profiles_url_format: "author/{slug}"
```
=== ":material-link: blog/:material-dots-horizontal:/"
``` yaml
plugins:
- blog:
authors_profiles_url_format: "{slug}"
```
The following placeholders are available:
- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]
- `name` – Author name from [`authors_file`][config.authors_file]
---
#### <!-- md:setting config.authors_profiles_pagination -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable pagination for author profiles. The value
of this setting is inherited from [`pagination`][config.pagination], unless it's
explicitly set. To disable pagination, use:
``` yaml
plugins:
- blog:
authors_profiles_pagination: false
```
---
#### <!-- md:setting config.authors_profiles_pagination_per_page -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `10` -->
Use this setting to change the number of posts rendered per archive page. The
value of this setting is inherited from [`pagination_per_page`]
[config.pagination_per_page], unless it's explicitly set. To change it, use:
``` yaml
plugins:
- blog:
authors_profiles_pagination_per_page: 5
```
---
#### <!-- md:setting config.authors_profiles_toc -->
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:default `false` -->
Use this setting to leverage the table of contents to display post titles on all
author profiles. The value of this setting is inherited from [`blog_toc`]
[config.blog_toc], unless it's explicitly set. To change it, use:
``` yaml
plugins:
- blog:
authors_profiles_toc: true
```
### Pagination
The following settings are available for pagination:
@ -1058,70 +1368,6 @@ plugins:
pagination_keep_content: true
```
### Authors
The following settings are available for authors:
---
#### <!-- md:setting config.authors -->
<!-- md:version 9.2.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable post authors. If this setting is enabled,
the plugin will look for a file named [`.authors.yml`][config.authors_file] and
render authors in posts and views. Disable this behavior with:
``` yaml
plugins:
- blog:
authors: false
```
---
#### <!-- md:setting config.authors_file -->
<!-- md:version 9.2.0 -->
<!-- md:default `{blog}/.authors.yml` -->
Use this setting to change the path of the file where the author information for
your posts resides. It's normally not necessary to change this setting, but if
you need to, use:
``` yaml
plugins:
- blog:
authors_file: "{blog}/.authors.yml"
```
The following placeholders are available:
- `blog` – [`blog` directory][config.blog_dir]
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
!!! info "Format of author information"
The `.authors.yml` file must adhere to the following format:
``` yaml title=".authors.yml"
authors:
<author>:
name: string # Author name
description: string # Author description
avatar: url # Author avatar
```
Note that `<author>` must be set to an identifier for associating authors
with posts, e.g., a GitHub username like `squidfunk`. This identifier can
then be used in the [`authors`][meta.authors] metadata property of
a post. Multiple authors are supported. As an example, see
[the `.authors.yml` file][.authors.yml] we're using for our blog.
[.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
### Drafts
The following settings are available for drafts:
@ -1270,7 +1516,7 @@ using a slightly different syntax:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
---
# Post title
@ -1282,8 +1528,8 @@ using a slightly different syntax:
``` yaml
---
date:
created: 2023-01-31 # (1)!
updated: 2023-02-01
created: 2024-01-31 # (1)!
updated: 2024-02-01
---
# Post title
@ -1297,8 +1543,8 @@ using a slightly different syntax:
``` yaml
---
date:
created: 2023-01-31
my_custom_date: 2023-02-01 # (1)!
created: 2024-01-31
my_custom_date: 2024-02-01 # (1)!
---
# Post title
@ -1313,8 +1559,8 @@ using a slightly different syntax:
The following date formats are supported:
- `2023-01-31`
- `2023-01-31T12:00:00`
- `2024-01-31`
- `2024-01-31T12:00:00`
---

4
docs/plugins/group.md
View File

@ -64,7 +64,7 @@ The following settings are available:
#### <!-- md:setting config.enabled -->
<!-- md:version 9.2.0 -->
<!-- md:version 9.3.0 -->
<!-- md:default `false` -->
Use this setting to enable or disable the plugin when [building your project].
@ -103,7 +103,7 @@ CI=true mkdocs build
#### <!-- md:setting config.plugins -->
<!-- md:version 9.2.0 -->
<!-- md:version 9.3.0 -->
<!-- md:default none -->
Use this setting to list the plugins that are part of the group. The syntax is

7
docs/plugins/meta.md
View File

@ -10,6 +10,13 @@ pages in a folder, i.e., a subsection of your project, which is particularly
useful to ensure that a certain subset of pages features specific tags, uses a
custom template, or is attributed to an author.
---
<!-- md:sponsors --> __Sponsors only__ – this plugin is currently reserved to
[our awesome sponsors].
[our awesome sponsors]: ../insiders/index.md
## Objective
### How it works

6
docs/plugins/optimize.md
View File

@ -10,7 +10,13 @@ The optimize plugin automatically identifies and optimizes all media files when
As a result, your site loads significantly faster and yields better rankings in
search engines.
---
<!-- md:sponsors --> __Sponsors only__ – this plugin is currently reserved to
[our awesome sponsors].
[building your project]: ../creating-your-site.md#building-your-site
[our awesome sponsors]: ../insiders/index.md
## Objective

102
docs/plugins/privacy.md
View File

@ -99,8 +99,7 @@ pipelines tailored to your project:
## Configuration
<!-- md:sponsors -->
<!-- md:version insiders-4.9.0 -->
<!-- md:version 9.5.0 -->
<!-- md:plugin [privacy] – built-in -->
<!-- md:flag multiple -->
<!-- md:flag experimental -->
@ -128,8 +127,7 @@ The following settings are available:
#### <!-- md:setting config.enabled -->
<!-- md:sponsors -->
<!-- md:version insiders-4.10.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable the plugin when [building your project].
@ -148,8 +146,7 @@ This configuration enables the plugin only during continuous integration (CI).
#### <!-- md:setting config.concurrency -->
<!-- md:sponsors -->
<!-- md:version insiders-4.30.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default available CPUs - 1 -->
With more CPUs available, the plugin can do more work in parallel, and thus
@ -179,8 +176,7 @@ The following settings are available for caching:
#### <!-- md:setting config.cache -->
<!-- md:sponsors -->
<!-- md:version insiders-4.30.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default `true` -->
Use this setting to instruct the plugin to bypass the cache, in order to
@ -198,8 +194,7 @@ plugins:
#### <!-- md:setting config.cache_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.30.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default `.cache/plugin/privacy` -->
It is normally not necessary to specify this setting, except for when you want
@ -218,6 +213,84 @@ with each other.
[multiple instances]: index.md#multiple-instances
### Logging
The following settings are available for logging:
---
#### <!-- md:setting config.log -->
<!-- md:sponsors -->
<!-- md:version insiders-4.50.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should display log messages when
building your site. While not being recommended, you can disable logging with:
``` yaml
plugins:
- privacy:
log: false
```
---
#### <!-- md:setting config.log_level -->
<!-- md:sponsors -->
<!-- md:version insiders-4.50.0 -->
<!-- md:default `info` -->
Use this setting to control the log level that the plugin should employ when
encountering errors, which requires that the [`log`][config.log] setting is
enabled. The following log levels are available:
=== "`error`"
``` yaml
plugins:
- privacy:
log_level: error
```
Only errors are reported.
=== "`warn`"
``` yaml
plugins:
- privacy:
log_level: warn
```
Errors and warnings are reported, terminating the build in
[`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot
be created due to a lack of permissions on Windows systems (#6550).
=== "`info`"
``` yaml
plugins:
- privacy:
log_level: info
```
Errors, warnings and informational messages are reported, including which
assets were successfully downloaded by the plugin.
=== "`debug`"
``` yaml
plugins:
- privacy:
log_level: debug
```
All messages are reported, including debug messages, if and only if MkDocs
was started with the `--verbose` flag. Note that this will print a lot of
messages and is only useful for debugging.
### External assets
The following settings are available for external assets:
@ -226,8 +299,7 @@ The following settings are available for external assets:
#### <!-- md:setting config.assets -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should download external
@ -246,8 +318,7 @@ plugins:
#### <!-- md:setting config.assets_fetch -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should downloads or only report
@ -265,8 +336,7 @@ plugins:
#### <!-- md:setting config.assets_fetch_dir -->
<!-- md:sponsors -->
<!-- md:version insiders-4.37.0 -->
<!-- md:version 9.5.0 -->
<!-- md:default `assets/external` -->
It is normally not necessary to specify this setting, except for when you want

82
docs/plugins/projects.md
View File

@ -10,6 +10,13 @@ distinct projects, build them concurrently and preview them together as one.
This is particularly useful when creating a multi-language project, but can also
be used to split very large projects into smaller parts.
---
<!-- md:sponsors --> __Sponsors only__ – this plugin is currently reserved to
[our awesome sponsors].
[our awesome sponsors]: ../insiders/index.md
## Objective
### How it works
@ -176,6 +183,81 @@ plugins:
cache_dir: my/custom/dir
```
### Logging
The following settings are available for logging:
---
#### <!-- md:setting config.log -->
<!-- md:sponsors -->
<!-- md:version insiders-4.47.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should display log messages from
projects when building your site. While not being recommended, you can disable
logging with:
``` yaml
plugins:
- projects:
log: false
```
---
#### <!-- md:setting config.log_level -->
<!-- md:sponsors -->
<!-- md:version insiders-4.47.0 -->
<!-- md:default `info` -->
Use this setting to control the log level that the plugin should employ when
encountering errors, which requires that the [`log`][config.log] setting is
enabled. The following log levels are available:
=== "`error`"
``` yaml
plugins:
- projects:
log_level: error
```
Only errors are reported.
=== "`warn`"
``` yaml
plugins:
- projects:
log_level: warn
```
Errors and warnings are reported, terminating the build in
[`strict`][mkdocs.strict] mode.
=== "`info`"
``` yaml
plugins:
- projects:
log_level: info
```
Errors, warnings and informational messages are reported.
=== "`debug`"
``` yaml
plugins:
- projects:
log_level: debug
```
All messages are reported, including debug messages.
### Projects
The following settings are available for projects:

1
docs/plugins/social.md
View File

@ -277,7 +277,6 @@ enabled. The following log levels are available:
Errors are only reported when using the `--verbose` flag.
### Social cards
The following settings are available for social card generation:

780
docs/plugins/tags.md
View File

@ -112,10 +112,9 @@ The following settings are available for tags:
<!-- md:version 9.2.9 -->
<!-- md:default `true` -->
Use this setting to enable or disable handling of tags. Currently, the plugin's
sole purpose is to process tags, so it's equivalent to the [`enabled`]
[config.enabled] setting, but in the future, other features might be added.
If you want to disable handling of tags, use:
Use this setting to enable or disable rendering of tags. The plugin still
extracts tags from all pages, e.g., for [exporting tags] without rendering them.
Rendering can be disabled with:
``` yaml
plugins:
@ -123,6 +122,11 @@ plugins:
tags: false
```
This setting is automatically disabled if [`export_only`][config.export_only]
is enabled.
[exporting tags]: #export
---
#### <!-- md:setting config.tags_file -->
@ -130,6 +134,13 @@ plugins:
<!-- md:version 8.2.0 -->
<!-- md:default none -->
!!! info "This setting is not needed in [Insiders]"
Insiders ships a __ground up rewrite of the tags plugin__ which is infinitely
more powerful than the current version in the community edition. It allows
for an arbitrary number of tags indexes (listings), [scoped listings],
[shadow tags], [nested tags], and much more.
Use this setting to specify the location of the tags index, which is the page
used to render a list of all tags and their associated pages. If this setting is
specified, tags become clickable, pointing to the corresponding section in the
@ -147,28 +158,10 @@ if you want to have a tags index.
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
---
#### <!-- md:setting config.tags_extra_files -->
<!-- md:sponsors -->
<!-- md:version insiders-4.20.0 -->
<!-- md:default none -->
Use this setting to specify the locations of additional tags indexes, which are
pages that render a subset of the tags index, in order to provide scoped tags
indexes for specific sections:
``` yaml
plugins:
- tags:
tags_extra_files:
extra-1.md: [tag-id-1, tag-id-2, ...]
extra-2.md: [tag-id-3, tag-id-4, ...]
...
```
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
[Insiders]: ../insiders/index.md
[scoped listings]: ../setup/setting-up-tags.md#scoped-listings
[shadow tags]: ../setup/setting-up-tags.md#shadow-tags
[nested tags]: ../setup/setting-up-tags.md#nested-tags
---
@ -176,35 +169,24 @@ The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
<!-- md:sponsors -->
<!-- md:version insiders-4.25.0 -->
<!-- md:default [`toc.slugify`][toc.slugify] -->
<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
Use this setting to change the function to use for generating URL-compatible
slugs from tags. [Python Markdown Extensions] comes with a Unicode-aware
[`slugify`][pymdownx.slugs.slugify] function:
Use this setting to change the function for generating URL-compatible slugs
from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
from [Python Markdown Extensions] is used as follows:
=== "Unicode"
``` yaml
plugins:
- blog:
post_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
kwds:
case: lower
```
The default configuration is Unicode-aware and should produce good slugs for all
languages. Of course, you can also provide a custom slugification function for
more granular control.
=== "Unicode, case-sensitive"
``` yaml
plugins:
- tags:
tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
```
When your project features non-European languages, it's advisable to use this
configuration. Of course, you can also provide a custom slugification function
for more granular control.
[toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
[pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
@ -228,29 +210,89 @@ plugins:
---
#### <!-- md:setting config.tags_compare -->
#### <!-- md:setting config.tags_slugify_format -->
<!-- md:sponsors -->
<!-- md:version insiders-4.26.2 -->
<!-- md:default none -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `tag:{slug}` -->
Use this setting to specify a custom function for comparing tags. By default,
tag comparison is case-sensitive, but you can use the `casefold` function
for case-insensitive comparison:
Use this setting to change the format string that is used when generating tag
slugs. It is a good idea to prefix tag slugs with a string that makes them
unique, the default being:
``` yaml
plugins:
- tags:
tags_compare: !!python/name:material.plugins.tags.casefold
tags_slugify_format: "tag:{slug}"
```
You can also define your own comparison function, which must return a string
representing the tag, that is used for sorting, and reference it in
[`tags_compare`][config.tags_compare].
The following placeholders are available:
- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]
---
#### <!-- md:setting config.tags_compare_reverse -->
#### <!-- md:setting config.tags_hierarchy -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `false` -->
<!-- md:flag experimental -->
Use this setting to enable support for tag hierarchies (nested tags, e.g.,
`foo/bar`). If you intend to create hierarchical listings of tags, you can
enable this setting in `mkdocs.yml` with:
``` yaml
plugins:
- tags:
tags_hierarchy: true
```
---
#### <!-- md:setting config.tags_hierarchy_separator -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `/` -->
<!-- md:flag experimental -->
Use this setting to change the separator that is used when creating tag
hierarchies. By default, tags are separated by a forward slash `/`, but you
can change this to any string, e.g., `.`:
``` yaml
plugins:
- tags:
tags_hierarchy_separator: .
```
---
#### <!-- md:setting config.tags_sort_by -->
<!-- md:sponsors -->
<!-- md:version insiders-4.26.2 -->
<!-- md:default `material.plugins.tags.tag_name` -->
Use this setting to specify a custom function for comparing tags. By default,
tag comparison is case-sensitive, but you can use `tag_name_casefold` for
case-insensitive comparison:
``` yaml
plugins:
- tags:
tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
```
You can also define your own comparison function, which must return a string
or number representing the tag, that is used for sorting, and reference it in
[`tags_sort_by`][config.tags_sort_by].
---
#### <!-- md:setting config.tags_sort_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.26.2 -->
@ -263,57 +305,43 @@ ordering as follows:
``` yaml
plugins:
- tags:
tags_compare_reverse: true
tags_sort_reverse: true
```
---
#### <!-- md:setting config.tags_pages_compare -->
#### <!-- md:setting config.tags_name_property -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default none -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default [`tags`][meta.tags] -->
Use this setting to specify a custom function for comparing pages. By default,
pages occur in order of appearance, but you can sort them by using the following
configuration:
=== "Sort by page title"
``` yaml
plugins:
- tags:
tags_pages_compare: !!python/name:material.plugins.tags.page_title
```
=== "Sort by page URL"
``` yaml
plugins:
- tags:
tags_pages_compare: !!python/name:material.plugins.tags.page_url
```
You can also define your own comparison function, which must return a string
representing the page, that is used for sorting, and reference it in
[`tags_pages_compare`][config.tags_pages_compare].
---
#### <!-- md:setting config.tags_pages_compare_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default `false` -->
Use this setting to reverse the order in which pages are sorted when comparing
them. By default, pages are sorted in ascending order, but you can reverse
ordering as follows:
Use this setting to change the name of the front matter property that is used by
the plugin. It is normally not necessary to change this setting, but if you want
to change it, you can use:
``` yaml
plugins:
- tags:
tags_pages_compare_reverse: true
tags_name_property: tags
```
---
#### <!-- md:setting config.tags_name_variable -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `tags` -->
Use this setting to change the name of the template variable that is used by
the plugin. It is normally not necessary to change this setting, but if you want
to change it, you can use:
``` yaml
plugins:
- tags:
tags_name_variable: tags
```
---
@ -341,6 +369,368 @@ The plugin stops the build if a page references a tag that is not part of
this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
metadata property.
### Listings
The following settings are available for listings:
---
#### <!-- md:setting config.listings -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable listings. It is normally not necessary to
change this setting, as listings are created entirely by inline comments, but
you can disable them if necessary with:
``` yaml
plugins:
- tags:
listings: false
```
This setting is automatically disabled if [`export_only`][config.export_only]
is enabled.
[exporting tags]: #export
---
#### <!-- md:setting config.listings_map -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default none -->
Use this define listing configurations that you can then reference in listings
with a custom identifier. Sharing configurations is a good idea, especially
when you have many tag listings:
``` yaml
plugins:
- tags:
listings_map:
custom-id:
scope: true
exclude: Internal
```
Then, just reference the listing identifier:
``` html
<!-- material/tags custom-id -->
```
See the [listings section] for a list of all available settings.
[listings section]: #listing_configuration
---
#### <!-- md:setting config.listings_sort_by -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default `material.plugins.tags.item_title` -->
Use this setting to specify a custom function for comparing listing items. By
default, items are ordered by their titles, but you can change the sorting
criterion with the following configuration:
=== "Sort by item title"
``` yaml
plugins:
- tags:
listings_sort_by: !!python/name:material.plugins.tags.item_title
```
=== "Sort by item URL"
``` yaml
plugins:
- tags:
listings_sort_by: !!python/name:material.plugins.tags.item_url
```
You can also define your own comparison function, which must return a string
or number representing the item, that is used for sorting, and reference it in
[`listings_sort_by`][config.listings_sort_by].
---
#### <!-- md:setting config.listings_sort_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.39.0 -->
<!-- md:default `false` -->
Use this setting to reverse the order in which items are sorted when comparing
them. By default, items are sorted in ascending order, but you can reverse
ordering as follows:
``` yaml
plugins:
- tags:
listings_sort_reverse: true
```
---
#### <!-- md:setting config.listings_tags_sort_by -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `material.plugins.tags.tag_name` -->
Use this setting to specify a custom function for comparing tags in listings. By
default, tag comparison is case-sensitive, but you can use `tag_name_casefold`
for case-insensitivity:
``` yaml
plugins:
- tags:
tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
```
You can also define your own comparison function, which must return a string
or number representing the tag, that is used for sorting, and reference it in
[`tags_sort_by`][config.tags_sort_by].
---
#### <!-- md:setting config.listings_tags_sort_reverse -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `false` -->
Use this setting to reverse the order in which tags are sorted when comparing
them. By default, tags are sorted in ascending order, but you can reverse
ordering as follows:
``` yaml
plugins:
- tags:
tags_sort_reverse: true
```
---
#### <!-- md:setting config.listings_directive -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `material/tags` -->
Use this setting to change the name of the directive the plugin will look for
when processing pages. If you want to use a shorter directive than
`material/tags`, you could use:
``` yaml
plugins:
- tags:
listings_directive: $tags
```
Using this setting, listings must now be referenced as such:
``` html
<!-- $tags { include: [foo, bar] } -->
```
---
#### <!-- md:setting config.listings_toc -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `true` -->
Use this setting to enable or disable tags showing up in the table of contents.
If you don't want tags to show up in the table of contents, you can disable this
behavior with:
``` yaml
plugins:
- blog:
listings_toc: false
```
### Shadow tags
The following settings are available for shadow tags:
---
#### <!-- md:setting config.shadow -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `false` -->
Use this setting to specify whether the plugin should include shadow tags on
pages and in listings when [building your project], which might be useful for
deploy previews:
=== "Show shadow tags"
``` yaml
plugins:
- tags:
shadow: true
```
=== "Hide shadow tags"
``` yaml
plugins:
- tags:
shadow: false
```
---
#### <!-- md:setting config.shadow_on_serve -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin should include shadow tags on
pages and in listings when [previewing your site]. If you don't wish to include
them when previewing, use:
``` yaml
plugins:
- tags:
shadow_on_serve: false
```
[previewing your site]: ../creating-your-site.md#previewing-as-you-write
---
#### <!-- md:setting config.shadow_tags -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default none -->
The plugin allows to specify a predefined list of shadow tags which can be
included and excluded from builds by using the [`shadow`][config.shadow]
setting. Shadow tags must be specified as a list:
``` yaml
plugins:
- tags:
shadow_tags:
- Draft
- Internal
```
---
#### <!-- md:setting config.shadow_tags_prefix -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default none -->
Use this setting to specify a string that is checked as a prefix for each tag.
If the tag starts with this string, the tag is marked as a shadow tag. A common
practice is to use `_` as a prefix:
``` yaml
plugins:
- tags:
shadow_tags_prefix: _
```
---
#### <!-- md:setting config.shadow_tags_suffix -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default none -->
Use this setting to specify a string that is checked as a suffix for each tag.
If the tag ends with this string, the tag is marked as a shadow tag. One option
can be to use `Internal` as a suffix:
``` yaml
plugins:
- tags:
shadow_tags_suffix: Internal
```
### Export
The following settings are available for exporting:
---
#### <!-- md:setting config.export -->
<!-- md:sponsors -->
<!-- md:version insiders-4.49.0 -->
<!-- md:default `true` -->
Use this setting to control whether the plugin creates a `tags.json` file
inside your [`site` directory][mkdocs.site_dir], which can then be consumed by
other plugins and projects:
``` yaml
plugins:
- tags:
export: true
```
---
#### <!-- md:setting config.export_file -->
<!-- md:sponsors -->
<!-- md:version insiders-4.49.0 -->
<!-- md:default `tags.json` -->
Use this setting to change the path of the file where the exported tags are
stored. It's normally not necessary to change this setting, but if you need to,
use:
``` yaml
plugins:
- tags:
export_file: tags.json
```
The provided path is resolved from the [`site` directory][mkdocs.site_dir].
---
#### <!-- md:setting config.export_only -->
<!-- md:sponsors -->
<!-- md:version insiders-4.49.0 -->
<!-- md:default `false` -->
This setting is solely provided for convenience to disable the rendering of tags
and listings with a single setting (e.g. by using an environment variable),
while keeping the export functionality:
``` yaml
plugins:
- tags:
export_only: true
```
This will automatically disable the [`tags`][config.tags] and
[`listings`][config.listings] settings.
## Usage
### Metadata
@ -374,3 +764,189 @@ tags:
If you want to prevent accidental typos when assigning tags to pages, you can
set a predefined list of allowed tags in `mkdocs.yml` by using the
[`tags_allowed`][config.tags_allowed] setting.
### Listing configuration
The listings configuration controls which tags are included in or excluded from
a listing and whether a listing only includes pages in the current scope.
Furthermore, listings can override some values from the global configuration.
The following settings are available:
---
#### <!-- md:setting listing.scope -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default `false` -->
This setting specifies whether the listing should only consider pages that are
within the current subsection of the documentation of the page the listing is
embedded in:
=== "Inline usage"
``` html
<!-- material/tags { scope: true } -->
```
=== "Usage in `mkdocs.yml`"
``` yaml
plugins:
- tags:
listings_map:
custom-id:
scope: false
```
Then, just reference the listing identifier:
``` html
<!-- material/tags custom-id -->
```
---
#### <!-- md:setting listing.shadow -->
<!-- md:sponsors -->
<!-- md:version insiders-4.49.0 -->
<!-- md:default computed -->
This setting specifies whether the listing should include shadow tags, which
allows to override the global [`shadow`][config.shadow] setting on a per-listing
basis:
=== "Inline usage"
``` html
<!-- material/tags { shadow: true } -->
```
=== "Usage in `mkdocs.yml`"
``` yaml
plugins:
- tags:
listings_map:
custom-id:
shadow: true
```
Then, just reference the listing identifier:
``` html
<!-- material/tags custom-id -->
```
---
#### <!-- md:setting listing.toc -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default [`listings_toc`][config.listings_toc] -->
This setting specifies whether the listing should render tags inside the table
of contents, allowing to override the global [`listings_toc`][config.listings_toc]
setting on a per-listing basis:
=== "Inline usage"
``` html
<!-- material/tags { toc: true } -->
```
=== "Usage in `mkdocs.yml`"
``` yaml
plugins:
- tags:
listings_map:
custom-id:
toc: true
```
Then, just reference the listing identifier:
``` html
<!-- material/tags custom-id -->
```
---
#### <!-- md:setting listing.include -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default none -->
Use this setting to specify which tags should be included in the listing. Each
page that features a tag that is part of this setting, is listed under the
respective tag:
=== "Inline usage"
``` html
<!-- material/tags { include: [foo, bar] } -->
```
=== "Usage in `mkdocs.yml`"
``` yaml
plugins:
- tags:
listings_map:
custom-id:
include:
- foo
- bar
```
Then, just reference the listing identifier:
``` html
<!-- material/tags custom-id -->
```
If this setting is left empty, all tags and pages are included.
---
#### <!-- md:setting listing.exclude -->
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:default none -->
Use this setting to specify which tags should be excluded from the listing. Each
page that features a tag that is part of this setting, is excluded from the
listing entirely:
=== "Inline usage"
``` html
<!-- material/tags { exclude: [foo, bar] } -->
```
=== "Usage in `mkdocs.yml`"
``` yaml
plugins:
- tags:
listings_map:
custom-id:
exclude:
- foo
- bar
```
Then, just reference the listing identifier:
``` html
<!-- material/tags custom-id -->
```
If this setting is left empty, no tags or pages are excluded.

7
docs/plugins/typeset.md
View File

@ -10,6 +10,13 @@ headlines within the navigation and table of contents. This means that code
blocks, icons, emojis and any other inline formatting can be rendered exactly
as defined in the page's content.
---
<!-- md:sponsors --> __Sponsors only__ – this plugin is currently reserved to
[our awesome sponsors].
[our awesome sponsors]: ../insiders/index.md
## Objective
### How it works

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

@ -35,6 +35,10 @@ contents:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v4
with:
python-version: 3.x
@ -90,6 +94,10 @@ contents:
if: github.event.repository.fork == false
steps:
- uses: actions/checkout@v4
- name: Configure Git Credentials
run: |
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- uses: actions/setup-python@v4
with:
python-version: 3.x
@ -210,6 +218,7 @@ other providers:
- [:simple-azuredevops: Azure][Azure]
- [:simple-cloudflarepages: Cloudflare Pages][Cloudflare Pages]
- [:simple-digitalocean: DigitalOcean][DigitalOcean]
- [:material-airballoon-outline: Fly.io][Flyio]
- [:simple-netlify: Netlify][Netlify]
- [:simple-vercel: Vercel][Vercel]
- [:simple-codeberg: Codeberg Pages][Codeberg Pages
@ -223,6 +232,7 @@ other providers:
[Azure]: https://bawmedical.co.uk/t/publishing-a-material-for-mkdocs-site-to-azure-with-automatic-branch-pr-preview-deployments/763
[Cloudflare Pages]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-cloudflare/
[DigitalOcean]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-digitalocean-app-platform/
[Flyio]: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/
[Netlify]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-netlify/
[Vercel]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-vercel/
[Codeberg Pages]: https://andre601.ch/blog/2023/11-05-using-codeberg-pages/

13
docs/reference/content-tabs.md
View File

@ -32,13 +32,12 @@ See additional configuration options:
### Anchor links
<!-- md:sponsors -->
<!-- md:version insiders-4.17.0 -->
<!-- md:version 9.5.0 -->
<!-- md:flag experimental -->
In order to link to content tabs and share them more easily, [Insiders] adds
an anchor link to each content tab automatically, which you can copy via right
click or open in a new tab:
In order to link to content tabs and share them more easily, an anchor link is
automatically added to each content tab, which you can copy via right click or
open in a new tab:
=== "Open me in a new tab ..."
@ -66,8 +65,8 @@ or to the [publishing guide for Insiders][tab_2].
Fore more information, please [see the extension guide][slugification].
[tab_1]: #-or-even-me
[tab_2]: ../publishing-your-site.md#insiders
[tab_1]: #anchor-links--or-even-me
[tab_2]: ../publishing-your-site.md#with-github-actions-insiders
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
[slugification]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.tabbed.slugify

22
docs/reference/diagrams.md
View File

@ -9,7 +9,7 @@ different technical components, and are a great addition to project
documentation. Material for MkDocs integrates with [Mermaid.js], a very
popular and flexible solution for drawing diagrams.
[Mermaid.js]: https://mermaid-js.github.io/mermaid/
[Mermaid.js]: https://mermaid.js.org/
## Configuration
@ -78,7 +78,7 @@ graph LR
</div>
[Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
[Flowcharts]: https://mermaid.js.org/syntax/flowchart.html
### Using sequence diagrams
@ -118,7 +118,7 @@ sequenceDiagram
</div>
[Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
[Sequence diagrams]: https://mermaid.js.org/syntax/sequenceDiagram.html
### Using state diagrams
@ -160,7 +160,7 @@ stateDiagram-v2
</div>
[State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram
[State diagrams]: https://mermaid.js.org/syntax/stateDiagram.html
### Using class diagrams
@ -232,7 +232,7 @@ classDiagram
</div>
[Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram
[Class diagrams]: https://mermaid.js.org/syntax/classDiagram.html
### Using entity-relationship diagrams
@ -268,7 +268,7 @@ erDiagram
</div>
[entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
[entity-relationship diagram]: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
### Other diagram types
@ -278,8 +278,8 @@ Besides the diagram types listed above, [Mermaid.js] provides support for
for MkDocs. Those diagrams should still work as advertised by [Mermaid.js], but
we don't consider them a good choice, mostly as they don't work well on mobile.
[pie charts]: https://mermaid-js.github.io/mermaid/#/pie
[gantt charts]: https://mermaid-js.github.io/mermaid/#/gantt
[user journeys]: https://mermaid-js.github.io/mermaid/#/user-journey
[git graphs]: https://mermaid-js.github.io/mermaid/#/gitgraph
[requirement diagrams]: https://mermaid-js.github.io/mermaid/#/requirementDiagram
[pie charts]: https://mermaid.js.org/syntax/pie.html
[gantt charts]: https://mermaid.js.org/syntax/gantt.html
[user journeys]: https://mermaid.js.org/syntax/userJourney.html
[git graphs]: https://mermaid.js.org/syntax/gitgraph.html
[requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html

6
docs/reference/grids.md
View File

@ -45,8 +45,7 @@ elements in a rectangular shape.
### Using card grids
<!-- md:sponsors -->
<!-- md:version insiders-4.12.0 -->
<!-- md:version 9.5.0 -->
<!-- md:flag experimental -->
Card grids wrap each grid item with a beautiful hover card that levitates on
@ -226,8 +225,7 @@ to the grid.
### Using generic grids
<!-- md:sponsors -->
<!-- md:version insiders-4.12.0 -->
<!-- md:version 9.5.0 -->
<!-- md:flag experimental -->
Generic grids allow for arranging arbitrary block elements in a grid, including

112
docs/reference/math.md
View File

@ -4,10 +4,10 @@ icon: material/alphabet-greek
# Math
[MathJax] and [KaTeX] are two popular libraries for displaying
mathematical content in browsers. Although both libraries offer similar
functionality, they use different syntaxes and have different configuration
options. This documentation site provides information on how to integrate them
[MathJax] and [KaTeX] are two popular libraries for displaying
mathematical content in browsers. Although both libraries offer similar
functionality, they use different syntaxes and have different configuration
options. This documentation site provides information on how to integrate them
with Material for MkDocs easily.
[MathJax]: https://www.mathjax.org/
@ -19,14 +19,14 @@ with Material for MkDocs easily.
## Configuration
The following configuration enables support for rendering block and
The following configuration enables support for rendering block and
inline block equations using [MathJax] and [KaTeX].
### MathJax
[MathJax] is a powerful and flexible library that supports multiple input formats,
such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
HTML, SVG, MathML. To use MathJax within your project, add the following lines
[MathJax] is a powerful and flexible library that supports multiple input formats,
such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
HTML, SVG, MathML. To use MathJax within your project, add the following lines
to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
@ -46,6 +46,9 @@ to your `mkdocs.yml`.
};
document$.subscribe(() => { // (1)!
MathJax.startup.output.clearCache()
MathJax.typesetClear()
MathJax.texReset()
MathJax.typesetPromise()
})
```
@ -72,11 +75,27 @@ See additional configuration options:
[Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
</script>
### KaTeX
[KaTeX] is a lightweight library that focuses on speed and simplicity. It
supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
[KaTeX] is a lightweight library that focuses on speed and simplicity. It
supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
[KaTeX] within your project, add the following lines to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
@ -102,37 +121,16 @@ supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
markdown_extensions:
- pymdownx.arithmatex:
generic: true
extra_javascript:
- javascripts/katex.js
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js # (1)!
- javascripts/katex.js
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
```
1. Alternatively, you can add these JavaScript and CSS files via `script` tags by overriding HTML files.
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};
</script>
## Usage
### Using block syntax
@ -159,44 +157,44 @@ $$
Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
``` latex title="inline syntax"
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
```
<div class="result" markdown>
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
The homomorphism $f$ is injective if and only if its kernel is only the
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
</div>
## Comparing MathJax and KaTeX
When deciding between MathJax and KaTeX, there are several key factors to
When deciding between MathJax and KaTeX, there are several key factors to
consider:
- __Speed__: KaTeX is generally faster than MathJax. If your site requires rendering large
quantities of complex equations quickly, KaTeX may be the better choice.
- __Speed__: KaTeX is generally faster than MathJax. If your site requires
rendering large quantities of complex equations quickly, KaTeX may be the
better choice.
- __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
process a variety of mathematical markup languages (like AsciiMath and MathML).
If you need advanced LaTeX features, MathJax may be more suitable.
- __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
process a variety of mathematical markup languages (like AsciiMath and MathML).
If you need advanced LaTeX features, MathJax may be more suitable.
- __Output Format__: Both libraries support HTML and SVG outputs. However,
MathJax also offers MathML output, which can be essential for accessibility, as
it is readable by screen readers.
- __Output Format__: Both libraries support HTML and SVG outputs. However,
MathJax also offers MathML output, which can be essential for accessibility,
as it is readable by screen readers.
- __Configurability__: MathJax provides a range of configuration options,
allowing for more precise control over its behavior. If you have specific
rendering requirements, MathJax might be a more flexible choice.
- __Configurability__: MathJax provides a range of configuration options,
allowing for more precise control over its behavior. If you have specific
rendering requirements, MathJax might be a more flexible choice.
- __Browser Support__: While both libraries work well in modern browsers,
MathJax has broader compatibility with older browsers. If your audience uses a
variety of browsers, including older ones, MathJax might be a safer option.
- __Browser Support__: While both libraries work well in modern browsers,
MathJax has broader compatibility with older browsers. If your audience uses a
variety of browsers, including older ones, MathJax might be a safer option.
In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
more features and better compatibility at the expense of speed. The choice
In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
more features and better compatibility at the expense of speed. The choice
between the two will largely depend on your specific needs and constraints.

14
docs/reference/tooltips.md
View File

@ -35,8 +35,7 @@ See additional configuration options:
### Improved tooltips
<!-- md:sponsors -->
<!-- md:version insiders-4.15.0 -->
<!-- md:version 9.5.0 -->
<!-- md:flag experimental -->
When improved tooltips are enabled, Material for MkDocs replaces the browser's
@ -156,3 +155,14 @@ pages with the following configuration:
````
[auto-append]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#auto-append-snippets
!!! tip
When using a dedicated file outside of the `docs` folder, add the parent directory to the list
of `watch` folders so that when the glossary file is updated, the project is automatically
reloaded when running `mkdocs serve`.
```` yaml
watch:
- includes
````

6324
docs/schema/assets/fonts.json
View File

File diff suppressed because it is too large Load Diff

391
docs/schema/assets/icons.json
View File

File diff suppressed because it is too large Load Diff

29
docs/schema/extensions.json
View File

@ -4,15 +4,36 @@
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/",
"type": "array",
"items": {
"oneOf": [
"anyOf": [
{
"$ref": "extensions/markdown.json"
"$ref": "#/$defs/external"
},
{
"$ref": "extensions/pymdownx.json"
"$ref": "#/$defs/external-community"
}
]
},
"uniqueItems": true,
"minItems": 1
"minItems": 1,
"$defs": {
"external": {
"description": "External markdown extensions, schema provided by us",
"anyOf": [
{
"$ref": "extensions/markdown.json"
},
{
"$ref": "extensions/pymdownx.json"
}
]
},
"external-community": {
"description": "External markdown extensions, schema provided by our community",
"anyOf": [
{
"$ref": "https://raw.githubusercontent.com/Neoteroi/mkdocs-plugins/main/docs/extensions-schema.json"
}
]
}
}
}

8
docs/schema/extensions/markdown.json
View File

@ -59,6 +59,14 @@
"md_in_html"
]
},
{
"title": "Sane Lists – Python Markdown",
"markdownDescription": "https://python-markdown.github.io/extensions/sane_lists/",
"enum": [
"markdown.extensions.sane_lists",
"sane_lists"
]
},
{
"title": "Tables – Python Markdown",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#tables",

64
docs/schema/extensions/pymdownx.json
View File

@ -27,9 +27,7 @@
{
"title": "Arithmatex – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#arithmatex",
"enum": [
"pymdownx.arithmatex"
]
"const": "pymdownx.arithmatex"
}
]
},
@ -63,9 +61,7 @@
{
"title": "BetterEm – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#betterem",
"enum": [
"pymdownx.betterem"
]
"const": "pymdownx.betterem"
}
]
},
@ -74,9 +70,7 @@
{
"title": "Caret – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#caret-mark-tilde",
"enum": [
"pymdownx.caret"
]
"const": "pymdownx.caret"
},
{
"type": "object",
@ -114,9 +108,7 @@
{
"title": "Critic – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#critic",
"enum": [
"pymdownx.critic"
]
"const": "pymdownx.critic"
},
{
"type": "object",
@ -145,18 +137,14 @@
{
"title": "Details – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#details",
"enum": [
"pymdownx.details"
]
"const": "pymdownx.details"
},
{
"oneOf": [
{
"title": "Emoji – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#emoji",
"enum": [
"pymdownx.emoji"
]
"const": "pymdownx.emoji"
},
{
"type": "object",
@ -208,9 +196,7 @@
{
"title": "Highlight – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight",
"enum": [
"pymdownx.highlight"
]
"const": "pymdownx.highlight"
},
{
"type": "object",
@ -267,18 +253,14 @@
{
"title": "InlineHilite – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#inlinehilite",
"enum": [
"pymdownx.inlinehilite"
]
"const": "pymdownx.inlinehilite"
},
{
"oneOf": [
{
"title": "Keys – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#keys",
"enum": [
"pymdownx.keys"
]
"const": "pymdownx.keys"
},
{
"type": "object",
@ -320,9 +302,7 @@
{
"title": "MagicLink – Python Markdown Extensions",
"markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/",
"enum": [
"pymdownx.magiclink"
]
"const": "pymdownx.magiclink"
},
{
"type": "object",
@ -410,9 +390,7 @@
{
"title": "Mark – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#caret-mark-tilde",
"enum": [
"pymdownx.mark"
]
"const": "pymdownx.mark"
},
{
"type": "object",
@ -440,9 +418,7 @@
{
"title": "SmartSymbols – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#smartsymbols",
"enum": [
"pymdownx.smartsymbols"
]
"const": "pymdownx.smartsymbols"
},
{
"type": "object",
@ -569,9 +545,7 @@
{
"title": "Snippets – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#snippets",
"enum": [
"pymdownx.snippets"
]
"const": "pymdownx.snippets"
}
]
},
@ -580,9 +554,7 @@
{
"title": "SuperFences – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences",
"enum": [
"pymdownx.superfences"
]
"const": "pymdownx.superfences"
},
{
"type": "object",
@ -663,9 +635,7 @@
{
"title": "Tasklist – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist",
"enum": [
"pymdownx.tasklist"
]
"const": "pymdownx.tasklist"
},
{
"type": "object",
@ -697,9 +667,7 @@
{
"title": "Tilde – Python Markdown Extensions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#caret-mark-tilde",
"enum": [
"pymdownx.tilde"
]
"const": "pymdownx.tilde"
},
{
"type": "object",

221
docs/schema/extra.json
View File

@ -13,99 +13,71 @@
"title": "Analytics provider",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"type": "object",
"properties": {
"provider": {
"title": "Analytics provider",
"anyOf": [
{
"title": "Google Analytics",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"enum": [
"google"
]
},
{
"type": "string"
}
]
},
"property": {
"anyOf": [
{
"title": "Google Analytics 4",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"pattern": "^G-\\w{10}$"
},
{
"title": "Universal Analytics",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"pattern": "^UA-\\w{9}-\\w$"
},
{
"title": "Unknown property",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"type": "string"
}
]
},
"feedback": {
"title": "Was this page helpful?",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#was-this-page-helpful",
"type": "object",
"properties": {
"title": {
"title": "Feedback widget title",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#was-this-page-helpful",
"type": "string",
"default": "Was this page helpful?"
},
"ratings": {
"title": "Feedback ratings",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#was-this-page-helpful",
"type": "array",
"items": {
"title": "Feedback rating",
"type": "object",
"properties": {
"icon": {
"$ref": "#/$defs/icon"
},
"name": {
"title": "Feedback rating name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.name",
"type": "string"
},
"data": {
"title": "Feedback rating data",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.data",
"type": "number"
},
"note": {
"title": "Feedback rating data",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.note",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"icon",
"name",
"data",
"note"
]
"allOf": [
{
"if": {
"properties": {
"provider": {
"const": "google"
}
}
},
"additionalProperties": false,
"required": [
"title"
]
"then": {
"properties": {
"provider": {
"title": "Google Analytics",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"const": "google"
},
"property": {
"anyOf": [
{
"title": "Google Analytics 4",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"pattern": "^G-\\w{10}$"
},
{
"title": "Unknown property",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#google-analytics",
"type": "string"
}
]
},
"feedback": {
"$ref": "#/$defs/feedback"
}
},
"required": [
"provider",
"property"
],
"additionalProperties": false
}
},
{
"if": {
"properties": {
"provider": {
"type": "string"
}
}
},
"then": {
"properties": {
"provider": {
"title": "Custom analytics provider",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#custom-site-analytics",
"type": "string"
},
"feedback": {
"$ref": "#/$defs/feedback"
}
},
"required": [
"provider"
]
}
}
},
"additionalProperties": false,
"required": [
"provider",
"property"
],
"defaultSnippets": [
{
@ -213,21 +185,15 @@
"oneOf": [
{
"title": "Button to accept cookies",
"enum": [
"accept"
]
"const": "accept"
},
{
"title": "Button to reject cookies",
"enum": [
"reject"
]
"const": "reject"
},
{
"title": "Button to manage settings",
"enum": [
"manage"
]
"const": "manage"
}
]
},
@ -334,9 +300,7 @@
"provider": {
"title": "Versioning provider",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#versioning",
"enum": [
"mike"
]
"const": "mike"
},
"default": {
"title": "Default version",
@ -406,6 +370,59 @@
"type": "string"
}
]
},
"feedback": {
"title": "Was this page helpful?",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#was-this-page-helpful",
"type": "object",
"properties": {
"title": {
"title": "Feedback widget title",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#was-this-page-helpful",
"type": "string",
"default": "Was this page helpful?"
},
"ratings": {
"title": "Feedback ratings",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#was-this-page-helpful",
"type": "array",
"items": {
"title": "Feedback rating",
"type": "object",
"properties": {
"icon": {
"$ref": "#/$defs/icon"
},
"name": {
"title": "Feedback rating name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.name",
"type": "string"
},
"data": {
"title": "Feedback rating data",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.data",
"type": "number"
},
"note": {
"title": "Feedback rating data",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.note",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"icon",
"name",
"data",
"note"
]
}
}
},
"additionalProperties": false,
"required": [
"title"
]
}
},
"defaultSnippets": [
@ -414,7 +431,7 @@
"body": {
"analytics": {
"provider": "${1:google}",
"property": "${2:UA-XXXXXXXX-X}"
"property": "${2:G-XXXXXXXXXX}"
}
}
}

136
docs/schema/plugins/blog.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
"enum": [
"blog"
]
"const": "blog"
},
{
"type": "object",
@ -28,13 +26,13 @@
"default": "blog"
},
"blog_toc": {
"title": "Blog table of contents",
"title": "Table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_toc",
"type": "boolean",
"default": false
},
"post_dir": {
"title": "Blog posts directory",
"title": "Post directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_dir",
"type": "string",
"default": "\"{blog\\}/posts\""
@ -114,15 +112,11 @@
"oneOf": [
{
"title": "Post excerpts are optional",
"enum": [
"optional"
]
"const": "optional"
},
{
"title": "Post excerpts are required, thus the build will fail",
"enum": [
"required"
]
"const": "required"
}
],
"default": "optional"
@ -215,8 +209,20 @@
}
]
},
"archive_pagination": {
"title": "Pagination for archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_pagination",
"type": "boolean",
"default": true
},
"archive_pagination_per_page": {
"title": "Posts per page for archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_pagination_per_page",
"type": "number",
"default": 10
},
"archive_toc": {
"title": "Archive table of contents",
"title": "Table of contents for archive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_toc",
"type": "boolean",
"default": false
@ -259,8 +265,29 @@
"type": "string",
"default": "\"-\""
},
"categories_sort_by": {
"title": "Sort categories by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_sort_by",
"default": "!!python/name:material.plugins.blog.view_name",
"oneOf": [
{
"type": "string"
},
{
"enum": [
"!!python/name:material.plugins.blog.view_name",
"!!python/name:material.plugins.blog.view_post_count"
]
}
]
},
"categories_sort_reverse": {
"title": "Soft categories in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_sort_reverse",
"default": false
},
"categories_allowed": {
"title": "Categories allowed",
"title": "Allowed categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_allowed",
"type": "array",
"items": {
@ -269,12 +296,81 @@
"uniqueItems": true,
"default": []
},
"categories_pagination": {
"title": "Pagination for categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_pagination",
"type": "boolean",
"default": true
},
"categories_pagination_per_page": {
"title": "Posts per page for categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_pagination_per_page",
"type": "number",
"default": 10
},
"categories_toc": {
"title": "Categories table of contents",
"title": "Table of contents for categories",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_toc",
"type": "boolean",
"default": false
},
"authors": {
"title": "Author info",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors",
"type": "boolean",
"default": true
},
"authors_file": {
"title": "Authors file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_file",
"type": "string",
"default": "\"{blog}/.authors.yml\""
},
"authors_profiles": {
"title": "Author profiles",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_profiles",
"type": "boolean",
"default": false
},
"authors_profiles_name": {
"title": "Authors profiles name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_profiles_name",
"type": "string",
"default": "Authors"
},
"authors_profiles_url_format": {
"title": "Format string for author profile URLs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_profiles_url_format",
"oneOf": [
{
"enum": [
"\"author/{slug}\"",
"\"{slug}\""
]
},
{
"type": "string"
}
]
},
"authors_profiles_pagination": {
"title": "Pagination for author profiles",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_profiles_pagination",
"type": "boolean",
"default": true
},
"authors_profiles_pagination_per_page": {
"title": "Posts per page for author profiles",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_profiles_pagination_per_page",
"type": "number",
"default": 10
},
"authors_profiles_toc": {
"title": "Table of contents for author profiles",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_profiles_toc",
"type": "boolean",
"default": false
},
"pagination": {
"title": "Pagination",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination",
@ -325,18 +421,6 @@
"type": "boolean",
"default": false
},
"authors": {
"title": "Author info",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors",
"type": "boolean",
"default": true
},
"authors_file": {
"title": "Authors file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_file",
"type": "string",
"default": "\"{blog\\}/.authors.yml\""
},
"draft": {
"title": "Render posts marked as drafts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft",

4
docs/schema/plugins/external/gen-files.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://github.com/oprypin/mkdocs-gen-files",
"enum": [
"git-authors"
]
"const": "git-authors"
},
{
"type": "object",

4
docs/schema/plugins/external/git-authors.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://timvink.github.io/mkdocs-git-authors-plugin/",
"enum": [
"git-authors"
]
"const": "git-authors"
},
{
"type": "object",

4
docs/schema/plugins/external/git-committers.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2",
"enum": [
"git-committers"
]
"const": "git-committers"
},
{
"type": "object",

4
docs/schema/plugins/external/git-revision-date.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin",
"enum": [
"git-revision-date"
]
"const": "git-revision-date"
},
{
"type": "object",

4
docs/schema/plugins/external/literate-nav.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://github.com/oprypin/mkdocs-literate-nav",
"enum": [
"literate-nav"
]
"const": "literate-nav"
},
{
"type": "object",

4
docs/schema/plugins/external/macros.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://github.com/fralau/mkdocs_macros_plugin",
"enum": [
"macros"
]
"const": "macros"
},
{
"type": "object",

4
docs/schema/plugins/external/section-index.json vendored
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://github.com/oprypin/mkdocs-section-index",
"enum": [
"section-index"
]
"const": "section-index"
},
{
"type": "object",

4
docs/schema/plugins/info.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
"enum": [
"info"
]
"const": "info"
},
{
"type": "object",

4
docs/schema/plugins/meta.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
"enum": [
"meta"
]
"const": "meta"
},
{
"type": "object",

4
docs/schema/plugins/offline.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
"enum": [
"offline"
]
"const": "offline"
},
{
"type": "object",

4
docs/schema/plugins/optimize.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
"enum": [
"optimize"
]
"const": "optimize"
},
{
"type": "object",

21
docs/schema/plugins/privacy.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
"enum": [
"privacy"
]
"const": "privacy"
},
{
"type": "object",
@ -38,6 +36,23 @@
"type": "string",
"default": ".cache/plugins/privacy"
},
"log": {
"title": "Enable logging",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.log",
"type": "boolean",
"default": true
},
"log_level": {
"title": "Log level",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.log_level",
"enum": [
"error",
"warn",
"info",
"debug"
],
"default": "info"
},
"assets": {
"title": "Process external assets",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets",

21
docs/schema/plugins/projects.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
"enum": [
"projects"
]
"const": "projects"
},
{
"type": "object",
@ -38,6 +36,23 @@
"type": "string",
"default": ".cache/plugins/projects"
},
"log": {
"title": "Enable logging",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.log",
"type": "boolean",
"default": true
},
"log_level": {
"title": "Log level",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.log_level",
"enum": [
"error",
"warn",
"info",
"debug"
],
"default": "info"
},
"projects": {
"title": "Enable projects",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects",

80
docs/schema/plugins/search.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
"enum": [
"search"
]
"const": "search"
},
{
"type": "object",
@ -73,117 +71,79 @@
"oneOf": [
{
"title": "Site search language: Arabic",
"enum": [
"ar"
]
"const": "ar"
},
{
"title": "Site search language: Danish",
"enum": [
"da"
]
"const": "da"
},
{
"title": "Site search language: German",
"enum": [
"de"
]
"const": "de"
},
{
"title": "Site search language: Dutch",
"enum": [
"du"
]
"const": "du"
},
{
"title": "Site search language: English",
"enum": [
"en"
]
"const": "en"
},
{
"title": "Site search language: Spanish",
"enum": [
"es"
]
"const": "es"
},
{
"title": "Site search language: Finnish",
"enum": [
"fi"
]
"const": "fi"
},
{
"title": "Site search language: French",
"enum": [
"fr"
]
"const": "fr"
},
{
"title": "Site search language: Hungarian",
"enum": [
"hu"
]
"const": "hu"
},
{
"title": "Site search language: Italian",
"enum": [
"it"
]
"const": "it"
},
{
"title": "Site search language: Japanese",
"enum": [
"ja"
]
"const": "ja"
},
{
"title": "Site search language: Norwegian",
"enum": [
"no"
]
"const": "no"
},
{
"title": "Site search language: Portuguese",
"enum": [
"pt"
]
"const": "pt"
},
{
"title": "Site search language: Romanian",
"enum": [
"ro"
]
"const": "ro"
},
{
"title": "Site search language: Russian",
"enum": [
"ru"
]
"const": "ru"
},
{
"title": "Site search language: Swedish",
"enum": [
"sv"
]
"const": "sv"
},
{
"title": "Site search language: Thai",
"enum": [
"th"
]
"const": "th"
},
{
"title": "Site search language: Turkish",
"enum": [
"tr"
]
"const": "tr"
},
{
"title": "Site search language: Vietnamese",
"enum": [
"vi"
]
"const": "vi"
}
]
}

20
docs/schema/plugins/social.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
"enum": [
"social"
]
"const": "social"
},
{
"type": "object",
@ -44,6 +42,22 @@
"type": "boolean",
"default": true
},
"log": {
"title": "Enable logging",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.log",
"type": "boolean",
"default": true
},
"log_level": {
"title": "Log level",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.log_level",
"enum": [
"warn",
"info",
"ignore"
],
"default": "warn"
},
"cards_dir": {
"title": "Social cards directory",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir",

194
docs/schema/plugins/tags.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
"enum": [
"tags"
]
"const": "tags"
},
{
"type": "object",
@ -21,27 +19,18 @@
"type": "boolean",
"default": true
},
"tags": {
"title": "Rendering of tags",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags",
"type": "boolean",
"default": true
},
"tags_file": {
"title": "Markdown file to render tags index",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_file",
"pattern": "\\.md$",
"default": "tags.md"
},
"tags_extra_files": {
"title": "Markdown files to render additional tags indexes",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_extra_files",
"type": "object",
"patternProperties": {
"\\.md$": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
}
},
"additionalProperties": false
},
"tags_slugify": {
"title": "Tags slugify function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify",
@ -51,27 +40,41 @@
"title": "Tags slugify separator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify_separator",
"type": "string",
"default": "\"-\""
"default": "-"
},
"tags_compare": {
"tags_slugify_format": {
"title": "Format string for tags slugifier",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify_format",
"type": "string",
"default": "\"tag:{slug}\""
},
"tags_hierarchy": {
"title": "Rendering of tags",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags",
"type": "boolean",
"default": true
},
"tags_sort_by": {
"title": "Sort tags by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_sort_by",
"default": "!!python/name:material.plugins.tags.casefold"
},
"tags_compare_reverse": {
"tags_sort_reverse": {
"title": "Soft tags in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare_reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_sort_reverse",
"default": false
},
"tags_pages_compare": {
"title": "Sort tags pages by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare",
"default": "!!python/name:material.plugins.tags.page_title"
"tags_name_property": {
"title": "Tags front matter property",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_name_property",
"type": "string",
"default": "tags"
},
"tags_pages_compare_reverse": {
"title": "Soft tags pages in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare_reverse",
"default": false
"tags_name_variable": {
"title": "Tags Jinja variable name",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_name_variable",
"type": "string",
"default": "tags"
},
"tags_allowed": {
"title": "Tags allowed",
@ -82,6 +85,135 @@
},
"uniqueItems": true,
"default": []
},
"listings": {
"title": "Rendering of listings",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings",
"type": "boolean",
"default": true
},
"listings_map": {
"title": "Map of listing configurations",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_map",
"type": "object",
"patternProperties": {
".*": {
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing-configuration",
"type": "object",
"properties": {
"scope": {
"title": "Scoped listing",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing.scope",
"default": false
},
"shadow": {
"title": "Render shadow tags",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing.shadow",
"default": true
},
"include": {
"title": "Tag inclusion list",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing.include",
"type": "array",
"uniqueItems": true
},
"exclude": {
"title": "Tag exclusion list",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing.exclude",
"type": "array",
"uniqueItems": true
},
"toc": {
"title": "Render tags in table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#listing.toc",
"default": true
}
}
}
},
"additionalProperties": false
},
"listings_sort_by": {
"title": "Sort listing items by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_sort_by",
"default": "!!python/name:material.plugins.tags.casefold"
},
"listings_sort_reverse": {
"title": "Soft listing items in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_sort_reverse",
"default": false
},
"listings_tags_sort_by": {
"title": "Sort listing tags by this function",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_tags_sort_by",
"default": "!!python/name:material.plugins.tags.casefold"
},
"listings_tags_sort_reverse": {
"title": "Soft listing tags in reverse",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_tags_sort_reverse",
"default": false
},
"listings_directive": {
"title": "Listings directive",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_directive",
"type": "string",
"default": "material/tags"
},
"listings_toc": {
"title": "Render tags in table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.listings_toc",
"default": true
},
"shadow": {
"title": "Rendering shadow tags on build",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.shadow",
"type": "boolean",
"default": false
},
"shadow_on_serve": {
"title": "Rendering shadow tags on serve",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.shadow_on_serve",
"type": "boolean",
"default": true
},
"shadow_tags": {
"title": "Shadow tags",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.shadow_tags",
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true,
"default": []
},
"shadow_tags_prefix": {
"title": "Shadow tags prefix",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.shadow_tags_prefix",
"type": "string",
"default": "_"
},
"shadow_tags_suffix": {
"title": "Shadow tags suffix",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.shadow_tags_suffix",
"type": "string"
},
"export": {
"title": "Tags export",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.export",
"type": "boolean",
"default": true
},
"export_file": {
"title": "Tags file",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.export_file",
"type": "boolean",
"default": "tags.json"
},
"export_only": {
"title": "Only export tags, don't render them",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.export_only",
"type": "boolean",
"default": true
}
},
"additionalProperties": false

4
docs/schema/plugins/typeset.json
View File

@ -4,9 +4,7 @@
"oneOf": [
{
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
"enum": [
"typeset"
]
"const": "typeset"
},
{
"type": "object",

361
docs/schema/theme.json
View File

@ -9,9 +9,7 @@
"markdownDescription": "https://www.mkdocs.org/user-guide/configuration/#name",
"oneOf": [
{
"enum": [
"material"
]
"const": "material"
},
{
"type": "null"
@ -48,375 +46,251 @@
{
"title": "Site language: Custom",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#custom-translations",
"enum": [
"custom"
]
"const": "custom"
},
{
"title": "Site language: Afrikaans",
"enum": [
"af"
]
"const": "af"
},
{
"title": "Site language: Arabic",
"enum": [
"ar"
]
"const": "ar"
},
{
"title": "Site language: Bulgarian",
"enum": [
"bg"
]
"const": "bg"
},
{
"title": "Site language: Bengali (Bangla)",
"enum": [
"bn"
]
"const": "bn"
},
{
"title": "Site language: Catalan",
"enum": [
"ca"
]
"const": "ca"
},
{
"title": "Site language: Czech",
"enum": [
"cs"
]
"const": "cs"
},
{
"title": "Site language: Danish",
"enum": [
"da"
]
"const": "da"
},
{
"title": "Site language: German",
"enum": [
"de"
]
"const": "de"
},
{
"title": "Site language: Greek",
"enum": [
"el"
]
"const": "el"
},
{
"title": "Site language: English",
"enum": [
"en"
]
"const": "en"
},
{
"title": "Site language: Esperanto",
"enum": [
"eo"
]
"const": "eo"
},
{
"title": "Site language: Spanish",
"enum": [
"es"
]
"const": "es"
},
{
"title": "Site language: Estonian",
"enum": [
"et"
]
"const": "et"
},
{
"title": "Site language: Persian (Farsi)",
"enum": [
"fa"
]
"const": "fa"
},
{
"title": "Site language: Finnish",
"enum": [
"fi"
]
"const": "fi"
},
{
"title": "Site language: French",
"enum": [
"fr"
]
"const": "fr"
},
{
"title": "Site language: Galician",
"enum": [
"gl"
]
"const": "gl"
},
{
"title": "Site language: Hebrew",
"enum": [
"he"
]
"const": "he"
},
{
"title": "Site language: Hindi",
"enum": [
"hi"
]
"const": "hi"
},
{
"title": "Site language: Croatian",
"enum": [
"hr"
]
"const": "hr"
},
{
"title": "Site language: Hungarian",
"enum": [
"hu"
]
"const": "hu"
},
{
"title": "Site language: Armenian",
"enum": [
"hy"
]
"const": "hy"
},
{
"title": "Site language: Indonesian",
"enum": [
"id"
]
"const": "id"
},
{
"title": "Site language: Icelandic",
"enum": [
"is"
]
"const": "is"
},
{
"title": "Site language: Italian",
"enum": [
"it"
]
"const": "it"
},
{
"title": "Site language: Japanese",
"enum": [
"ja"
]
"const": "ja"
},
{
"title": "Site language: Georgian",
"enum": [
"ka"
]
"const": "ka"
},
{
"title": "Site language: Kannada",
"enum": [
"kn"
]
"const": "kn"
},
{
"title": "Site language: Korean",
"enum": [
"ko"
]
"const": "ko"
},
{
"title": "Site language: Lithuanian",
"enum": [
"lt"
]
"const": "lt"
},
{
"title": "Site language: Latvian",
"enum": [
"lv"
]
"const": "lv"
},
{
"title": "Site language: Macedonian",
"enum": [
"mk"
]
"const": "mk"
},
{
"title": "Site language: Mongolian",
"enum": [
"mn"
]
"const": "mn"
},
{
"title": "Site language: Bahasa Malaysia",
"enum": [
"ms"
]
"const": "ms"
},
{
"title": "Site language: Burmese",
"enum": [
"my"
]
"const": "my"
},
{
"title": "Site language: Dutch",
"enum": [
"nl"
]
"const": "nl"
},
{
"title": "Site language: Norwegian (Bokmål)",
"enum": [
"nb"
]
"const": "nb"
},
{
"title": "Site language: Norwegian (Nynorsk)",
"enum": [
"nn"
]
"const": "nn"
},
{
"title": "Site language: Polish",
"enum": [
"pl"
]
"const": "pl"
},
{
"title": "Site language: Portuguese",
"enum": [
"pt"
]
"const": "pt"
},
{
"title": "Site language: Portuguese (Brasilian)",
"enum": [
"pt-BR"
]
"const": "pt-BR"
},
{
"title": "Site language: Romanian",
"enum": [
"ro"
]
"const": "ro"
},
{
"title": "Site language: Russian",
"enum": [
"ru"
]
"const": "ru"
},
{
"title": "Site language: Sanskrit",
"enum": [
"sa"
]
"const": "sa"
},
{
"title": "Site language: Serbo-Croatian",
"enum": [
"sh"
]
"const": "sh"
},
{
"title": "Site language: Sinhalese",
"enum": [
"si"
]
"const": "si"
},
{
"title": "Site language: Slovak",
"enum": [
"sk"
]
"const": "sk"
},
{
"title": "Site language: Slovenian",
"enum": [
"sl"
]
"const": "sl"
},
{
"title": "Site language: Serbian",
"enum": [
"sr"
]
"const": "sr"
},
{
"title": "Site language: Swedish",
"enum": [
"sv"
]
"const": "sv"
},
{
"title": "Site language: Telugu",
"enum": [
"te"
]
"const": "te"
},
{
"title": "Site language: Thai",
"enum": [
"th"
]
"const": "th"
},
{
"title": "Site language: Tagalog",
"enum": [
"tl"
]
"const": "tl"
},
{
"title": "Site language: Turkish",
"enum": [
"tr"
]
"const": "tr"
},
{
"title": "Site language: Ukrainian",
"enum": [
"uk"
]
"const": "uk"
},
{
"title": "Site language: Urdu",
"enum": [
"ur"
]
"const": "ur"
},
{
"title": "Site language: Uzbek",
"enum": [
"uz"
]
"const": "uz"
},
{
"title": "Site language: Vietnamese",
"enum": [
"vi"
]
"const": "vi"
},
{
"title": "Site language: Chinese (Simplified)",
"enum": [
"zh"
]
"const": "zh"
},
{
"title": "Site language: Chinese (Traditional)",
"enum": [
"zh-Hant"
]
"const": "zh-Hant"
},
{
"title": "Site language: Chinese (Taiwanese)",
"enum": [
"zh-TW"
]
"const": "zh-TW"
}
],
"default": "en"
@ -597,191 +471,137 @@
{
"title": "Mark as read",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#mark-as-read",
"enum": [
"announce.dismiss"
]
"const": "announce.dismiss"
},
{
"title": "Edit this page",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions",
"enum": [
"content.action.edit"
]
"const": "content.action.edit"
},
{
"title": "View source of this page",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions",
"enum": [
"content.action.view"
]
"const": "content.action.view"
},
{
"title": "Code annotations",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations",
"enum": [
"content.code.annotate"
]
"const": "content.code.annotate"
},
{
"title": "Code copy button",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-copy-button",
"enum": [
"content.code.copy"
]
"const": "content.code.copy"
},
{
"title": "Code selection button",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-selection-button",
"enum": [
"content.code.select"
]
"const": "content.code.select"
},
{
"title": "Linked content tabs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs",
"enum": [
"content.tabs.link"
]
"const": "content.tabs.link"
},
{
"title": "Improved tooltips",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/tooltips/#improved-tooltips",
"enum": [
"content.tooltips"
]
"const": "content.tooltips"
},
{
"title": "Header hides automatically when scrolling",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#automatic-hiding",
"enum": [
"header.autohide"
]
"const": "header.autohide"
},
{
"title": "Navigation expansion",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion",
"enum": [
"navigation.expand"
]
"const": "navigation.expand"
},
{
"title": "Navigation footer",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-footer",
"enum": [
"navigation.footer"
]
"const": "navigation.footer"
},
{
"title": "Section index pages",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages",
"enum": [
"navigation.indexes"
]
"const": "navigation.indexes"
},
{
"title": "Instant loading",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading",
"enum": [
"navigation.instant"
]
"const": "navigation.instant"
},
{
"title": "Instant prefetching",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-prefetching",
"enum": [
"navigation.instant.prefetch"
]
"const": "navigation.instant.prefetch"
},
{
"title": "Progress indicator",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#progress-indicator",
"enum": [
"navigation.instant.progress"
]
"const": "navigation.instant.progress"
},
{
"title": "Navigation path (Breadcrumbs)",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-path",
"enum": [
"navigation.path"
]
"const": "navigation.path"
},
{
"title": "Navigation pruning",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-pruning",
"enum": [
"navigation.prune"
]
"const": "navigation.prune"
},
{
"title": "Navigation sections",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections",
"enum": [
"navigation.sections"
]
"const": "navigation.sections"
},
{
"title": "Navigation tabs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs",
"enum": [
"navigation.tabs"
]
"const": "navigation.tabs"
},
{
"title": "Sticky navigation tabs",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#sticky-navigation-tabs",
"enum": [
"navigation.tabs.sticky"
]
"const": "navigation.tabs.sticky"
},
{
"title": "Back-to-top button",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button",
"enum": [
"navigation.top"
]
"const": "navigation.top"
},
{
"title": "Anchor tracking",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking",
"enum": [
"navigation.tracking"
]
"const": "navigation.tracking"
},
{
"title": "Search higlighting",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-highlighting",
"enum": [
"search.highlight"
]
"const": "search.highlight"
},
{
"title": "Search sharing",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-sharing",
"enum": [
"search.share"
]
"const": "search.share"
},
{
"title": "Search suggestions",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions",
"enum": [
"search.suggest"
]
"const": "search.suggest"
},
{
"title": "Integrated table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-following",
"enum": [
"toc.follow"
]
"const": "toc.follow"
},
{
"title": "Integrated table of contents",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-integration",
"enum": [
"toc.integrate"
]
"const": "toc.integrate"
}
]
},
@ -885,6 +705,7 @@
{
"title": "Google Fonts",
"markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/",
"type": "object",
"properties": {
"text": {
"$ref": "assets/fonts.json"

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

@ -248,8 +248,7 @@ them at your own risk.
#### Document contributors
<!-- md:sponsors -->
<!-- md:version insiders-4.19.0 -->
<!-- md:version 9.5.0 -->
<!-- md:plugin [git-committers] -->
<!-- md:flag experimental -->
@ -324,8 +323,7 @@ them at your own risk.
#### Document authors
<!-- md:sponsors -->
<!-- md:version insiders-4.19.0 -->
<!-- md:version 9.5.0 -->
<!-- md:plugin [git-authors] -->
<!-- md:flag experimental -->
@ -333,7 +331,10 @@ The [git-authors] plugin is a lightweight alternative to the
[git-committers] plugin and extracts the authors of a document from git to display
them at the bottom of each page.
[Insiders] offers deep integration for [git-authors]. This means the [customized overrides](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-material-theme) are not necessary, and additional styling (such as nice icons) are added. Simply install it with `pip`:
Material for MkDocs offers deep integration for [git-authors]. This means the
[customized overrides](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-material-theme)
are not necessary, and additional styling (such as nice icons) are added.
Simply install it with `pip`:
```
pip install mkdocs-git-authors-plugin

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

@ -267,15 +267,14 @@ default color palette.
#### Automatic light / dark mode
<!-- md:sponsors -->
<!-- md:version insiders-4.18.0 -->
<!-- md:version 9.5.0 -->
<!-- md:flag experimental -->
<!-- md:example color-palette-system-preference -->
Newer operating system allow to automatically switch between light and dark
appearance during day and night times. [Insiders] adds support for automatic
light / dark mode, delegating color palette selection to the user's operating
system. Add the following lines to `mkdocs.yml`:
Newer operating systems allow to automatically switch between light and dark
appearance during day and night times. Material for MkDocs adds support for
automatic light / dark mode, delegating color palette selection to the user's
operating system. Add the following lines to `mkdocs.yml`:
``` yaml
theme:

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

@ -67,7 +67,7 @@ theme:
while complying with the __General Data Protection Regulation__ (GDPR),
by automatically downloading and self-hosting the web font files.
[data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
[data privacy]: https://developers.google.com/fonts/faq/privacy
[built-in privacy plugin]:../plugins/privacy.md
## Customization

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

@ -97,6 +97,38 @@ The following properties are available for each alternate language:
[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
[Language selector preview]: ../assets/screenshots/language-selection.png
#### Stay on page :material-alert-decagram:{ .mdx-pulse title="Added on December 8, 2023" }
<!-- md:sponsors -->
<!-- md:version insiders-4.47.0 -->
<!-- md:flag experimental -->
[Insiders] improves the user experience when switching between languages, e.g.,
if language `en` and `de` contain a page with the same path name, the user will
stay on the current page:
=== "Insiders"
```
docs.example.com/en/ -> docs.example.com/de/
docs.example.com/en/foo/ -> docs.example.com/de/foo/
docs.example.com/en/bar/ -> docs.example.com/de/bar/
```
=== "Material for MkDocs"
```
docs.example.com/en/ -> docs.example.com/de/
docs.example.com/en/foo/ -> docs.example.com/de/
docs.example.com/en/bar/ -> docs.example.com/de/
```
No configuration is necessary. We're working hard on improving multi-language
support in 2024, including making switching between languages even more seamless
in the future.
[Insiders]: ../insiders/index.md
### Directionality
<!-- md:version 2.5.0 -->

24
docs/setup/ensuring-data-privacy.md
View File

@ -139,7 +139,7 @@ in `mkdocs.yml`:
``` yaml
copyright: >
Copyright &copy; 2016 - 2023 Martin Donath –
Copyright &copy; 2016 - 2024 Martin Donath –
<a href="#__consent">Change cookie settings</a>
```
@ -147,8 +147,7 @@ copyright: >
### Built-in privacy plugin
<!-- md:sponsors -->
<!-- md:version insiders-4.9.0 -->
<!-- md:version 9.5.0 -->
<!-- md:plugin [privacy][built-in privacy plugin] -->
<!-- md:flag experimental -->
@ -207,7 +206,6 @@ For a list of all settings, please consult the [plugin documentation].
[example]: #example
[built-in optimize plugin]: ../plugins/optimize.md
??? example "Expand to inspect example"
For the official documentation, the [built-in privacy plugin] downloads the
@ -281,6 +279,24 @@ For a list of all settings, please consult the [plugin documentation].
[built-in privacy plugin]: ../plugins/privacy.md
[preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch
#### Advanced settings
<!-- md:sponsors -->
<!-- md:version insiders-4.50.0 -->
The following advanced settings are currently reserved to our [sponsors]
[Insiders]. They are entirely optional, and don't affect the functionality of
the blog, but can be helpful for customizations:
- [`log`][config.log]
- [`log_level`][config.log_level]
We'll add more settings here, as we discover new use cases.
[Insiders]: ../insiders/index.md
[config.log]: ../plugins/privacy.md#config.log
[config.log_level]: ../plugins/privacy.md#config.log_level
## Customization
### Custom cookies

15
docs/setup/extensions/python-markdown-extensions.md
View File

@ -53,11 +53,17 @@ of [additional JavaScript]:
}
};
document$.subscribe(() => {
document$.subscribe(() => { // (1)!
MathJax.startup.output.clearCache()
MathJax.typesetClear()
MathJax.texReset()
MathJax.typesetPromise()
})
```
1. This integrates MathJax with [instant loading]
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
@ -81,6 +87,7 @@ See reference for usage:
[MathJax]: https://www.mathjax.org/
[KaTeX]: https://github.com/Khan/KaTeX
[additional JavaScript]: ../../customization.md#additional-javascript
[instant loading]: ../setting-up-navigation.md#instant-loading
[Using block syntax]: ../../reference/math.md#using-block-syntax
[Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax
@ -532,7 +539,7 @@ See reference for usage:
<!-- md:extension [pymdownx.smartsymbols][SmartSymbols] -->
The [SmartSymbols] extension converts some sequences of characters into their
corresponding symbols, e.h. copyright symbols or fractions. Enable it via
corresponding symbols, e.g. copyright symbols or fractions. Enable it via
`mkdocs.yml`:
``` yaml
@ -667,8 +674,8 @@ The following configuration options are supported:
<!-- md:option pymdownx.tabbed.combine_header_slug -->
: <!-- md:default `false` --> This option enables the content tabs
[combine_header_slug style] flag, which prepends the id of the header to
: <!-- md:default `false` --> This option enables the content tabs'
[`combine_header_slug` style] flag, which prepends the id of the header to
the id of the tab:
``` yaml

127
docs/setup/setting-up-a-blog.md
View File

@ -36,12 +36,41 @@ For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/blog.md
#### Advanced settings :material-alert-decagram:{ .mdx-pulse title="Added on November 23, 2023" }
<!-- md:sponsors -->
<!-- md:version insiders-4.44.0 -->
The following advanced settings are currently reserved to our [sponsors]
[Insiders]. They are entirely optional, and don't affect the functionality of
the blog, but can be helpful for customizations:
- [`archive_pagination`][config.archive_pagination]
- [`archive_pagination_per_page`][config.archive_pagination_per_page]
- [`categories_sort_by`][config.categories_sort_by]
- [`categories_sort_reverse`][config.categories_sort_reverse]
- [`categories_pagination`][config.categories_pagination]
- [`categories_pagination_per_page`][config.categories_pagination_per_page]
- [`authors_profiles_pagination`][config.authors_profiles_pagination]
- [`authors_profiles_pagination_per_page`][config.authors_profiles_pagination_per_page]
We'll add more settings here, as we discover new use cases.
[Insiders]: ../insiders/index.md
[built-in blog plugin]: ../plugins/blog.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
[start writing your first post]: #writing-your-first-post
[config.archive_pagination]: ../plugins/blog.md#config.archive_pagination
[config.archive_pagination_per_page]: ../plugins/blog.md#config.archive_pagination_per_page
[config.categories_sort_by]: ../plugins/blog.md#config.categories_sort_by
[config.categories_sort_reverse]: ../plugins/blog.md#config.categories_sort_reverse
[config.categories_pagination]: ../plugins/blog.md#config.categories_pagination
[config.categories_pagination_per_page]: ../plugins/blog.md#config.categories_pagination_per_page
[config.authors_profiles_pagination]: ../plugins/blog.md#config.authors_profiles_pagination
[config.authors_profiles_pagination_per_page]: ../plugins/blog.md#config.authors_profiles_pagination_per_page
### RSS
<!-- md:version 9.2.0 -->
@ -152,6 +181,36 @@ For further information, see the [documentation].
[theme extension]: ../customization.md
[documentation]: https://guts.github.io/mkdocs-rss-plugin/configuration/
### Blog only
You might need to build a pure blog without any documentation.
In this case, you can create a folder tree like this:
``` { .sh .no-copy }
.
├─ docs/
│ ├─ posts/ # (1)!
│ ├─ .authors.yml
│ └─ index.md
└─ mkdocs.yml
```
1. Notice that the `posts` directory is in the root of `docs` without
intermediate `blog` directory.
And add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- blog:
blog_dir: . # (1)!
```
1. More info about [blog_dir](../plugins/blog.md#config.blog_dir)
With this configuration, the url of the blog post will be `/<post_slug>`
instead of `/blog/<post_slug>`.
## Usage
### Writing your first post
@ -181,7 +240,7 @@ Create a new file called `hello-world.md` and add the following lines:
``` yaml
---
draft: true # (1)!
date: 2023-01-31 # (2)!
date: 2024-01-31 # (2)!
categories:
- Hello
- World
@ -260,25 +319,8 @@ authors:
The [`.authors.yml`][authors_file] file associates each author with an
identifier (in this example `squidfunk`), which can then be used in posts.
The following properties are available for each author:
<!-- md:option blog.authors_file.name -->
: <!-- md:default none --> <!-- md:flag required -->
This property must define a name for the author. The name is displayed in
the left sidebar of each post as part of the author info.
<!-- md:option blog.authors_file.description -->
: <!-- md:default none --> <!-- md:flag required -->
This property can be used to add a short description for the author, e.g.
the role or profession of the author, or any other title.
<!-- md:option blog.authors_file.avatar -->
: <!-- md:default none --> <!-- md:flag required -->
This property must point to a valid image URL, internal or external, and is
used as part of posts and excerpts as the author's avatar.
Different attributes can be configured. For a list of all possible attributes,
please consult the [`authors_file`][authors_file] documentation.
Now, you can assign one or more authors to a post by referencing their
identifiers in the front matter of the Markdown file under the `authors`
@ -287,7 +329,7 @@ each post, as well as in post excerpts on index pages:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
authors:
- squidfunk
...
@ -300,6 +342,30 @@ authors:
[authors]: ../plugins/blog.md#authors
[authors_file]: ../plugins/blog.md#config.authors_file
#### Adding author profiles :material-alert-decagram:{ .mdx-pulse title="Added on November 26, 2023" }
<!-- md:sponsors -->
<!-- md:version insiders-4.46.0 -->
<!-- md:flag experimental -->
If you wish to add a dedicated page for each author, you can enable author
profiles by setting the [`authors_profiles`][authors_profiles] configuration
option to `true`. Just add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- blog:
authors_profiles: true
```
If you combine this with [custom index pages], you can create a dedicated page
for each author with a short description, social media links, etc. – basically
anything you can write in Markdown. The list of posts is then appended after
the content of the page.
[authors_profiles]: ../plugins/blog.md#config.authors_profiles
[custom index pages]: #custom-index-pages
#### Adding categories
Categories are an excellent way for grouping your posts thematically on
@ -309,7 +375,7 @@ add them to the front matter `categories` property:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
categories:
- Hello
- World
@ -335,7 +401,7 @@ part of a post, the post is linked from the [tags index]:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
tags:
- Foo
- Bar
@ -378,7 +444,7 @@ to add related links to a post:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
links:
- plugins/search.md
- insiders/index.md#how-to-become-a-sponsor
@ -394,7 +460,7 @@ links and even use nesting:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
links:
- plugins/search.md
- insiders/index.md#how-to-become-a-sponsor
@ -454,7 +520,7 @@ post:
``` yaml
---
date: 2023-01-31
date: 2024-01-31
readtime: 15
---
@ -469,6 +535,11 @@ This will disable automatic reading time computation.
#### Setting defaults
<!-- md:sponsors -->
<!-- md:version insiders-4.21.0 -->
<!-- md:plugin [meta] – built-in -->
<!-- md:flag experimental -->
If you have a lot of posts, it might feel redundant to define all of the above
for each post. Luckily, the [built-in meta plugin] allows to set default front
matter properties per folder. You can group your posts by categories, or
@ -595,5 +666,5 @@ The following templates are added by the [built-in blog plugin]:
[theme extension]: ../customization.md#extending-the-theme
[blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog.html
[blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog-post.htmlhtml
[blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog.html
[blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog-post.html

29
docs/setup/setting-up-site-analytics.md
View File

@ -274,18 +274,39 @@ generated by users interacting with the feedback widget with the help of some
``` js
var feedback = document.forms.feedback
feedback.hidden = false // (1)!
feedback.addEventListener("submit", function(ev) {
ev.preventDefault()
/* Retrieve page and feedback value */
var page = document.location.pathname
var page = document.location.pathname // (2)!
var data = ev.submitter.getAttribute("data-md-value")
/* Send feedback value */
console.log(page, data)
console.log(page, data) // (3)!
feedback.firstElementChild.disabled = true // (4)!
var note = feedback.querySelector(
".md-feedback__note [data-md-value='" + data + "']"
)
if (note)
note.hidden = false // (5)!
})
```
1. The feedback widget is hidden by default so that it does not appear when
people have JavaScript turned off. So, it needs to be turned on here.
2. Retrieve page and feedback value.
3. Replace this with the code that sends the data off to your analytics
provider.
4. Disable the form after submission.
5. Show the configured notes. Which one is shown depends on the user
feedback.
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml

8
docs/setup/setting-up-social-cards.md
View File

@ -1,7 +1,3 @@
---
status: new
---
# Setting up social cards
Material for MkDocs can automatically create beautiful social cards for your
@ -53,7 +49,7 @@ plugins:
For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/blog.md
[plugin documentation]: ../plugins/social.md
!!! info "The [`site_url`][site_url] setting must be set"
@ -632,7 +628,7 @@ tags:
twitter:image: "{{ image.url }}"
```
Note that this examples makes use of [YAML anchors] to minify repetition. The
Note that this example makes use of [YAML anchors] to minify repetition. The
`definitions` property is solely intended for the definition on aliases that
can then be referenced with anchors.

169
docs/setup/setting-up-tags.md
View File

@ -27,6 +27,25 @@ For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/tags.md
#### Advanced settings :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:flag experimental -->
The following advanced settings are currently reserved to our [sponsors]
[Insiders]. They are entirely optional, and only add additional capabilities to
the tags plugin:
<!-- - [`listings_layout`][config.listings_layout] -->
- [`listings_toc`][config.listings_toc]
We'll add more settings here in the near future.
[Insiders]: ../insiders/index.md
[config.listings_layout]: ../plugins/tags.md#config.listings_layout
[config.listings_toc]: ../plugins/tags.md#config.listings_toc
### Tag icons and identifiers
<!-- md:version 8.5.0 -->
@ -159,19 +178,31 @@ search preview, which now allows to __find pages by tags__.
<!-- md:version 8.2.0 -->
<!-- md:example tags -->
The [built-in tags plugin] allows to define a file to render a [tags index]
[tags.tags_file], which can be any page that is part of the `nav` section. To
add a tags index, create a page, e.g. `tags.md`:
The [built-in tags plugin] allows to define a file to render a tags index,
which can be any page that is part of the `nav` section. To add a tags index,
create a page, e.g. `tags.md`:
``` markdown
# Tags
Following is a list of relevant tags:
[TAGS]
<!-- material/tags -->
```
The `[TAGS]` marker specifies the position of the tags index, i.e. it is
Then in your `mkdocs.yml` file, add the following.
``` yaml
plugins:
- tags:
tags_file: tags.md # (1)!
```
1. This setting is not necessary when using [Insiders].
Note that the path to `tags.md` is relative to the `docs/` directory.
The tags marker specifies the position of the tags index, i.e. it is
replaced with the actual tags index when the page is rendered. You can include
arbitrary content before and after the marker:
@ -180,6 +211,134 @@ arbitrary content before and after the marker:
[tags.tags_file]: #tags-file
[tags index enabled]: ../assets/screenshots/tags-index.png
### Advanced features :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
[Insiders] ships a __ground up rewrite of the tags plugin__ which is infinitely
more powerful than the current version in the community edition. It allows
for an arbitrary number of tags indexes (listings), [scoped listings],
[shadow tags], [nested tags], and much more.
[scoped listings]: #scoped-listings
[shadow tags]: #shadow-tags
[nested tags]: #nested-tags
#### Configurable listings
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:flag experimental -->
Listings can be configured in `mkdocs.yml` or directly at the location of the
marker that you position in a Markdown document. Some examples:
- __Use [scoped listings]__: limit the tags index to pages that are on the same
level of the subsection of the documentation the page is in:
``` html
<!-- material/tags { scope: true } -->
```
- __List only specific tags__: limit the tags index to a single or multiple
selected tags, e.g., `Foo` and `Bar`, excluding all other tags:
``` html
<!-- material/tags { include: [Foo, Bar] } -->
```
- __Exclude pages with specific tags__: don't include pages that are tagged
with specific tags, e.g. `Internal`. This can be any tag, including a shadow
tag:
``` html
<!-- material/tags { exclude: [Internal] } -->
```
- __Enable or disable tags inside the table of contents__: specify whether the
table of contents lists all tags under the nearest headline:
``` html
<!-- material/tags { toc: false } -->
```
See the [listing configuration] for all options.
[listing configuration]: ../plugins/tags.md#listing-configuration
#### Scoped listings
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:flag experimental -->
If your documentation is large, you might want to consider using scoped listings
which will only include pages that are on the same level or below the page
containing the listing. Just use:
``` html
<!-- material/tags { scope: true } -->
```
If you plan to use multiple scoped indexes, it's a good idea to define a
listing configuration in `mkdocs.yml`, which you can then reference by its id:
``` yaml
plugins:
- tags:
listings_map:
scoped:
scope: true
```
You can now use:
``` html
<!-- material/tags scoped -->
```
#### Shadow tags
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:flag experimental -->
Shadow tags are tags that are solely meant to organization, which can be
included or excluded for rendering with a simple flag. They can be enumerated
in the [`shadow_tags`][config.shadow_tags] setting:
``` yaml
plugins:
- tags:
shadow_tags:
- Draft
- Internal
```
If a document is tagged with `Draft`, the tag will only be rendered if
[`shadow`][config.shadow] setting is enabled, and excluded when it is disabled.
This is an excellent opportunity for using tags for structuring.
[config.shadow]: ../plugins/tags.md#config.shadow
[config.shadow_tags]: ../plugins/tags.md#config.shadow_tags
#### Nested tags
<!-- md:sponsors -->
<!-- md:version insiders-4.48.0 -->
<!-- md:flag experimental -->
[Insiders] ships support for nested tags. The
[`tags_hierarchy_separator`][config.tags_hierarchy_separator] allows to create
hierarchies of tags, e.g., `Foo/Bar`. Nested tags will be rendered as children
of the parent tag:
``` yaml
plugins:
- tags:
tags_hierarchy: true
```
[config.tags_hierarchy_separator]: ../plugins/tags.md#config.tags_hierarchy_separator
### Hiding tags on a page
While the tags are rendered above the main headline, sometimes, it might be

4
material/__init__.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -18,4 +18,4 @@
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
__version__ = "9.4.8"
__version__ = "9.5.4"

2
material/extensions/__init__.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
material/extensions/emoji.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

6
material/overrides/assets/javascripts/custom.9c11c319.min.js → material/overrides/assets/javascripts/custom.054acff4.min.js vendored
View File

File diff suppressed because one or more lines are too long

6
material/overrides/assets/javascripts/custom.9c11c319.min.js.map → material/overrides/assets/javascripts/custom.054acff4.min.js.map
View File

File diff suppressed because one or more lines are too long

2
material/overrides/assets/javascripts/iconsearch_index.json
View File

File diff suppressed because one or more lines are too long

2
material/overrides/hooks/shortcodes.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

6
material/overrides/hooks/translations.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -124,7 +124,7 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files):
# -----------------------------------------------------------------------------
# Map ISO 639-1 (languages) to ISO 3166 (countries)
countries = dict({
countries = {
"af": "za",
"az": "az",
"ar": "ae",
@ -191,4 +191,4 @@ countries = dict({
"zh": "cn",
"zh-Hant": "cn",
"zh-TW": "tw"
})
}

2
material/overrides/main.html
View File

@ -23,5 +23,5 @@
{% endblock %}
{% block scripts %}
{{ super() }}
<script src="{{ 'assets/javascripts/custom.9c11c319.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/custom.054acff4.min.js' | url }}"></script>
{% endblock %}

2
material/plugins/__init__.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
material/plugins/blog/__init__.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

6
material/plugins/blog/author.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -19,7 +19,7 @@
# IN THE SOFTWARE.
from mkdocs.config.base import Config
from mkdocs.config.config_options import DictOfItems, SubConfig, Type
from mkdocs.config.config_options import DictOfItems, Optional, SubConfig, Type
# -----------------------------------------------------------------------------
# Classes
@ -30,6 +30,8 @@ class Author(Config):
name = Type(str)
description = Type(str)
avatar = Type(str)
slug = Optional(Type(str))
url = Optional(Type(str))
# -----------------------------------------------------------------------------

18
material/plugins/blog/config.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -18,10 +18,10 @@
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
from functools import partial
from markdown.extensions.toc import slugify
from collections.abc import Callable
from mkdocs.config.config_options import Choice, Deprecated, Optional, Type
from mkdocs.config.base import Config
from pymdownx.slugs import slugify
# -----------------------------------------------------------------------------
# Classes
@ -41,7 +41,7 @@ class BlogConfig(Config):
post_url_date_format = Type(str, default = "yyyy/MM/dd")
post_url_format = Type(str, default = "{date}/{slug}")
post_url_max_categories = Type(int, default = 1)
post_slugify = Type((type(slugify), partial), default = slugify)
post_slugify = Type(Callable, default = slugify(case = "lower"))
post_slugify_separator = Type(str, default = "-")
post_excerpt = Choice(["optional", "required"], default = "optional")
post_excerpt_max_authors = Type(int, default = 1)
@ -62,11 +62,15 @@ class BlogConfig(Config):
categories = Type(bool, default = True)
categories_name = Type(str, default = "blog.categories")
categories_url_format = Type(str, default = "category/{slug}")
categories_slugify = Type((type(slugify), partial), default = slugify)
categories_slugify = Type(Callable, default = slugify(case = "lower"))
categories_slugify_separator = Type(str, default = "-")
categories_allowed = Type(list, default = [])
categories_toc = Optional(Type(bool))
# Settings for authors
authors = Type(bool, default = True)
authors_file = Type(str, default = "{blog}/.authors.yml")
# Settings for pagination
pagination = Type(bool, default = True)
pagination_per_page = Type(int, default = 10)
@ -75,10 +79,6 @@ class BlogConfig(Config):
pagination_if_single_page = Type(bool, default = False)
pagination_keep_content = Type(bool, default = False)
# Settings for authors
authors = Type(bool, default = True)
authors_file = Type(str, default = "{blog}/.authors.yml")
# Settings for drafts
draft = Type(bool, default = False)
draft_on_serve = Type(bool, default = True)

118
material/plugins/blog/plugin.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -27,6 +27,8 @@ import yaml
from babel.dates import format_date
from datetime import datetime
from jinja2 import pass_context
from jinja2.runtime import Context
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.exceptions import PluginError
from mkdocs.plugins import BasePlugin, event_priority
@ -35,6 +37,7 @@ from mkdocs.structure.files import File, Files, InclusionLevel
from mkdocs.structure.nav import Navigation, Section
from mkdocs.structure.pages import Page
from mkdocs.utils import copy_file, get_relative_url
from mkdocs.utils.templates import url_filter
from paginate import Page as Pagination
from shutil import rmtree
from tempfile import mkdtemp
@ -44,7 +47,6 @@ from .author import Authors
from .config import BlogConfig
from .readtime import readtime
from .structure import Archive, Category, Excerpt, Post, View
from .templates import url_filter
# -----------------------------------------------------------------------------
# Classes
@ -110,7 +112,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
root = posixpath.normpath(self.config.blog_dir)
site = config.site_dir
# Compute path to posts directory
# Compute and normalize path to posts directory
path = self.config.post_dir.format(blog = root)
path = posixpath.normpath(path)
@ -136,19 +138,22 @@ class BlogPlugin(BasePlugin[BlogConfig]):
# Generate views for archive
if self.config.archive:
views = self._generate_archive(config, files)
self.blog.views.extend(views)
self.blog.views.extend(
self._generate_archive(config, files)
)
# Generate views for categories
if self.config.categories:
views = self._generate_categories(config, files)
self.blog.views.extend(views)
self.blog.views.extend(sorted(
self._generate_categories(config, files),
key = lambda view: view.name,
reverse = False
))
# Generate pages for views
if self.config.pagination:
for view in self._resolve_views(self.blog):
for page in self._generate_pages(view, config, files):
page.file.inclusion = InclusionLevel.EXCLUDED
view.pages.append(page)
# Ensure that entrypoint is always included in navigation
@ -180,6 +185,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
# Revert temporary exclusion of views from navigation
for view in self._resolve_views(self.blog):
view.file.inclusion = self.blog.file.inclusion
for page in view.pages:
page.file.inclusion = self.blog.file.inclusion
@ -259,10 +265,11 @@ class BlogPlugin(BasePlugin[BlogConfig]):
# is not already present, so we can remove footnotes or other content
# from the excerpt without affecting the content of the excerpt
if separator not in page.markdown:
path = page.file.src_path
if self.config.post_excerpt == "required":
docs = os.path.relpath(config.docs_dir)
path = os.path.relpath(page.file.abs_src_path, docs)
raise PluginError(
f"Couldn't find '{separator}' separator in '{path}'"
f"Couldn't find '{separator}' in post '{path}' in '{docs}'"
)
else:
page.markdown += f"\n\n{separator}"
@ -298,9 +305,25 @@ class BlogPlugin(BasePlugin[BlogConfig]):
def date_filter(date: datetime):
return self._format_date_for_post(date, config)
# Patch URL template filter to add support for paginated views, i.e.,
# that paginated views never link to themselves but to the main view
@pass_context
def url_filter_with_pagination(context: Context, url: str | None):
page = context["page"]
# If the current page is a view, check if the URL links to the page
# itself, and replace it with the URL of the main view
if isinstance(page, View):
view = self._resolve_original(page)
if page.url == url:
url = view.url
# Forward to original template filter
return url_filter(context, url)
# Register custom template filters
env.filters["date"] = date_filter
env.filters["url"] = url_filter
env.filters["url"] = url_filter_with_pagination
# Prepare view for rendering (run latest) - views are rendered last, as we
# need to mutate the navigation to account for pagination. The main problem
@ -317,16 +340,6 @@ class BlogPlugin(BasePlugin[BlogConfig]):
if view not in self._resolve_views(self.blog):
return
# If the current view is paginated, replace and rewire it - the current
# view temporarily becomes the main view, and is reset after rendering
assert isinstance(view, View)
if view != page:
prev = view.pages[view.pages.index(page) - 1]
# Replace previous page with current page
items = self._resolve_siblings(view, nav)
items[items.index(prev)] = page
# Render excerpts and prepare pagination
posts, pagination = self._render(page)
@ -342,26 +355,6 @@ class BlogPlugin(BasePlugin[BlogConfig]):
context["posts"] = posts
context["pagination"] = pager if pagination else None
# After rendering a paginated view, replace the URL of the paginated view
# with the URL of the original view - since we need to replace the original
# view with a paginated view in `on_page_context` for correct resolution of
# the active state, we must fix the paginated view URLs after rendering
def on_post_page(self, output, *, page, config):
if not self.config.enabled:
return
# Skip if page is not a view managed by this instance - this plugin has
# support for multiple instances, which is why this check is necessary
view = self._resolve_original(page)
if view not in self._resolve_views(self.blog):
return
# If the current view is paginated, replace the URL of the paginated
# view with the URL of the original view - see https://t.ly/Yeh-P
assert isinstance(view, View)
if view != page:
page.file.url = view.file.url
# Remove temporary directory on shutdown
def on_shutdown(self):
rmtree(self.temp_dir)
@ -484,19 +477,6 @@ class BlogPlugin(BasePlugin[BlogConfig]):
# Validate authors and throw if errors occurred
errors, warnings = config.validate()
if not config.authors and warnings:
log.warning(
f"Action required: the format of the authors file changed.\n"
f"All authors must now be located under the 'authors' key.\n"
f"Please adjust '{file}' to match:\n"
f"\n"
f"authors:\n"
f" squidfunk:\n"
f" avatar: https://avatars.githubusercontent.com/u/932156\n"
f" description: Creator\n"
f" name: Martin Donath\n"
f"\n"
)
for _, w in warnings:
log.warning(w)
for _, e in errors:
@ -527,7 +507,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
# Resolve original page or view (e.g. for paginated views)
def _resolve_original(self, page: Page):
if isinstance(page, View):
if isinstance(page, View) and page.pages:
return page.pages[0]
else:
return page
@ -550,13 +530,14 @@ class BlogPlugin(BasePlugin[BlogConfig]):
file = self._path_to_file(path, config)
files.append(file)
# Create file in temporary directory
# Create file in temporary directory and temporarily remove
# from navigation, as we'll add it at a specific location
self._save_to_file(file.abs_src_path, f"# {name}")
file.inclusion = InclusionLevel.EXCLUDED
# Create and yield view - we don't explicitly set the title of
# the view, so authors can override them in the page's content
# Create and yield view
if not isinstance(file.page, Archive):
yield Archive(None, file, config)
yield Archive(name, file, config)
# Assign post to archive
assert isinstance(file.page, Archive)
@ -585,13 +566,14 @@ class BlogPlugin(BasePlugin[BlogConfig]):
file = self._path_to_file(path, config)
files.append(file)
# Create file in temporary directory
# Create file in temporary directory and temporarily remove
# from navigation, as we'll add it at a specific location
self._save_to_file(file.abs_src_path, f"# {name}")
file.inclusion = InclusionLevel.EXCLUDED
# Create and yield view - we don't explicitly set the title of
# the view, so authors can override them in the page's content
# Create and yield view
if not isinstance(file.page, Category):
yield Category(None, file, config)
yield Category(name, file, config)
# Assign post to category and vice versa
assert isinstance(file.page, Category)
@ -615,12 +597,14 @@ class BlogPlugin(BasePlugin[BlogConfig]):
file = self._path_to_file(path, config)
files.append(file)
# Copy file to temporary directory
# Copy file to temporary directory and temporarily remove
# from navigation, as we'll add it at a specific location
copy_file(view.file.abs_src_path, file.abs_src_path)
file.inclusion = InclusionLevel.EXCLUDED
# Create view and attach to previous page
# Create and yield view
if not isinstance(file.page, View):
yield View(None, file, config)
yield view.__class__(None, file, config)
# Assign pages and posts to view
assert isinstance(file.page, View)
@ -800,7 +784,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
# Format date
def _format_date(self, date: datetime, format: str, config: MkDocsConfig):
locale = config.theme["language"]
locale: str = config.theme["language"].replace("-", "_")
return format_date(date, format = format, locale = locale)
# Format date for post

2
material/plugins/blog/readtime/__init__.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
material/plugins/blog/readtime/parser.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

24
material/plugins/blog/structure/__init__.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -61,7 +61,7 @@ class Post(Page):
self.markdown = f.read()
# Sadly, MkDocs swallows any exceptions that occur during parsing.
# As we want to provide the best possible authoring experience, we
# Since we want to provide the best possible user experience, we
# need to catch errors early and display them nicely. We decided to
# drop support for MkDocs' MultiMarkdown syntax, because it is not
# correctly implemented anyway. When using MultiMarkdown syntax, all
@ -80,7 +80,7 @@ class Post(Page):
self.markdown = self.markdown[match.end():].lstrip("\n")
# The post's metadata could not be parsed because of a syntax error,
# which we display to the user with a nice error message
# which we display to the author with a nice error message
except Exception as e:
raise PluginError(
f"Error reading metadata of post '{path}' in '{docs}':\n"
@ -148,8 +148,8 @@ class Excerpt(Page):
self._set_canonical_url(config.site_url)
# Initialize configuration and metadata
self.config = post.config
self.meta = post.meta
self.config = post.config
self.meta = post.meta
# Initialize authors and categories - note that views usually contain
# subsets of those lists, which is why we need to manage them here
@ -212,10 +212,18 @@ class Excerpt(Page):
# View
class View(Page):
# Parent view
parent: View | Section
# Initialize view
def __init__(self, title: str | None, file: File, config: MkDocsConfig):
super().__init__(title, file, config)
self.parent: View | Section
def __init__(self, name: str | None, file: File, config: MkDocsConfig):
super().__init__(None, file, config)
# Initialize name of the view - note that views never pass a title to
# the parent constructor, so the author can always override the title
# that is used for rendering. However, for some purposes, like for
# example sorting, we need something to compare.
self.name = name
# Initialize posts and views
self.posts: list[Post] = []

2
material/plugins/blog/structure/config.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

2
material/plugins/blog/structure/markdown.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to

18
material/plugins/blog/structure/options.py
View File

@ -1,4 +1,4 @@
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@ -53,15 +53,23 @@ class PostDate(BaseConfigOption[DateDict]):
# Normalize the supported types for post dates to datetime
def pre_validation(self, config: Config, key_name: str):
# If the date points to a scalar value, convert it to a dictionary,
# since we want to allow the user to specify custom and arbitrary date
# values for posts. Currently, only the `created` date is mandatory,
# because it's needed to sort posts for views.
# If the date points to a scalar value, convert it to a dictionary, as
# we want to allow the author to specify custom and arbitrary dates for
# posts. Currently, only the `created` date is mandatory, because it's
# needed to sort posts for views.
if not isinstance(config[key_name], dict):
config[key_name] = { "created": config[key_name] }
# Convert all date values to datetime
for key, value in config[key_name].items():
# Handle datetime - since datetime is a subclass of date, we need
# to check it first, or we lose the time - see https://t.ly/-KG9N
if isinstance(value, datetime):
continue
# Handle date - we set 00:00:00 as the default time, if the author
# only supplied a date, and convert it to datetime
if isinstance(value, date):
config[key_name][key] = datetime.combine(value, time())

Some files were not shown because too many files have changed in this diff Show More