Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-09-24 03:18:21 +02:00
Code Issues Releases Wiki Activity

Added documentation on new tags features

Browse Source
This commit is contained in:
squidfunk 2023-12-29 13:32:19 +01:00
parent 533d02e740
commit 2757f27819
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
6 changed files with 995 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/insiders/index.md
View File

@ -96,8 +96,8 @@ which are currently exclusively available to sponsors:
- [x] [Tags plugin: advanced settings] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
- [x] [Tags plugin: nested tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
- [x] [Tags plugin: shadow tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
- [x] [Stay on page when switching languages] :material-alert-decagram:{ .mdx-pulse title="Added on December 8, 2023" }
- [x] [Blog plugin: author profiles] :material-alert-decagram:{ .mdx-pulse title="Added on November 26, 2023" }
- [x] [Stay on page when switching languages]
- [x] [Blog plugin: author profiles]
- [x] [Blog plugin: advanced settings]
- [x] [Projects plugin]
- [x] [Instant prefetching]
@ -115,7 +115,7 @@ which are currently exclusively available to sponsors:
- [x] [Blog plugin: custom index pages]
- [x] [Blog plugin: related links]
- [x] [Meta plugin]
- [x] [Tags plugin: additional indexes]
- [x] [Tags plugin: configurable listings]
</div>
@ -273,14 +273,14 @@ are released for general availability.
- [x] [Meta plugin]
- [x] [Blog plugin: related links]
- [x] [Blog plugin: custom index pages]
- [x] [Tags plugin: additional indexes]
- [x] [Tags plugin: configurable listings]
- [x] [Tags plugin: allow list] + [custom sorting]
- [x] [Navigation subtitles]
[Meta plugin]: ../plugins/meta.md
[Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
[Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
[Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
[Tags plugin: configurable listings]: ../setup/setting-up-tags.md#configurable-listings
[Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed
[custom sorting]: ../setup/setting-up-tags.md#+tags.tags_compare
[Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
@ -322,8 +322,8 @@ are released for general availability.
[Code range selection]: ../reference/code-blocks.md#code-selection-button
[Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
[Stay on page when switching languages]: ../setup/changing-the-language.md#stay-on-page
[Tags plugin: nested tags]: ../plugins/tags.md#config.tags_hierarchy
[Tags plugin: shadow tags]: ../plugins/tags.md#config.shadow
[Tags plugin: nested tags]: ../setup/setting-up-tags.md#nested-tags
[Tags plugin: shadow tags]: ../setup/setting-up-tags.md#shadow-tags
#### $ 28,000 – Lemon Drop

741
docs/plugins/tags.md
View File

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

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

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

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

@ -34,6 +34,8 @@ plugins:
For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/blog.md
#### Advanced settings :material-alert-decagram:{ .mdx-pulse title="Added on November 23, 2023" }
<!-- md:sponsors -->
@ -54,8 +56,6 @@ the blog, but can be helpful for customizations:
We'll add more settings here, as we discover new use cases.
[plugin documentation]: ../plugins/blog.md
[Insiders]: ../insiders/index.md
[built-in blog plugin]: ../plugins/blog.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins

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

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

8
src/plugins/tags/plugin.py
View File

@ -131,11 +131,13 @@ class TagsPlugin(BasePlugin[TagsConfig]):
# Render tags index
def _render_tag_index(self, markdown):
if not "[TAGS]" in markdown:
markdown += "\n[TAGS]"
if "[TAGS]" in markdown:
markdown = markdown.replace("[TAGS]", "<!-- material/tags -->")
if not "<!-- material/tags -->" in markdown:
markdown += "\n<!-- material/tags -->"
# Replace placeholder in Markdown with rendered tags index
return markdown.replace("[TAGS]", "\n".join([
return markdown.replace("<!-- material/tags -->", "\n".join([
self._render_tag_links(*args)
for args in sorted(self.tags.items())
]))