Add AI documentation skills
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: Built-in group plugin
|
||||
icon: material/format-list-group
|
||||
---
|
||||
|
||||
# Built-in group plugin
|
||||
|
||||
The group plugin allows to group plugins into logical units to conditionally
|
||||
enable or disable them for specific environments with the use of
|
||||
[environment variables][mkdocs.env], e.g., to only enable a subset of
|
||||
plugins when [building your project] during continuous integration (CI).
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin conditionally and lazily loads all plugins that are part of a group
|
||||
if and only if the group is enabled, which means that the plugin doesn't add any
|
||||
overhead when the group is disabled. It also means that the grouped plugins
|
||||
only need to be installed when the group is enabled.
|
||||
|
||||
The plugins that are part of the group are executed in the same order as if
|
||||
they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
|
||||
Thus, order is preserved and deterministic.
|
||||
|
||||
### When to use it
|
||||
|
||||
Whenever you're using multiple plugins that are only required in specific
|
||||
environments, e.g., when building your project during continuous integration
|
||||
(CI), the plugin is the perfect utility for making configuration simpler, as it
|
||||
removes the need for splitting configuration into multiple files.
|
||||
|
||||
It can be used with any built-in or third-party plugin.
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.3.0 -->
|
||||
<!-- md:plugin [group] – built-in -->
|
||||
<!-- md:flag multiple -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
As with all [built-in plugins], getting started with the group plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and start
|
||||
splitting plugins into logical units:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- group
|
||||
```
|
||||
|
||||
The group plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[group]: group.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.3.0 -->
|
||||
<!-- md:default `false` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
The plugin behaves differently than all other built-in plugins – __it is
|
||||
disabled by default__. To enable a group, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- group:
|
||||
enabled: !ENV CI # (1)!
|
||||
```
|
||||
|
||||
1. If you only want to use the group plugin for better organization and
|
||||
always want to enable the plugins that are part of it, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- group:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
The decision to disable the plugin by default was made to simplify the usage
|
||||
of environment variables, as it removes the need to provide a default value for
|
||||
an environment variable.
|
||||
|
||||
Now, when [building your project], you can enable a group by setting the
|
||||
[environment variable][mkdocs.env]:
|
||||
|
||||
``` sh
|
||||
CI=true mkdocs build
|
||||
```
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.plugins -->
|
||||
|
||||
<!-- md:version 9.3.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to list the plugins that are part of the group. The syntax is
|
||||
exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
|
||||
simply copy the list of plugins that you want to group, e.g:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- group:
|
||||
plugins:
|
||||
- optimize
|
||||
- minify
|
||||
```
|
||||
|
||||
The plugins mentioned here are just used for illustration purposes.
|
||||
@@ -0,0 +1,246 @@
|
||||
# Built-in plugins
|
||||
|
||||
Material for MkDocs started out as a theme for [MkDocs][mkdocs], but has since
|
||||
evolved into a full-fledged framework for building and maintaining documentation.
|
||||
The theme is still the core of the project, but it's now accompanied by a
|
||||
growing number of complementary built-in plugins.
|
||||
|
||||
We strive to make those plugins as modular and generic as possible, so that they
|
||||
can be used in a wide variety of projects and use cases. By providing useful
|
||||
default settings, we also try to make them as easy to use as possible, so that
|
||||
you can get started quickly, tweaking their settings later on. When
|
||||
developing built-in plugins, we always adhere to the following design principles:
|
||||
|
||||
- **Modularity:** Built-in plugins are designed to be modular, so that they can
|
||||
be easily combined to implement sophisticated pipelines. For example, the
|
||||
[offline], [optimize] and [privacy] plugins can be used together to build
|
||||
truly [offline-capable documentation].
|
||||
|
||||
- **Interoperability:** Built-in plugins are designed to be as compatible as
|
||||
possible, so they can be used in combination with other plugins, including
|
||||
third-party plugins. We strive to make it simple to integrate with the vast
|
||||
ecosystem that has evolved around [MkDocs][mkdocs].
|
||||
|
||||
- **Performance:** Built-in plugins are designed to be as fast and
|
||||
memory-efficient as possible, so that they don't unnecessarily slow down
|
||||
builds. This is particularly important for large documentation projects with
|
||||
thousands of pages.
|
||||
|
||||
[mkdocs]: https://www.mkdocs.org/
|
||||
[design principles]: ../design-principles.md
|
||||
[offline-capable documentation]: ../setup/building-for-offline-usage.md
|
||||
|
||||
## Categories
|
||||
|
||||
### Management
|
||||
|
||||
The following plugins greatly improve the authoring experience when working on
|
||||
documentation projects by providing better management capabilities, from the
|
||||
management of plugins, multiple projects, and metadata, to the creation of
|
||||
minimal reproductions for bug reports:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-format-list-group: __[Built-in group plugin][group]__
|
||||
|
||||
---
|
||||
|
||||
The group plugin allows to group plugins into logical units to conditionally
|
||||
enable or disable them for specific environments with the use of
|
||||
[environment variables][mkdocs.env].
|
||||
|
||||
---
|
||||
|
||||
__Optimal management of plugins when building in different environments__
|
||||
|
||||
- :material-file-tree: __[Built-in meta plugin][meta]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it easy to manage metadata (front matter) for all
|
||||
pages in a folder, so a certain subset of pages uses specific tags or a
|
||||
custom template.
|
||||
|
||||
---
|
||||
|
||||
__Simpler organization, categorization and management of metadata__
|
||||
|
||||
- :material-folder-open: __[Built-in projects plugin][projects]__
|
||||
|
||||
---
|
||||
|
||||
The projects plugin allows to split your main project into multiple distinct
|
||||
projects, build them concurrently and preview them together as one.
|
||||
|
||||
---
|
||||
|
||||
__Connect multiple projects together, and build them separately or as one__
|
||||
|
||||
- :material-information: __[Built-in info plugin][info]__
|
||||
|
||||
---
|
||||
|
||||
The info plugin is a small and useful utility that helps to create
|
||||
self-contained minimal reproductions, so we maintainers can fix reported
|
||||
bugs more quickly.
|
||||
|
||||
---
|
||||
|
||||
__Your bug reports are of the highest quality, so we can fix them as fast as
|
||||
possible__
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
[group]: group.md
|
||||
[info]: info.md
|
||||
[meta]: meta.md
|
||||
[projects]: projects.md
|
||||
|
||||
### Optimization
|
||||
|
||||
The following plugins are designed to help you build optimized documentation,
|
||||
making it more accessible to your users through faster loading times, better
|
||||
search engine rankings, beautiful preview images on social media, and GDPR
|
||||
compliance with a few lines of configuration:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-share-circle: __[Built-in social plugin][social]__
|
||||
|
||||
---
|
||||
|
||||
The social plugin automatically generates beautiful and customizable
|
||||
social cards for each page of your documentation, showing as previews on
|
||||
social media.
|
||||
|
||||
---
|
||||
|
||||
__Links to your site render beautiful social cards when shared on social
|
||||
media__
|
||||
|
||||
- :material-rabbit: __[Built-in optimize plugin][optimize]__
|
||||
|
||||
---
|
||||
|
||||
The optimize plugin automatically identifies and optimizes all media files
|
||||
that you reference in your project by using compression and conversion
|
||||
techniques.
|
||||
|
||||
---
|
||||
|
||||
__Your site loads faster as smaller images are served to your users__
|
||||
|
||||
- :material-shield-account: __[Built-in privacy plugin][privacy]__
|
||||
|
||||
---
|
||||
|
||||
The privacy plugin downloads external assets automatically for easy
|
||||
self-hosting, allowing for GDPR compliance with a single line of
|
||||
configuration.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can be made GDPR compliant with minimal effort__
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building [offline-capable documentation],
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet__
|
||||
|
||||
</div>
|
||||
|
||||
[offline]: offline.md
|
||||
[optimize]: optimize.md
|
||||
[privacy]: privacy.md
|
||||
[social]: social.md
|
||||
|
||||
### Content
|
||||
|
||||
The following plugins are designed to help you set up a blog, provide search
|
||||
functionality to your users, add tags to pages and posts, and use the same
|
||||
typesetting capabilities in specific parts of the documentation exactly as in
|
||||
the main content:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
|
||||
|
||||
---
|
||||
|
||||
The blog plugin adds first-class support for blogging to Material for
|
||||
MkDocs, either as a sidecar to your documentation or as a standalone
|
||||
installation.
|
||||
|
||||
---
|
||||
|
||||
__Your blog is built with the same powerful engine as your documentation__
|
||||
|
||||
- :material-magnify: __[Built-in search plugin][search]__
|
||||
|
||||
---
|
||||
|
||||
The search plugin adds a search bar to the header, allowing users to search
|
||||
the entire documentation, so it's easier for them to find what they're
|
||||
looking for.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation is searchable without any external services, even
|
||||
offline__
|
||||
|
||||
- :material-tag-text: __[Built-in tags plugin][tags]__
|
||||
|
||||
---
|
||||
|
||||
The tags plugin adds first-class support for categorizing pages with tags,
|
||||
adding the ability to group related pages to improve the discovery of
|
||||
related content.
|
||||
|
||||
---
|
||||
|
||||
__Your pages are categorized with tags, yielding additional context__
|
||||
|
||||
- :material-format-title: __[Built-in typeset plugin][typeset]__
|
||||
|
||||
---
|
||||
|
||||
The typeset plugin allows to preserve the enriched presentation of titles
|
||||
and headlines within the navigation and table of contents.
|
||||
|
||||
---
|
||||
|
||||
__Sidebars preserve the same formatting as section titles in pages__
|
||||
|
||||
</div>
|
||||
|
||||
[blog]: blog.md
|
||||
[search]: search.md
|
||||
[tags]: tags.md
|
||||
[typeset]: typeset.md
|
||||
|
||||
## Architecture
|
||||
|
||||
### Multiple instances
|
||||
|
||||
Several built-in plugins have support for multiple instances, which means that
|
||||
they can be used multiple times in the same configuration file, allowing to
|
||||
fine-tune behavior for separate sections of your project. Currently, the
|
||||
following plugins have support for multiple instances:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [Built-in blog plugin][blog]
|
||||
- [Built-in group plugin][group]
|
||||
- [Built-in optimize plugin][optimize]
|
||||
- [Built-in privacy plugin][privacy]
|
||||
- [Built-in social plugin][social]
|
||||
|
||||
</div>
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Built-in info plugin
|
||||
icon: material/information
|
||||
---
|
||||
|
||||
# Built-in info plugin
|
||||
|
||||
The info plugin is a utility that is solely intended to create self-contained
|
||||
[minimal reproductions] as `.zip` files when [reporting bugs] or proposing
|
||||
[change requests], making communication between us maintainers and you much
|
||||
easier, as we have a common ground to work on.
|
||||
|
||||
[minimal reproductions]: ../guides/creating-a-reproduction.md
|
||||
[reporting bugs]: ../contributing/reporting-a-bug.md
|
||||
[change requests]: ../contributing/requesting-a-change.md
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin helps you to prepare a minimal reproduction by collecting the
|
||||
necessary information about the environment and configuration of your project.
|
||||
This makes it easier for us to fix bugs, as it requires that you
|
||||
[upgrade to the latest version] and [remove your customizations].
|
||||
|
||||
When following these principles, you can be confident that you don't report a
|
||||
bug that has already been fixed in a subsequent release, or which is caused by
|
||||
one of your customizations. Even more importantly, you actively help
|
||||
us to fix the bug as quickly as possible.
|
||||
|
||||
The output of the plugin is a `.zip` file that you can share with us maintainers.
|
||||
|
||||
[Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
|
||||
[Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations
|
||||
|
||||
|
||||
### When to use it
|
||||
|
||||
Whenever you're [reporting a bug][reporting bugs] or have something to discuss,
|
||||
like a question or [change request][change requests], you should attach
|
||||
a small, self-contained minimal reproduction. Runnable examples help to make
|
||||
communication much more efficient, giving us maintainers more time to benefit
|
||||
more users by pushing the project forward. Minimal reproductions are mandatory
|
||||
for bug reports.
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:plugin [info] – built-in -->
|
||||
|
||||
In order to get started with the built-in info plugin, just add the following
|
||||
lines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share
|
||||
with us maintainers:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- info
|
||||
```
|
||||
|
||||
The info plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[info]: info.md
|
||||
[create a minimal reproduction]: ../guides/creating-a-reproduction.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
It's normally not necessary to specify this setting, but if you want to disable
|
||||
the plugin, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- info:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled_on_serve -->
|
||||
|
||||
<!-- md:version 9.0.6 -->
|
||||
<!-- md:default `false` -->
|
||||
|
||||
Use this setting to control whether the plugin should be enabled when
|
||||
[previewing your site]. It's normally not necessary to specify this setting,
|
||||
but if you want to change this behavior, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- info:
|
||||
enabled_on_serve: true
|
||||
```
|
||||
|
||||
This setting streamlines the process of creating and inspecting minimal
|
||||
reproductions, as it allows to quickly iterate on the reproduction without
|
||||
having to disable the plugin first.
|
||||
|
||||
[previewing your site]: ../creating-your-site.md#previewing-as-you-write
|
||||
|
||||
### Archive
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.archive -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to control whether the plugin should create a `.zip` file
|
||||
from the project or exit after the version check. This setting is solely
|
||||
intended for debugging the plugin itself:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- info:
|
||||
archive: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.archive_stop_on_violation -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to control whether the plugin should stop creating the `.zip`
|
||||
file when one of the [requirements] is not satisfied. This setting must only be
|
||||
used when [reporting a bug][reporting bugs] that is related to a customization
|
||||
[explicitly mentioned in our documentation]. You can change it with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- info:
|
||||
archive_stop_on_violation: false
|
||||
```
|
||||
|
||||
If you're using this setting when [reporting a bug][reporting bugs], please
|
||||
explain why you think it is necessary to include customizations. If you're
|
||||
unsure, please ask us first by [creating a discussion].
|
||||
|
||||
[requirements]: #how-it-works
|
||||
[explicitly mentioned in our documentation]: ?q=%22extends+base%22
|
||||
[creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
title: Built-in meta plugin
|
||||
icon: material/file-tree
|
||||
---
|
||||
|
||||
# Built-in meta plugin
|
||||
|
||||
The meta plugin solves the problem of setting metadata (front matter) for all
|
||||
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.
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,
|
||||
and recursively merges the contents of those files with the metadata (front
|
||||
matter) of all pages that are contained in the same folder and all subfolders.
|
||||
For example, if you want to add the tag <span class="md-tag">Example</span> to
|
||||
multiple pages, use:
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
tags:
|
||||
- Example
|
||||
```
|
||||
|
||||
Now, given the following directory layout, if you store the file in the folder
|
||||
named `example`, all pages in that folder receive the tag, while all pages
|
||||
outside of the folder remain unaffected:
|
||||
|
||||
``` { .sh .no-copy hl_lines="4-8" }
|
||||
.
|
||||
├─ docs/
|
||||
│ ├─ ...
|
||||
│ ├─ example/
|
||||
│ │ ├─ .meta.yml
|
||||
│ │ ├─ a.md
|
||||
│ │ ├─ ...
|
||||
│ │ └─ z.md
|
||||
│ └─ ...
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
When combining metadata, lists and dictionaries are recursively merged, which
|
||||
means you can append values to a list and add or set specific properties in a
|
||||
dictionary on arbitrary levels.
|
||||
|
||||
### When to use it
|
||||
|
||||
While the plugin itself doesn't offer much functionality beyond adding and
|
||||
merging metadata, it is a perfect companion for many of the other built-in
|
||||
plugins that Material for MkDocs offers. Some of the most powerful combinations
|
||||
of the meta plugin and other built-in plugins are:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-share-circle: __[Built-in social plugin][social]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin can be used to [change the layout] for social cards or
|
||||
[change specific layout options] like [background] or [color]
|
||||
for a subset of pages.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
social:
|
||||
cards_layout: default/variant
|
||||
```
|
||||
|
||||
- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin allows to automatically associate blog posts with specific
|
||||
[authors] and [categories], ensuring that blog posts are always correctly
|
||||
annotated.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
authors:
|
||||
- squidfunk
|
||||
```
|
||||
|
||||
- :material-tag-text: __[Built-in tags plugin][tags]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it possible to ensure that subsections of your
|
||||
project are annotated with [specific tags], so they can't be forgotten when
|
||||
adding pages.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
tags:
|
||||
- Example
|
||||
```
|
||||
|
||||
- :material-magnify: __[Built-in search plugin][search]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it easy to [boost] specific sections in search results
|
||||
or to [exclude] them entirely from being indexed, giving more granular
|
||||
control over search.
|
||||
|
||||
``` yaml title=".meta.yml"
|
||||
search:
|
||||
exclude: true
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
[social]: social.md
|
||||
[change the layout]: social.md#meta.social.cards_layout
|
||||
[change specific layout options]: social.md#meta.social.cards_layout_options
|
||||
[background]: social.md#option.background_color
|
||||
[color]: social.md#option.color
|
||||
[blog]: blog.md
|
||||
[authors]: blog.md#meta.authors
|
||||
[categories]: blog.md#meta.categories
|
||||
[tags]: tags.md
|
||||
[specific tags]: tags.md#meta.tags
|
||||
[search]: search.md
|
||||
[exclude]: search.md#meta.search.exclude
|
||||
[boost]: search.md#meta.search.boost
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:plugin [meta] – built-in -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
As with all [built-in plugins], getting started with the meta plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and start
|
||||
applying metadata for multiple pages at once:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- meta
|
||||
```
|
||||
|
||||
The meta plugin is included with Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[meta]: meta.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
It's normally not necessary to specify this setting, but if you want to disable
|
||||
the plugin, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- meta:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
### Meta file
|
||||
|
||||
The following settings are available for meta files:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.meta_file -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default `.meta.yml` -->
|
||||
|
||||
Use this setting to change the meta file name the plugin will look for when
|
||||
scanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to
|
||||
change this setting, but if you want to change it, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- meta:
|
||||
meta_file: .meta.yml
|
||||
```
|
||||
|
||||
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]
|
||||
recursively.
|
||||
@@ -0,0 +1,154 @@
|
||||
---
|
||||
title: Built-in offline plugin
|
||||
icon: material/connection
|
||||
---
|
||||
|
||||
|
||||
# Built-in offline plugin
|
||||
|
||||
[MkDocs][mkdocs] is one of the few frameworks that supports building
|
||||
offline-capable documentation that can be directly viewed by the user – no
|
||||
server needed. With the offline plugin, you can distribute the
|
||||
[`site` directory][mkdocs.site_dir] as a downloadable `.zip` file while
|
||||
retaining most interactive functionality.
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
After [building your project], switch to the [`site` directory][mkdocs.site_dir]
|
||||
and open `index.html` in your browser – you're now viewing your documentation
|
||||
from your local file system! Most browsers will denote this by showing `file://`
|
||||
in the address bar. However, you'll realize that the site search is gone.
|
||||
|
||||
Material for MkDocs offers many interactive features, some of which will not
|
||||
work from the local file system due to the restrictions of modern browsers. More
|
||||
specifically and technically, all calls to the [Fetch API] will error with a
|
||||
message like:
|
||||
|
||||
```
|
||||
Cross origin requests are only supported for protocol schemes: http, [...]
|
||||
```
|
||||
|
||||
While browsers impose those restriction for security reasons, it reduces the
|
||||
interactivity of your project. The offline plugin makes sure that site search
|
||||
keeps working by moving the search index to a JavaScript file, and leveraging
|
||||
@squidfunk's [iframe-worker] shim.
|
||||
|
||||
Additionally, the plugin automatically disables the [`use_directory_urls`]
|
||||
[mkdocs.use_directory_urls] setting, ensuring that users can open your
|
||||
documentation directly from the local file system.
|
||||
|
||||
There are some [limitations].
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
[Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
|
||||
[iframe-worker]: https://github.com/squidfunk/iframe-worker
|
||||
[limitations]: #limitations
|
||||
|
||||
### When to use it
|
||||
|
||||
As the name already indicates, the plugin should only be used when you're
|
||||
[building your project] for offline distribution. It's also good to know, that
|
||||
the offline plugin plays nicely with the following other plugins, helping to
|
||||
create even better offline-capable documentation:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-shield-account: __[Built-in privacy plugin][privacy]__
|
||||
|
||||
---
|
||||
|
||||
The privacy plugin makes it easy to use external assets when building for
|
||||
offline usage, as it automatically downloads them for distribution with
|
||||
your documentation.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet[^1]__
|
||||
|
||||
- :material-rabbit: __[Built-in optimize plugin][optimize]__
|
||||
|
||||
---
|
||||
|
||||
The optimize plugin automatically identifies and optimizes all media files
|
||||
that you reference in your project by using compression and conversion
|
||||
techniques.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can be distributed as a smaller `.zip` download__
|
||||
|
||||
</div>
|
||||
|
||||
[^1]:
|
||||
You might wonder why the [privacy plugin][privacy] is necessary to build
|
||||
truly offline-capable documentation with the offline plugin. While it's
|
||||
certainly possible to also add support for downloading external assets to
|
||||
the offline plugin, this functionality is already fully implemented in the
|
||||
privacy plugin and is its very raison d'être.
|
||||
|
||||
Material for MkDocs follows a modular approach for its plugin system – many
|
||||
of the plugins work perfectly together and enhance each others
|
||||
functionalities, allowing to solve complex problems with a few lines
|
||||
of configuration.
|
||||
|
||||
[privacy]: privacy.md
|
||||
[optimize]: optimize.md
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:plugin [offline] – built-in -->
|
||||
|
||||
As with all [built-in plugins], getting started with the offline plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and start
|
||||
building offline-capable documentation:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- offline
|
||||
```
|
||||
|
||||
The offline plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[offline]: offline.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
If you want to build online- as well as offline-capable documentation, it's a
|
||||
good idea to use an [environment variable][mkdocs.env]:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- offline:
|
||||
enabled: !ENV [OFFLINE, false]
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
When enabling the offline plugin, make sure to disable the following settings,
|
||||
as they make use of the [Fetch API] which will error when invoked from the local
|
||||
file system:
|
||||
|
||||
- [Instant loading]
|
||||
- [Site analytics]
|
||||
- [Versioning]
|
||||
- [Comment systems]
|
||||
|
||||
[Instant loading]: ../setup/setting-up-navigation.md#instant-loading
|
||||
[Site analytics]: ../setup/setting-up-site-analytics.md
|
||||
[Versioning]: ../setup/setting-up-versioning.md
|
||||
[Comment systems]: ../setup/adding-a-comment-system.md
|
||||
@@ -0,0 +1,427 @@
|
||||
---
|
||||
title: Built-in optimize plugin
|
||||
icon: material/rabbit
|
||||
---
|
||||
|
||||
# Built-in optimize plugin
|
||||
|
||||
The optimize plugin automatically identifies and optimizes all media files when
|
||||
[building your project] by using common compression and conversion techniques.
|
||||
As a result, your site loads significantly faster and yields better rankings in
|
||||
search engines.
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and
|
||||
assets, optimizing them automatically in order to reduce the final size of the
|
||||
[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you
|
||||
ship less bytes to your users, as well as a smaller download for
|
||||
[offline-capable documentation].
|
||||
|
||||
Optimized images are [intelligently cached][intelligent caching], which is why
|
||||
the plugin will only optimize media files that changed since the last build.
|
||||
This makes it possible to swap out or update images, without having to worry
|
||||
about optimizing them, or even worse, forgetting to do so.
|
||||
|
||||
In order to optimize media files, a few [dependencies] need to be available on
|
||||
your system.
|
||||
|
||||
[offline-capable documentation]: ../setup/building-for-offline-usage.md
|
||||
[dependencies]: #configuration
|
||||
|
||||
### When to use it
|
||||
|
||||
It's generally recommended to use the plugin, as media files are optimized
|
||||
automatically without the need for intervention, ensuring that your site loads
|
||||
as fast as possible. Optimized media files are one of the key components for a
|
||||
high and consistent ranking in search engines.
|
||||
|
||||
Additionally, the plugin can be combined with other built-in plugins
|
||||
that Material for MkDocs offers, in order to create sophisticated
|
||||
build pipelines tailored to your project:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-shield-account: __[Built-in privacy plugin][privacy]__
|
||||
|
||||
---
|
||||
|
||||
The privacy plugin makes it easy to use unoptimized external assets, passing
|
||||
them to the optimize plugin before copying them to the [`site` directory]
|
||||
[mkdocs.site_dir].
|
||||
|
||||
---
|
||||
|
||||
__External media files can be automatically downloaded and optimized__
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building offline-capable documentation,
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can be distributed as a smaller `.zip` download__
|
||||
|
||||
</div>
|
||||
|
||||
[privacy]: privacy.md
|
||||
[offline]: offline.md
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:plugin [optimize] – built-in -->
|
||||
<!-- md:flag multiple -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
As with all [built-in plugins], getting started with the optimize plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and observe how
|
||||
media files are optimized automatically:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize
|
||||
```
|
||||
|
||||
The optimize plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
However, in order to optimize all media files, it's necessary to install the
|
||||
dependencies for [image processing], if they're not already available on your
|
||||
system. The linked guide includes instructions for several operating systems
|
||||
and mentions some alternative environments.
|
||||
|
||||
[optimize]: optimize.md
|
||||
[built-in plugins]: index.md
|
||||
[image processing]: requirements/image-processing.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
If you want to disable the plugin, e.g., for local builds, you can use an
|
||||
[environment variable][mkdocs.env] in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
This configuration enables the plugin only during continuous integration (CI).
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.concurrency -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default available CPUs - 1 -->
|
||||
|
||||
With more CPUs available, the plugin can do more work in parallel, and thus
|
||||
complete media file optimization faster. If you want to disable concurrent
|
||||
processing completely, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
concurrency: 1
|
||||
```
|
||||
|
||||
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
|
||||
|
||||
### Caching
|
||||
|
||||
The plugin implements an [intelligent caching] mechanism, ensuring that a media
|
||||
file or asset is only passed through the optimization pipeline when its contents
|
||||
change. If you swap out or update an image, the plugin detects it and updates
|
||||
the optimized version of the media file.
|
||||
|
||||
The following settings are available for caching:
|
||||
|
||||
[intelligent caching]: requirements/caching.md
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.cache -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to instruct the plugin to bypass the cache, in order to
|
||||
re-optimize all media files, even though the cache may not be stale. It's
|
||||
normally not necessary to specify this setting, except for when debugging
|
||||
the plugin itself. Caching can be disabled with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
cache: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.cache_dir -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `.cache/plugin/optimize` -->
|
||||
|
||||
It is normally not necessary to specify this setting, except for when you want
|
||||
to change the path within your root directory where media files are cached.
|
||||
If you want to change it, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
cache_dir: my/custom/dir
|
||||
```
|
||||
|
||||
If you're using [multiple instances] of the plugin, it can be a good idea to
|
||||
set different cache directories for both instances, so that they don't interfere
|
||||
with each other.
|
||||
|
||||
[multiple instances]: index.md#multiple-instances
|
||||
|
||||
### Optimization
|
||||
|
||||
Documentation often makes use of screenshots or diagrams for better
|
||||
visualization of things, both of which are prime candidates for optimization.
|
||||
The plugin automatically optimizes images using [pngquant] for `.png` files,
|
||||
and [Pillow] for `.jpg` files.
|
||||
|
||||
The following settings are available for optimization:
|
||||
|
||||
[pngquant]: https://pngquant.org/
|
||||
[Pillow]: https://pillow.readthedocs.io/
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable media file optimization. Currently,
|
||||
the plugin's sole purpose is to optimize media files, so it's equivalent to the
|
||||
[`enabled`][config.enabled] setting, but in the near future, other features
|
||||
might be added. If you want to disable optimization, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_png -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the optimization of `.png` files. It's
|
||||
normally not necessary to specify this setting, but if you want to disable
|
||||
the optimization of `.png` files, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_png: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_png_speed -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `3` of `1-10` -->
|
||||
|
||||
Use this setting to specify the speed/quality tradeoff that [pngquant] applies
|
||||
when optimizing `.png` files. The lower the number, the more aggressively
|
||||
[pngquant] will try to optimize:
|
||||
|
||||
=== "Slower <small>smaller</small>"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_png_speed: 1
|
||||
```
|
||||
|
||||
=== "Faster <small>larger</small>"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_png_speed: 10
|
||||
```
|
||||
|
||||
A factor of `10` has 5% lower quality, but is 8x faster than the default `3`.
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_png_strip -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to specify whether [pngquant] should strip optional metadata
|
||||
from `.png` files that are not required to display the image, e.g., [EXIF].
|
||||
If you want to preserve metadata, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_png_strip: false
|
||||
```
|
||||
|
||||
[EXIF]: https://en.wikipedia.org/wiki/Exif
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_jpg -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the optimization of `.jpg` files. It's
|
||||
normally not necessary to specify this setting, but if you want to disable
|
||||
the optimization of `.jpg` files, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_jpg: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_jpg_quality -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `60` of `0-100` -->
|
||||
|
||||
Use this setting to specify the image quality that [Pillow] applies when
|
||||
optimizing `.jpg` files. If the images look blurry, it's a good idea to
|
||||
fine-tune and change this setting:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_jpg_quality: 75
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_jpg_progressive -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to specify whether [Pillow] should use progressive encoding
|
||||
when optimizing `.jpg` files, rendering faster on slow connections. If you want
|
||||
to disable progressive encoding, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_jpg_progressive: false
|
||||
```
|
||||
|
||||
[progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_include -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to enable media file optimization for specific directories
|
||||
of your project, e.g., when using [multiple instances] of the plugin to optimize
|
||||
media files differently:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
optimize_include:
|
||||
- screenshots/*
|
||||
```
|
||||
|
||||
This configuration enables optimization for all media files that are contained
|
||||
in the `screenshots` folder and its subfolders inside the [`docs` directory]
|
||||
[mkdocs.docs_dir].
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.optimize_exclude -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to disable media file optimization for specific directories
|
||||
of your project, e.g., when using [multiple instances] of the plugin to optimize
|
||||
media files differently:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- social:
|
||||
optimize_exclude:
|
||||
- vendor/*
|
||||
```
|
||||
|
||||
This configuration disables optimization for all media files that are contained
|
||||
in the `vendor` folder and its subfolders inside the [`docs` directory]
|
||||
[mkdocs.docs_dir].
|
||||
|
||||
### Reporting
|
||||
|
||||
The following settings are available for reporting:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.print_gain -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to control whether the plugin should print the number of bytes
|
||||
gained after optimizing each file. If you want to disable this behavior, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
print_gain: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.print_gain_summary -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to control whether the plugin should print the total number of
|
||||
bytes gained after optimizing all files. If you want to disable this behavior,
|
||||
use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- optimize:
|
||||
print_gain_summary: false
|
||||
```
|
||||
@@ -0,0 +1,497 @@
|
||||
---
|
||||
title: Built-in privacy plugin
|
||||
icon: material/shield-account
|
||||
---
|
||||
|
||||
|
||||
# Built-in privacy plugin
|
||||
|
||||
The privacy plugin offers a streamlined solution for automatically self-hosting
|
||||
external assets. With just a single line of configuration, the plugin can
|
||||
automatically identify and download external assets, making GDPR compliance
|
||||
as effortless as it can possibly be.
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin scans the generated HTML for external assets, i.e., scripts, style
|
||||
sheets, images, and web fonts, downloads them, stores them in the
|
||||
[`site` directory][mkdocs.site_dir] and replaces all references with links to
|
||||
the downloaded copies for effortless self-hosting. For example:
|
||||
|
||||
``` html
|
||||
<script src="https://example.com/script.js"></script>
|
||||
```
|
||||
|
||||
This external script is downloaded, and the link is replaced with:
|
||||
|
||||
``` html
|
||||
<script src="assets/external/example.com/script.js"></script>
|
||||
```
|
||||
|
||||
Of course, scripts and style sheets can reference further external assets,
|
||||
which is why this process is repeated recursively until no further external
|
||||
assets are detected:
|
||||
|
||||
- Scripts are scanned for further scripts, style sheets and JSON files
|
||||
- Style sheets are scanned for images and web fonts
|
||||
|
||||
Additionally, hints like [`preconnect`][preconnect], used to reduce latency when
|
||||
requesting external assets, are removed from the output, as they're not
|
||||
necessary when self-hosting. After the plugin has done its work, your project
|
||||
will be free of requests to external services.
|
||||
|
||||
There are some [limitations].
|
||||
|
||||
[preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect
|
||||
[limitations]: #limitations
|
||||
|
||||
### When to use it
|
||||
|
||||
The plugin was developed to make compliance with the 2018 European
|
||||
__General Data Protection Regulation__ (GDPR) as simple as possible, while
|
||||
retaining the flexibility and power that Material for MkDocs offers, like for
|
||||
example its tight integration with [Google Fonts].
|
||||
|
||||
But, that's only the start. For example, if your project includes a lot of
|
||||
images, enabling the plugin allows to move them outside of your repository, as
|
||||
the plugin will automatically download and store them in the [`site` directory]
|
||||
[mkdocs.site_dir] when [building your project].
|
||||
|
||||
Even more interestingly, the plugin can be combined with other built-in plugins
|
||||
that Material for MkDocs offers, in order to create sophisticated build
|
||||
pipelines tailored to your project:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-rabbit: __[Built-in optimize plugin][optimize]__
|
||||
|
||||
---
|
||||
|
||||
The optimize plugin allows to optimize all downloaded external assets
|
||||
detected by the privacy plugin by using compression and conversion
|
||||
techniques.
|
||||
|
||||
---
|
||||
|
||||
__External media files are automatically downloaded and optimized__
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building [offline-capable documentation],
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet__
|
||||
|
||||
</div>
|
||||
|
||||
[Google Fonts]: ../setup/changing-the-fonts.md
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
[optimize]: optimize.md
|
||||
[offline]: offline.md
|
||||
[offline-capable documentation]: ../setup/building-for-offline-usage.md
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:plugin [privacy] – built-in -->
|
||||
<!-- md:flag multiple -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
As with all [built-in plugins], getting started with the privacy plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and start
|
||||
effortlessly self-hosting external assets:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy
|
||||
```
|
||||
|
||||
The privacy plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[privacy]: privacy.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
If you want to disable the plugin, e.g., for local builds, you can use an
|
||||
[environment variable][mkdocs.env] in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
This configuration enables the plugin only during continuous integration (CI).
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.concurrency -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default available CPUs - 1 -->
|
||||
|
||||
With more CPUs available, the plugin can do more work in parallel, and thus
|
||||
complete handling of external assets faster. If you want to disable concurrent
|
||||
processing completely, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
concurrency: 1
|
||||
```
|
||||
|
||||
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
|
||||
|
||||
### Caching
|
||||
|
||||
The plugin implements an [intelligent caching] mechanism, ensuring that external
|
||||
assets are only downloaded when they're not already contained in the cache.
|
||||
While the initial build might take some time, it's a good idea to use caching,
|
||||
as it will speed up consecutive builds.
|
||||
|
||||
The following settings are available for caching:
|
||||
|
||||
[intelligent caching]: requirements/caching.md
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.cache -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to instruct the plugin to bypass the cache, in order to
|
||||
re-schedule downloads for all external assets, even though the cache may not be
|
||||
stale. It's normally not necessary to specify this setting, except for when
|
||||
debugging the plugin itself. Caching can be disabled with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
cache: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.cache_dir -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default `.cache/plugin/privacy` -->
|
||||
|
||||
It is normally not necessary to specify this setting, except for when you want
|
||||
to change the path within your root directory where downloaded copies are
|
||||
cached. If you want to change it, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
cache_dir: my/custom/dir
|
||||
```
|
||||
|
||||
If you're using [multiple instances] of the plugin, it can be a good idea to
|
||||
set different cache directories for both instances, so that they don't interfere
|
||||
with each other.
|
||||
|
||||
[multiple instances]: index.md#multiple-instances
|
||||
|
||||
### Logging
|
||||
|
||||
The following settings are available for logging:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.log -->
|
||||
|
||||
<!-- md:version 9.7.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:version 9.7.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:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.assets -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to control whether the plugin should download external
|
||||
assets. If you only want the plugin to process [external links], you can disable
|
||||
handling of external assets with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
assets: false
|
||||
```
|
||||
|
||||
[external links]: #external-links
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.assets_fetch -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to control whether the plugin should downloads or only report
|
||||
external assets when they're encountered. If you already self-host all external
|
||||
assets, this setting can be used as a safety net to detect links to external
|
||||
assets placed by the author in pages:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
assets_fetch: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.assets_fetch_dir -->
|
||||
|
||||
<!-- md:version 9.5.0 -->
|
||||
<!-- md:default `assets/external` -->
|
||||
|
||||
It is normally not necessary to specify this setting, except for when you want
|
||||
to change the path within the [`site` directory][mkdocs.site_dir] where
|
||||
external assets are stored. If you want to change it, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
assets_fetch_dir: my/custom/dir
|
||||
```
|
||||
|
||||
This configuration stores the downloaded copies at `my/custom/dir` in the
|
||||
[`site` directory][mkdocs.site_dir].
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.assets_include -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to enable downloading of external assets for specific origins,
|
||||
e.g., when using [multiple instances] of the plugin to fine-tune processing of
|
||||
external assets for different origins:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
assets_include:
|
||||
- unsplash.com/*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.assets_exclude -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to disable downloading of external assets for specific origins,
|
||||
e.g., when using [multiple instances] of the plugin to fine-tune processing of
|
||||
external assets for different origins:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
assets_exclude: # (1)!
|
||||
- unpkg.com/mathjax@3/*
|
||||
- giscus.app/*
|
||||
```
|
||||
|
||||
1. [MathJax] loads web fonts for typesetting of mathematical content
|
||||
through relative URLs, and thus cannot be automatically bundled by the
|
||||
privacy plugin. [MathJax can be self-hosted].
|
||||
|
||||
[Giscus], which we recommend to use as a [comment system], uses a technique
|
||||
called code-splitting to load only the code that is necessary, which
|
||||
is implemented via relative URLs. [Giscus can be self-hosted] as well.
|
||||
|
||||
[MathJax]: ../reference/math.md
|
||||
[MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
|
||||
[Giscus]: https://giscus.app/
|
||||
[comment system]: ../setup/adding-a-comment-system.md
|
||||
[Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
|
||||
|
||||
---
|
||||
|
||||
### External links
|
||||
|
||||
The following settings are available for external links:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.links -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to instruct the plugin to parse and process external links to
|
||||
annotate them for [improved security], or to automatically add additional
|
||||
attributes to external links. If you want to disable processing of external
|
||||
links, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
links: false
|
||||
```
|
||||
|
||||
[improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.links_attr_map -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to specify additional attributes that should be added to
|
||||
external links, for example, to add `target="_blank"` to all external links
|
||||
so they open in a new tab:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
links_attr_map:
|
||||
target: _blank
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.links_noopener -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
It is normally not recommended to change this setting, as it will automatically
|
||||
annotate external links that open in a new window with `rel="noopener"` for
|
||||
[improved security]:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- privacy:
|
||||
links_noopener: true
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
### Dynamic URLs
|
||||
|
||||
Dynamically created URLs as part of scripts are not detected, and thus cannot be
|
||||
downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
|
||||
|
||||
``` js
|
||||
const host = "https://example.com"
|
||||
const path = `${host}/script.js`
|
||||
```
|
||||
|
||||
Instead, always use fully qualified URLs:
|
||||
|
||||
``` js
|
||||
const url ="https://example.com/script.js"
|
||||
```
|
||||
|
||||
### Embedded HTML
|
||||
|
||||
By default, embedded HTML files (e.g. in iframes) are not scanned for external
|
||||
assets. This is a limitation of MkDocs, as it considers `.html` files to be
|
||||
templates, which must be explicitly listed under
|
||||
[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets
|
||||
of an embedded HTML file:
|
||||
|
||||
``` yaml
|
||||
extra_templates:
|
||||
- iframe.html
|
||||
```
|
||||
|
||||
Note that the path to `iframe.html` is relative to the
|
||||
[`docs_dir`][mkdocs.docs_dir] directory.
|
||||
@@ -0,0 +1,444 @@
|
||||
---
|
||||
title: Built-in projects plugin
|
||||
icon: material/folder-open
|
||||
status: deprecated
|
||||
---
|
||||
|
||||
# Built-in projects plugin
|
||||
|
||||
The projects plugin adds the ability to split your main project into multiple
|
||||
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.
|
||||
|
||||
!!! bug "The built-in projects plugin is deprecated"
|
||||
|
||||
[Material for MkDocs is in maintenance mode]. The projects plugin, which was
|
||||
formely part of the [Insiders] edition, was released in <!-- md:version 9.7.0 -->, the last release that includes all features from the Insiders edition.
|
||||
Unfortunately, the projects plugin turned out impossible to maintain, and
|
||||
was one of the key motivators to create [Zensical].
|
||||
|
||||
---
|
||||
|
||||
__If you're considering the projects plugin, please be aware that known issues will <u>not</u> be fixed.__
|
||||
|
||||
[Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523
|
||||
[Zensical]: ../blog/posts/zensical.md
|
||||
[Insiders]: ../insiders/index.md
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin scans the configured [`projects` directory][config.projects_dir] for
|
||||
`mkdocs.yml` files, identifies all nested projects and builds them concurrently.
|
||||
If not configured otherwise, the plugin expects that your project has
|
||||
the following directory layout, e.g. for a multi-language project:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ docs/
|
||||
├─ projects/
|
||||
│ ├─ en/
|
||||
│ │ ├─ docs/
|
||||
│ │ └─ mkdocs.yml
|
||||
│ └─ de/
|
||||
│ ├─ docs/
|
||||
│ └─ mkdocs.yml
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
One of the most useful and interesting features of the plugin is that it allows
|
||||
[previewing your site] from the main project, while still being able to preview
|
||||
and build each project individually. This is especially useful for
|
||||
multi-language projects.
|
||||
|
||||
If, when [previewing your site], you change a file in one of the projects, the
|
||||
plugin only rebuilds this project and makes sure that MkDocs will also reload
|
||||
the associated files. This also creates the opportunity for splitting your
|
||||
main project into several projects for a better editing experience.
|
||||
|
||||
There are some [limitations], but we're working hard to remove them.
|
||||
|
||||
[previewing your site]: ../creating-your-site.md#previewing-as-you-write
|
||||
[limitations]: #limitations
|
||||
|
||||
### When to use it
|
||||
|
||||
The plugin came into existence because we needed a convenient and scalable
|
||||
method to build our [examples] repository, which features many self-contained
|
||||
and runnable projects that users can download and use as a basis when
|
||||
bootstrapping a new project or [creating a reproduction].
|
||||
|
||||
When you want to create a multi-language project, or have a very large existing
|
||||
project, you might consider using the plugin, as it makes managing, editing
|
||||
and building more comfortable.
|
||||
|
||||
[examples]: https://github.com/mkdocs-material/examples
|
||||
[creating a reproduction]: ../guides/creating-a-reproduction.md
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:plugin [projects] – built-in -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
In order to get started with the projects plugin, just add the following lines
|
||||
to `mkdocs.yml`, and split your main project into several distinct projects that
|
||||
can be built concurrently:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects
|
||||
```
|
||||
|
||||
The projects plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[projects]: projects.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
If you want to disable the plugin, e.g., for local builds, you can use an
|
||||
[environment variable][mkdocs.env] in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
enabled: !ENV [CI, false]
|
||||
```
|
||||
|
||||
This configuration enables the plugin only during continuous integration (CI).
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.concurrency -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default available CPUs - 1 -->
|
||||
|
||||
With more CPUs available, the plugin can do more work in parallel, and thus
|
||||
build projects faster. If you want to disable concurrent processing completely,
|
||||
use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
concurrency: 1
|
||||
```
|
||||
|
||||
By default, the plugin uses all available CPUs - 1 with a minimum of 1.
|
||||
|
||||
### Caching
|
||||
|
||||
The plugin implements an [intelligent caching] mechanism, ensuring that a
|
||||
project is only rebuilt when its contents change. While the initial build might
|
||||
take some time, it's a good idea to use caching, as it will speed up consecutive
|
||||
builds.
|
||||
|
||||
The following settings are available for caching:
|
||||
|
||||
[intelligent caching]: requirements/caching.md
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.cache -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to instruct the plugin to bypass the cache, in order to
|
||||
rebuild all projects, even though the cache may not be stale. It's normally not
|
||||
necessary to specify this setting, except for when debugging the plugin itself.
|
||||
Caching can be disabled with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
cache: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.cache_dir -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `.cache/plugin/projects` -->
|
||||
|
||||
It is normally not necessary to specify this setting, except for when you want
|
||||
to change the path within your root directory where the metadata is cached.
|
||||
If you want to change it, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
cache_dir: my/custom/dir
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
The following settings are available for logging:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.log -->
|
||||
|
||||
<!-- md:version 9.7.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:version 9.7.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:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.projects -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable building of projects. Currently, the
|
||||
plugin's sole purpose is to build projects, so it's equivalent to the
|
||||
[`enabled`][config.enabled] setting, but in the future, other features might be
|
||||
added. If you want to disable building of projects, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
projects: false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.projects_dir -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `projects` -->
|
||||
|
||||
Use this setting to change the folder where your projects are located. It's
|
||||
normally not necessary to change this setting, but if you want to rename the
|
||||
folder or change its file system location, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
projects_dir: projects
|
||||
```
|
||||
|
||||
Note that the [`projects` directory][config.projects_dir] is solely used for
|
||||
project organization – it is not included in project URLs, since projects are
|
||||
automatically hoisted by the plugin.
|
||||
|
||||
The provided path is resolved from the root directory.
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.projects_config_files -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `*/mkdocs.yml` -->
|
||||
|
||||
Use this setting to change the location or name of configuration files the
|
||||
plugin will look for when scanning the [`projects` directory]
|
||||
[config.projects_dir]. Adjusting this setting can be necessary when the
|
||||
configuration files are located in subdirectories of projects, e.g.
|
||||
`docs/mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
projects_config_files: "**/mkdocs.yml" # (1)!
|
||||
```
|
||||
|
||||
1. If all projects share the same location for their configuration files, e.g.,
|
||||
`docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster
|
||||
to resolve than a `**` glob pattern.
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
projects_config_files: "*/docs/mkdocs.yml"
|
||||
```
|
||||
|
||||
This configuration fits the following directory structure, which is quite
|
||||
common for projects using git submodules:
|
||||
|
||||
``` { .sh .no-copy }
|
||||
.
|
||||
├─ docs/
|
||||
├─ projects/
|
||||
│ ├─ git-submodule-a/
|
||||
│ │ └─ docs/
|
||||
│ │ └─ mkdocs.yml
|
||||
│ └─ git-submodule-b/
|
||||
│ └─ docs/
|
||||
│ └─ mkdocs.yml
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
The provided path is resolved from the [`projects` directory]
|
||||
[config.projects_dir].
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.projects_config_transform -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this setting to transform the configuration of each project as read from
|
||||
`mkdocs.yml` before it is built, which allows for adjusting the configuration
|
||||
of each project when building them together, but leave them untouched when
|
||||
building them individually:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
projects_config_transform: !!python/name:projects.transform
|
||||
```
|
||||
|
||||
The provided module and function name are looked up in Python's [module search
|
||||
path]. You need to add your root directory to the search path when building
|
||||
your site, so Python can resolve it. The easiest way is to add the working
|
||||
directory to the [`PYTHONPATH`][PYTHONPATH] environment variable:
|
||||
|
||||
``` .sh
|
||||
export PYTHONPATH=.
|
||||
```
|
||||
|
||||
!!! tip "How to define a configuration transformation function"
|
||||
|
||||
The [`python/name`][python-name] tag is provided by [PyYAML] and must point
|
||||
to a valid module and function name within Python's [module search path].
|
||||
The plugin passes the `project` and top-level `config` objects to the
|
||||
function.
|
||||
|
||||
As an example, we can inherit the [`use_directory_urls`]
|
||||
[mkdocs.use_directory_urls] setting for all projects from the top-level
|
||||
configuration:
|
||||
|
||||
``` py title="projects/__init__.py"
|
||||
from mkdocs.config.defaults import MkDocsConfig
|
||||
|
||||
# Transform project configuration
|
||||
def transform(project: MkDocsConfig, config: MkDocsConfig):
|
||||
project.use_directory_urls = config.use_directory_urls
|
||||
```
|
||||
|
||||
[module search path]: https://docs.python.org/3/library/sys_path_init.html
|
||||
[PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
|
||||
[python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
|
||||
[PyYAML]: https://pyyaml.org/
|
||||
|
||||
### Hoisting
|
||||
|
||||
The following settings are available for hoisting:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.hoisting -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable hoisting of themes files to the main
|
||||
project. If you disable this setting, each project receives a copy of the
|
||||
theme's files, which can be considered redundant:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- projects:
|
||||
hoisting: false
|
||||
```
|
||||
|
||||
It's generally advisable to enable hoisting, as it yields faster deployments
|
||||
and faster loading of your project's sites, because the files are the same for
|
||||
all projects and can be deduplicated.
|
||||
|
||||
### Limitations
|
||||
|
||||
The plugin is one of the latest additions to Material for MkDocs, which means it
|
||||
is rather young and has some limitations. We're working hard to remove them, and
|
||||
we're happy to receive feedback and learn about your requirements in ?5800.
|
||||
Current limitations are:
|
||||
|
||||
- __Basic multi-language support only__: we'll be investigating how to provide
|
||||
better support for multi-language projects, allowing to easier interlink
|
||||
projects and switch between them.
|
||||
|
||||
- __Separate search indexes and sitemaps__: currently, the projects are entirely
|
||||
separate, which means they will have separate search indexes and sitemaps.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
icon: material/database-outline
|
||||
---
|
||||
|
||||
# Caching
|
||||
|
||||
Some of the [built-in plugins] implement intelligent caching mechanisms, which
|
||||
massively speed up consecutive builds by reducing the amount of work that needs
|
||||
to be done. This guide explains how to configure caching in different
|
||||
environments.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Caching is entirely optional but enabled by default. It can be disabled per
|
||||
plugin. If not configured otherwise, plugins will cache their data in the
|
||||
`.cache` folder in the root of your project. For this reason it's recommended
|
||||
to create a `.gitignore` file in the root of your project:
|
||||
|
||||
``` title=".gitignore"
|
||||
.cache
|
||||
```
|
||||
|
||||
This ensures that cached files are not added to your git repository – something
|
||||
that is generally not recommended to do unless absolutely necessary. In some
|
||||
cases, you might need to check in cached files, e.g. when you need to
|
||||
pre-generate [social cards] locally, e.g., when you're not be able to install
|
||||
the image processing dependencies in your continuous integration (CI)
|
||||
environment.
|
||||
|
||||
In this case, we recommend changing the `cache_dir` setting – something that all
|
||||
plugins that implement caching share – to a folder which you add to your git
|
||||
repository.
|
||||
|
||||
[built-in plugins]: ../index.md
|
||||
[social cards]: ../../setup/setting-up-social-cards.md
|
||||
@@ -0,0 +1,272 @@
|
||||
---
|
||||
icon: material/image-sync-outline
|
||||
---
|
||||
|
||||
# Image processing
|
||||
|
||||
Some of the [built-in plugins] depend on external libraries for efficient image
|
||||
processing, most notably the [social] plugin to generate [social cards], and the
|
||||
[optimize] plugin for applying [image optimization]. This guide explains how to
|
||||
install those libraries in different environments.
|
||||
|
||||
[built-in plugins]: ../index.md
|
||||
[social]: ../social.md
|
||||
[social cards]: ../../setup/setting-up-social-cards.md
|
||||
[optimize]: ../optimize.md
|
||||
[image optimization]: ../../setup/building-an-optimized-site.md
|
||||
|
||||
## Dependencies
|
||||
|
||||
The libraries for image processing are entirely optional, and only need to be
|
||||
installed if you want to use the [social] plugin or the [optimize] plugin. The
|
||||
libraries are listed under the `imaging` extra:
|
||||
|
||||
```
|
||||
pip install "mkdocs-material[imaging]"
|
||||
```
|
||||
|
||||
This will install compatible versions of the following packages:
|
||||
|
||||
- [Pillow]
|
||||
- [CairoSVG]
|
||||
|
||||
[Pillow]: https://pillow.readthedocs.io/
|
||||
[CairoSVG]: https://cairosvg.org/
|
||||
|
||||
### Cairo Graphics
|
||||
|
||||
[Cairo Graphics] is a graphics library and dependency of [Pillow], which
|
||||
Material for MkDocs makes use of for generating [social cards] and performing
|
||||
[image optimization]. See the following section which explains how to install
|
||||
[Cairo Graphics] and its dependencies on your system:
|
||||
|
||||
=== ":material-apple: macOS"
|
||||
|
||||
Make sure [Homebrew] is installed, which is a modern package manager for
|
||||
macOS. Next, use the following command to install all necessary
|
||||
dependencies:
|
||||
|
||||
```
|
||||
brew install cairo freetype libffi libjpeg libpng zlib
|
||||
```
|
||||
|
||||
=== ":fontawesome-brands-windows: Windows"
|
||||
|
||||
The easiest way to get up and running with the [Cairo Graphics] library is
|
||||
by installing it via [MSYS2], which is a software distribution and building
|
||||
platform for Windows. Run the following command inside of a MSYS2 shell:
|
||||
|
||||
```
|
||||
pacman -S mingw-w64-ucrt-x86_64-cairo
|
||||
```
|
||||
|
||||
MSYS2 provides the Cairo Graphics library in several different environments.
|
||||
The above command uses the [UCRT64] environment, as recommended by the MSYS2
|
||||
developers.
|
||||
|
||||
=== ":material-linux: Linux"
|
||||
|
||||
There are several package managers for Linux with varying availability per
|
||||
distribution. The [installation guide] explains how to install the [Cairo
|
||||
Graphics] library for your distribution:
|
||||
|
||||
=== ":material-ubuntu: Ubuntu"
|
||||
|
||||
```
|
||||
apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
|
||||
```
|
||||
|
||||
=== ":material-fedora: Fedora"
|
||||
|
||||
```
|
||||
yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
|
||||
```
|
||||
|
||||
=== ":fontawesome-brands-suse: openSUSE"
|
||||
|
||||
```
|
||||
zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
|
||||
```
|
||||
|
||||
The following environments come with a preinstalled version of [Cairo Graphics]:
|
||||
|
||||
- [x] No installation needed in [Docker image]
|
||||
- [x] No installation needed in [GitHub Actions] (Ubuntu)
|
||||
|
||||
[Cairo Graphics]: https://www.cairographics.org/
|
||||
[Homebrew]: https://brew.sh/
|
||||
[installation guide]: https://www.cairographics.org/download/
|
||||
[MSYS2]: https://www.msys2.org/
|
||||
[UCRT64]: https://www.msys2.org/docs/environments/
|
||||
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[GitHub Actions]: ../../publishing-your-site.md#with-github-actions
|
||||
|
||||
### pngquant
|
||||
|
||||
[pngquant] is an excellent library for lossy PNG compression, and a direct
|
||||
dependency of the [built-in optimize plugin]. See the following section which
|
||||
explains how to install [pngquant] system:
|
||||
|
||||
=== ":material-apple: macOS"
|
||||
|
||||
Make sure [Homebrew] is installed, which is a modern package manager for
|
||||
macOS. Next, use the following command to install all necessary
|
||||
dependencies:
|
||||
|
||||
```
|
||||
brew install pngquant
|
||||
```
|
||||
|
||||
=== ":fontawesome-brands-windows: Windows"
|
||||
|
||||
The easiest way to get [pngquant] is by installing it via [MSYS2], which is
|
||||
a software distribution and building platform for Windows. Run the following
|
||||
command inside of a MSYS2 shell:
|
||||
|
||||
```
|
||||
pacman -S mingw-w64-ucrt-x86_64-pngquant
|
||||
```
|
||||
|
||||
=== ":material-linux: Linux"
|
||||
|
||||
All popular Linux distributions, regardless of package manager, should
|
||||
allow to install [pngquant] with the bundled package manager. For example,
|
||||
on Ubuntu, [pngquant] can be installed with:
|
||||
|
||||
```
|
||||
apt-get install pngquant
|
||||
```
|
||||
|
||||
The same is true for `yum` and `zypper`.
|
||||
|
||||
The following environments come with a preinstalled version of [pngquant]:
|
||||
|
||||
- [x] No installation needed in [Docker image]
|
||||
|
||||
[pngquant]: https://pngquant.org/
|
||||
[built-in optimize plugin]: ../../plugins/optimize.md
|
||||
[pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Cairo library was not found
|
||||
|
||||
After following the installation guide above it may happen that you still get
|
||||
the following error:
|
||||
|
||||
```bash
|
||||
no library called "cairo-2" was found
|
||||
no library called "cairo" was found
|
||||
no library called "libcairo-2" was found
|
||||
cannot load library 'libcairo.so.2': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
|
||||
cannot load library 'libcairo.2.dylib': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
|
||||
cannot load library 'libcairo-2.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
|
||||
```
|
||||
|
||||
This means that the [`cairosvg`][PyPi CairoSVG] package was installed, but the
|
||||
underlying [`cairocffi`][PyPi CairoCFFI] dependency couldn't [find][cffi-dopen]
|
||||
the installed library. Depending on the operating system the library lookup
|
||||
process is different:
|
||||
|
||||
!!! tip
|
||||
Before proceeding remember to fully restart any open Terminal windows, and
|
||||
their parent hosts like IDEs to reload any environmental variables, which
|
||||
were altered during the installation process. This might be the quick fix.
|
||||
|
||||
=== ":material-apple: macOS"
|
||||
|
||||
On macOS the library lookup checks inside paths defined in [dyld][osx-dyld].
|
||||
Additionally each library `name` is checked in [three variants][find-library-macOS]
|
||||
with the `libname.dylib`, `name.dylib` and `name.framework/name` format.
|
||||
|
||||
[Homebrew] should set every needed variable to point at the installed
|
||||
library directory, but if that didn't happen, you can use the debug script
|
||||
below to see what paths are looked up.
|
||||
|
||||
A [known workaround][cffi-issue] is to add the Homebrew lib path directly
|
||||
before running MkDocs:
|
||||
|
||||
```bash
|
||||
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
|
||||
```
|
||||
|
||||
View source code of [cairo-lookup-macos.py]
|
||||
|
||||
```bash title="Python Debug macOS Script"
|
||||
curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py" | python -
|
||||
```
|
||||
|
||||
=== ":fontawesome-brands-windows: Windows"
|
||||
|
||||
On Windows the library lookup checks inside the paths defined in the
|
||||
environmental `PATH` variable. Additionally each library `name` is checked
|
||||
in [two variants][find-library-Windows] with the `name` and `name.dll` format.
|
||||
|
||||
The default binary and shared library path for the [UCRT64] environment of
|
||||
[MSYS2], in which the packages were installed using the above commands, is:
|
||||
|
||||
```powershell
|
||||
C:\msys64\ucrt64\bin
|
||||
```
|
||||
|
||||
Use the debug script below to check if the path is included. If it isn't then:
|
||||
|
||||
1. Press ++windows+r++.
|
||||
2. Run the `SystemPropertiesAdvanced` applet.
|
||||
3. Select "Environmental Variables" at the bottom.
|
||||
4. Add the whole path to the above directory to your `Path` variable.
|
||||
5. Click OK on all open windows to apply changes.
|
||||
6. Fully restart any open Terminal windows and their parent hosts like IDEs.
|
||||
|
||||
```powershell title="You can also list paths using PowerShell"
|
||||
$env:Path -split ';'
|
||||
```
|
||||
|
||||
View source code of [cairo-lookup-windows.py]
|
||||
|
||||
```powershell title="PowerShell - Python Debug Windows Script"
|
||||
(Invoke-WebRequest "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py").Content | python -
|
||||
```
|
||||
|
||||
=== ":material-linux: Linux"
|
||||
|
||||
On Linux the library lookup can [differ greatly][find-library-Linux] and is
|
||||
dependent from the installed distribution. For tested Ubuntu and Manjaro
|
||||
systems Python runs shell commands to check which libraries are available in
|
||||
[`ldconfig`][ubuntu-ldconfig], in the [`gcc`][ubuntu-gcc]/`cc` compiler, and
|
||||
in [`ld`][ubuntu-ld].
|
||||
|
||||
You can extend the `LD_LIBRARY_PATH` environmental variable with an absolute
|
||||
path to a library directory containing `libcairo.so` etc. Run this directly
|
||||
before MkDocs:
|
||||
|
||||
```bash
|
||||
export LD_LIBRARY_PATH=/absolute/path/to/lib:$LD_LIBRARY_PATH
|
||||
```
|
||||
|
||||
You can also modify the `/etc/ld.so.conf` file.
|
||||
|
||||
The Python script below shows, which function is being run to find installed
|
||||
libraries. You can check the source to find out what specific commands are
|
||||
executed on your system during library lookup.
|
||||
|
||||
View source code of [cairo-lookup-linux.py]
|
||||
|
||||
```bash title="Python Debug Linux Script"
|
||||
curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py" | python -
|
||||
```
|
||||
|
||||
[PyPi CairoSVG]: https://pypi.org/project/CairoSVG
|
||||
[PyPi CairoCFFI]: https://pypi.org/project/CairoCFFI
|
||||
[osx-dyld]: https://www.unix.com/man-page/osx/1/dyld/
|
||||
[ubuntu-ldconfig]: https://manpages.ubuntu.com/manpages/focal/en/man8/ldconfig.8.html
|
||||
[ubuntu-ld]: https://manpages.ubuntu.com/manpages/xenial/man1/ld.1.html
|
||||
[ubuntu-gcc]: https://manpages.ubuntu.com/manpages/trusty/man1/gcc.1.html
|
||||
[cffi-issue]: https://github.com/squidfunk/mkdocs-material/issues/5121
|
||||
[cffi-dopen]: https://github.com/Kozea/cairocffi/blob/f1984d644bbc462ef0ec33b97782cf05733d7b53/cairocffi/__init__.py#L24-L49
|
||||
[find-library-macOS]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L70-L81
|
||||
[find-library-Windows]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L59-L67
|
||||
[find-library-Linux]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L92
|
||||
[cairo-lookup-macos.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py
|
||||
[cairo-lookup-windows.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py
|
||||
[cairo-lookup-linux.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py
|
||||
@@ -0,0 +1,427 @@
|
||||
---
|
||||
title: Built-in search plugin
|
||||
icon: material/magnify
|
||||
---
|
||||
|
||||
# Built-in search plugin
|
||||
|
||||
The search plugin adds a search bar to the header, allowing users to search your
|
||||
documentation. It's powered by [lunr.js], a lightweight full-text search engine
|
||||
for the browser, elimininating the need for external services, and even works
|
||||
when building [offline-capable documentation].
|
||||
|
||||
[lunr.js]: https://lunrjs.com/
|
||||
[offline-capable documentation]: ../setup/building-for-offline-usage.md
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin scans the generated HTML and builds a search index from all pages and
|
||||
sections by extracting the section titles and contents. It preserves some inline
|
||||
formatting like code blocks and lists, but removes all other formatting, so the
|
||||
search index is as small as possible.
|
||||
|
||||
When a user visits your site, the search index is shipped to the browser,
|
||||
indexed with [lunr.js] and made available for fast and simple querying – no
|
||||
server needed. This ensures that the search index is always up to date with
|
||||
your documentation, yielding accurate results.
|
||||
|
||||
### When to use it
|
||||
|
||||
It's generally recommended to use the plugin, as interactive search functionality
|
||||
is a vital part of every good documentation. Additionally, the plugin integrates
|
||||
perfectly with several of the other [built-in plugins] that Material for MkDocs
|
||||
offers:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-connection: __[Built-in offline plugin][offline]__
|
||||
|
||||
---
|
||||
|
||||
The offline plugin adds support for building offline-capable documentation,
|
||||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||||
file that can be downloaded.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation can work without connectivity to the internet__
|
||||
|
||||
- :material-file-tree: __[Built-in meta plugin][meta]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it easy to [boost][meta.search.boost] specific
|
||||
sections in search results or to [exclude][meta.search.exclude] them
|
||||
entirely from being indexed, giving more granular control over search.
|
||||
|
||||
---
|
||||
|
||||
__Simpler organization and management of search in different subsections__
|
||||
|
||||
</div>
|
||||
|
||||
[offline]: offline.md
|
||||
[meta]: meta.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:plugin [search] – built-in -->
|
||||
|
||||
As with all [built-in plugins], getting started with the search plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and your users
|
||||
will be able to search your documentation:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search
|
||||
```
|
||||
|
||||
The search plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[search]: search.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.3.2 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
It's normally not necessary to specify this setting, but if you want to disable
|
||||
the plugin, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
### Search
|
||||
|
||||
The following settings are available for search:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.lang -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default computed -->
|
||||
|
||||
Use this setting to specify the language of the search index, enabling [stemming]
|
||||
support for other languages than English. The default value is automatically
|
||||
computed from the [site language], but can be explicitly set to another language
|
||||
or even multiple languages with:
|
||||
|
||||
=== "Set language"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
lang: en
|
||||
```
|
||||
|
||||
=== "Add further languages"
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
lang: # (1)!
|
||||
- en
|
||||
- de
|
||||
```
|
||||
|
||||
1. Be aware that including support for further languages increases the
|
||||
base JavaScript payload by around 20kb and by another 15-30kb per
|
||||
language, all before `gzip`.
|
||||
|
||||
[stemming]: https://en.wikipedia.org/wiki/Stemming
|
||||
[site language]: ../setup/changing-the-language.md#site-language
|
||||
[lunr languages]: https://github.com/MihaiValentin/lunr-languages
|
||||
|
||||
Language support is provided by [lunr languages], a collection of
|
||||
language-specific stemmers and stop words for [lunr.js] maintained by the
|
||||
Open Source community.
|
||||
|
||||
---
|
||||
|
||||
The following languages are currently supported by [lunr languages]:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- `ar` – Arabic
|
||||
- `da` – Danish
|
||||
- `de` – German
|
||||
- `du` – Dutch
|
||||
- `en` – English
|
||||
- `es` – Spanish
|
||||
- `fi` – Finnish
|
||||
- `fr` – French
|
||||
- `hi` – Hindi
|
||||
- `hu` – Hungarian
|
||||
- `hy` – Armenian
|
||||
- `it` – Italian
|
||||
- `ja` – Japanese
|
||||
- `kn` - Kannada
|
||||
- `ko` – Korean
|
||||
- `no` – Norwegian
|
||||
- `pt` – Portuguese
|
||||
- `ro` – Romanian
|
||||
- `ru` – Russian
|
||||
- `sa` – Sanskrit
|
||||
- `sv` – Swedish
|
||||
- `ta` – Tamil
|
||||
- `te` – Telugu
|
||||
- `th` – Thai
|
||||
- `tr` – Turkish
|
||||
- `vi` – Vietnamese
|
||||
- `zh` – Chinese
|
||||
|
||||
</div>
|
||||
|
||||
If [lunr languages] doesn't provide support for the selected [site language],
|
||||
the plugin falls back to another language that yields the best stemming results.
|
||||
If you discover that the search results are not satisfactory, you can contribute
|
||||
to [lunr languages] by adding support for your language.
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.separator -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default computed -->
|
||||
|
||||
Use this setting to specify the separator used to split words when building the
|
||||
search index on the client side. The default value is automatically computed
|
||||
from the [site language], but can also be explicitly set to another value with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
|
||||
```
|
||||
|
||||
Separators support [positive and negative lookahead assertions], which allows
|
||||
for rather complex expressions that yield precise control over how words are
|
||||
split when building the search index.
|
||||
|
||||
Broken into its parts, this separator induces the following behavior:
|
||||
|
||||
=== "Special characters"
|
||||
|
||||
```
|
||||
[\s\-,:!=\[\]()"/]+
|
||||
```
|
||||
|
||||
The first part of the expression inserts token boundaries for each
|
||||
document before and after whitespace, hyphens, commas, brackets and
|
||||
other special characters. If several of those special characters are
|
||||
adjacent, they are treated as one.
|
||||
|
||||
=== "Case changes"
|
||||
|
||||
```
|
||||
(?!\b)(?=[A-Z][a-z])
|
||||
```
|
||||
|
||||
Many programming languages have naming conventions like `PascalCase` or
|
||||
`camelCase`. By adding this subexpression to the separator,
|
||||
[words are split at case changes], tokenizing the word `PascalCase`
|
||||
into `Pascal` and `Case`.
|
||||
|
||||
=== "Version strings"
|
||||
|
||||
```
|
||||
\.(?!\d)
|
||||
```
|
||||
|
||||
When adding `.` to the separator, version strings like `1.2.3` are split
|
||||
into `1`, `2` and `3`, which makes them undiscoverable via search. When
|
||||
using this subexpression, a small lookahead is introduced which will
|
||||
[preserve version strings] and keep them discoverable.
|
||||
|
||||
=== "HTML/XML tags"
|
||||
|
||||
```
|
||||
&[lg]t;
|
||||
```
|
||||
|
||||
If your documentation includes HTML/XML code examples, you may want to allow
|
||||
users to find [specific tag names]. Unfortunately, the `<` and `>` control
|
||||
characters are encoded in code blocks as `<` and `>`. Adding this
|
||||
subexpression to the separator allows for just that.
|
||||
|
||||
[positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
|
||||
[words are split at case changes]: ?q=searchHighlight
|
||||
[preserve version strings]: ?q=9.0.0
|
||||
[specific tag names]: ?q=script
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.pipeline -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:default computed -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Use this setting to specify the [pipeline functions] that are used to filter and
|
||||
expand tokens after tokenizing them with the [`separator`][config.separator] and
|
||||
before adding them to the search index. The default value is automatically
|
||||
computed from the [site language], but can also be explicitly set with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
pipeline:
|
||||
- stemmer
|
||||
- stopWordFilter
|
||||
- trimmer
|
||||
```
|
||||
|
||||
The following pipeline functions can be used:
|
||||
|
||||
- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
|
||||
- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
|
||||
- `trimmer` – Trim whitespace from tokens
|
||||
|
||||
[pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
|
||||
|
||||
### Segmentation
|
||||
|
||||
The plugin supports text segmentation of Chinese via [jieba], a popular
|
||||
Chinese text segmentation library. Other languages like Japanese and Korean are
|
||||
currently segmented on the client side, but we're considering to move this
|
||||
functionality into the plugin in the future.
|
||||
|
||||
The following settings are available for segmentation:
|
||||
|
||||
[jieba]: https://pypi.org/project/jieba/
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.jieba_dict -->
|
||||
|
||||
<!-- md:version 9.2.0 -->
|
||||
<!-- md:default none -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Use this setting to specify a [custom dictionary] to be used by [jieba] for
|
||||
segmenting text, replacing the default dictionary. [jieba] comes with
|
||||
several dictionaries, which can be used with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
jieba_dict: dict.txt
|
||||
```
|
||||
|
||||
The following dictionaries are provided by [jieba]:
|
||||
|
||||
- [dict.txt.small] – 占用内存较小的词典文件
|
||||
- [dict.txt.big] – 支持繁体分词更好的词典文件
|
||||
|
||||
The provided path is resolved from the root directory.
|
||||
|
||||
[custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
|
||||
[dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
|
||||
[dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.jieba_dict_user -->
|
||||
|
||||
<!-- md:version 9.2.0 -->
|
||||
<!-- md:default none -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Use this setting to specify an additional [user dictionary] to be used by
|
||||
[jieba] for segmenting text, augmenting the default dictionary. User
|
||||
dictionaries are ideal for tuning the segmenter:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- search:
|
||||
jieba_dict_user: user_dict.txt
|
||||
```
|
||||
|
||||
The provided path is resolved from the root directory.
|
||||
|
||||
[user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
|
||||
|
||||
## Usage
|
||||
|
||||
### Metadata
|
||||
|
||||
The following properties are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting meta.search.boost -->
|
||||
|
||||
<!-- md:version 8.3.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this property to increase or decrease the relevance of a page in the search
|
||||
results, giving more weight to them. Use values above `1` to rank up and values
|
||||
below `1` to rank down:
|
||||
|
||||
=== ":material-arrow-up-circle: Rank up"
|
||||
|
||||
``` yaml
|
||||
---
|
||||
search:
|
||||
boost: 2 # (1)!
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
1. When boosting pages, always start with low values.
|
||||
|
||||
=== ":material-arrow-down-circle: Rank down"
|
||||
|
||||
``` yaml
|
||||
---
|
||||
search:
|
||||
boost: 0.5
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting meta.search.exclude -->
|
||||
|
||||
<!-- md:version 9.0.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this property to exclude a page from the search results. Note that this will
|
||||
not only remove the page, but also all subsections of the page from the search
|
||||
results:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
search:
|
||||
exclude: true
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,928 @@
|
||||
---
|
||||
title: Built-in tags plugin
|
||||
icon: material/tag-text
|
||||
---
|
||||
|
||||
# Built-in tags plugin
|
||||
|
||||
The tags plugin adds first-class support for categorizing pages with the use
|
||||
of tags, adding the possibility to group related pages and make them
|
||||
discoverable via search and dedicated tags indexes. If your documentation is
|
||||
large, tags can help to discover relevant information faster.
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
The plugin scans all pages for the [`tags`][meta.tags] metadata property and
|
||||
generates a tags index, which is an inverted list of tags and the pages they
|
||||
appear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],
|
||||
allowing for maximum flexibility when adding tags to your project.
|
||||
|
||||
### When to use it
|
||||
|
||||
If you want to add one or multiple tags indexes to your project, the tags
|
||||
plugin is a perfect choice as it makes this process ridiculously simple.
|
||||
Additionally, it integrates perfectly with several of the other
|
||||
[built-in plugins] that Material for MkDocs offers:
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-file-tree: __[Built-in meta plugin][meta]__
|
||||
|
||||
---
|
||||
|
||||
The meta plugin makes it possible to ensure that subsections of your
|
||||
project are annotated with [specific tags][meta.tags], so they can't be
|
||||
forgotten when adding pages.
|
||||
|
||||
---
|
||||
|
||||
__Simpler organization and management of tags in different subsections__
|
||||
|
||||
- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
|
||||
|
||||
---
|
||||
|
||||
The tags plugin allows to categorize posts alongside with pages in your
|
||||
project, to improve their discoverability and connect posts to your
|
||||
documentation.
|
||||
|
||||
---
|
||||
|
||||
__Your documentation's tag system integrates with your blog__
|
||||
|
||||
</div>
|
||||
|
||||
[meta]: meta.md
|
||||
[blog]: blog.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 8.2.0 -->
|
||||
<!-- md:plugin [tags] – built-in -->
|
||||
<!-- md:flag multiple -->
|
||||
|
||||
As with all [built-in plugins], getting started with the tags plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and start using
|
||||
[tags][meta.tags] to categorize your pages:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags
|
||||
```
|
||||
|
||||
The tags plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[tags]: tags.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.1.7 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
It's normally not necessary to specify this setting, but if you want to disable
|
||||
the plugin, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
### Tags
|
||||
|
||||
The following settings are available for tags:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags -->
|
||||
|
||||
<!-- md:version 9.3.2 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
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:
|
||||
- tags:
|
||||
tags: false
|
||||
```
|
||||
|
||||
This setting is automatically disabled if [`export_only`][config.export_only]
|
||||
is enabled.
|
||||
|
||||
[exporting tags]: #export
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_file -->
|
||||
|
||||
<!-- md:version 8.2.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
!!! warning "This setting is deprecated"
|
||||
|
||||
As of version <!-- md:version 9.6.0 -->, this setting is deprecated, as this
|
||||
version ships a __ground up rewrite of the tags plugin__ which is much more
|
||||
powerful than the previous version. Tags [listings] can be used on any page
|
||||
now.
|
||||
|
||||
<div style="opacity: 0.5" markdown>
|
||||
|
||||
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
|
||||
tags index:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
tags_file: tags.md
|
||||
```
|
||||
|
||||
The page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]
|
||||
section of `mkdocs.yml`. This setting is not required – you should only use it
|
||||
if you want to have a tags index.
|
||||
|
||||
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
|
||||
|
||||
</div>
|
||||
|
||||
[listings]: ../setup/setting-up-tags.md#adding-a-tags-index
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_slugify -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
|
||||
|
||||
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:
|
||||
|
||||
``` 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.
|
||||
|
||||
[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/
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_slugify_separator -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default `-` -->
|
||||
|
||||
Use this setting to change the separator that is passed to the slugification
|
||||
function set as part of [`tags_slugify`][config.tags_slugify]. While the default
|
||||
is a hyphen, it can be set to any string, e.g., `_`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
tags_slugify_separator: _
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_slugify_format -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default `tag:{slug}` -->
|
||||
|
||||
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_slugify_format: "tag:{slug}"
|
||||
```
|
||||
|
||||
The following placeholders are available:
|
||||
|
||||
- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_hierarchy -->
|
||||
|
||||
<!-- md:version 9.7.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:version 9.7.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:version 9.6.0 -->
|
||||
<!-- 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:version 9.6.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.tags_name_property -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default [`tags`][meta.tags] -->
|
||||
|
||||
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_name_property: tags
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_name_variable -->
|
||||
|
||||
<!-- md:version 9.6.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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.tags_allowed -->
|
||||
|
||||
<!-- md:version 9.6.0 -->
|
||||
<!-- md:default none -->
|
||||
|
||||
The plugin allows to check tags against a predefined list, in order to catch
|
||||
typos or make sure that tags are not arbitrarily added. Specify the tags you
|
||||
want to allow with:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- tags:
|
||||
tags_allowed:
|
||||
- HTML5
|
||||
- JavaScript
|
||||
- CSS
|
||||
```
|
||||
|
||||
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:version 9.6.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:version 9.6.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:version 9.6.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:version 9.6.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:version 9.6.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:version 9.6.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:version 9.6.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:version 9.7.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:
|
||||
- tags:
|
||||
listings_toc: false
|
||||
```
|
||||
|
||||
### Shadow tags
|
||||
|
||||
The following settings are available for shadow tags:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.shadow -->
|
||||
|
||||
<!-- md:version 9.7.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:version 9.7.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:version 9.7.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:version 9.7.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:version 9.7.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:version 9.7.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:version 9.7.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:version 9.7.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
|
||||
|
||||
The following properties are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting meta.tags -->
|
||||
|
||||
<!-- md:version 8.2.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:default none -->
|
||||
|
||||
Use this property to associate a page with one or more tags, making the page
|
||||
appear in the generated tags index. Tags are defined as a list of strings
|
||||
(whitespaces are allowed):
|
||||
|
||||
``` yaml
|
||||
---
|
||||
tags:
|
||||
- HTML5
|
||||
- JavaScript
|
||||
- CSS
|
||||
---
|
||||
|
||||
# Page title
|
||||
...
|
||||
```
|
||||
|
||||
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:version 9.6.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:version 9.7.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:version 9.7.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:version 9.6.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:version 9.6.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.
|
||||
|
||||
## Limitations
|
||||
|
||||
The implementation of the tags plugin is tricky due to MkDocs architecture.
|
||||
Notably, tag listing markers cannot appear within code blocks. For technical
|
||||
details, refer to #8114.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Built-in typeset plugin
|
||||
icon: material/format-title
|
||||
status: deprecated
|
||||
---
|
||||
|
||||
# Built-in typeset plugin
|
||||
|
||||
The typeset plugin allows to preserve the enriched presentation of titles and
|
||||
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.
|
||||
|
||||
!!! bug "The built-in typeset plugin is deprecated"
|
||||
|
||||
[Material for MkDocs is in maintenance mode]. The typeset plugin, which was
|
||||
formely part of the [Insiders] edition, was released in <!-- md:version 9.7.0 -->, the last release that includes all features from the Insiders edition.
|
||||
Unfortunately, the typeset plugin turned out impossible to maintain, and
|
||||
was one of the key motivators to create [Zensical].
|
||||
|
||||
---
|
||||
|
||||
__If you're considering the typeset plugin, please be aware that known issues will <u>not</u> be fixed.__
|
||||
|
||||
[Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523
|
||||
[Zensical]: ../blog/posts/zensical.md
|
||||
[Insiders]: ../insiders/index.md
|
||||
|
||||
## Objective
|
||||
|
||||
### How it works
|
||||
|
||||
When [building your project], MkDocs extracts the plain text from headlines and
|
||||
drops the original formatting. This is generally useful and a good idea, since
|
||||
this information is made available to other plugins that might have problems
|
||||
when being passed HTML instead of plain text.
|
||||
|
||||
However, it also means that the entire formatting is lost.
|
||||
|
||||
The plugin hooks into the rendering process, extracts the original headlines,
|
||||
and makes them available to be used in templates and plugins. The templates of
|
||||
Material for MkDocs use this information to render an enriched version of the
|
||||
navigation and table of contents.
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
|
||||
### When to use it
|
||||
|
||||
It's generally recommended to use the plugin, because it is a drop-in solution
|
||||
that doesn't require any configuration and is designed to work out of the box.
|
||||
Since it doesn't overwrite but only adds information, it's not expected to
|
||||
interfere with other plugins.
|
||||
|
||||
## Configuration
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:plugin [typeset] – built-in -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
As with all [built-in plugins], getting started with the typeset plugin is
|
||||
straightforward. Just add the following lines to `mkdocs.yml`, and observe the
|
||||
enriched navigation and table of contents:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- typeset
|
||||
```
|
||||
|
||||
The typeset plugin is built into Material for MkDocs and doesn't need to be
|
||||
installed.
|
||||
|
||||
[typeset]: typeset.md
|
||||
[built-in plugins]: index.md
|
||||
|
||||
### General
|
||||
|
||||
The following settings are available:
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting config.enabled -->
|
||||
|
||||
<!-- md:version 9.7.0 -->
|
||||
<!-- md:default `true` -->
|
||||
|
||||
Use this setting to enable or disable the plugin when [building your project].
|
||||
It's normally not necessary to specify this setting, but if you want to disable
|
||||
the plugin, use:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- typeset:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
[building your project]: ../creating-your-site.md#building-your-site
|
||||
Reference in New Issue
Block a user