diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 67ffcd3ff..e1e4e711a 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -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] @@ -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 diff --git a/docs/plugins/tags.md b/docs/plugins/tags.md index 24a73ff54..c9aac16e9 100644 --- a/docs/plugins/tags.md +++ b/docs/plugins/tags.md @@ -112,10 +112,9 @@ The following settings are available for tags: -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 + --- #### @@ -130,6 +134,13 @@ plugins: +!!! 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]. ---- - -#### - - - - - -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: --- -#### +#### - - + + -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] --- -#### +#### + + + + + + +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 +``` + +--- + +#### + + + + + + +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: . +``` + +--- + +#### + + + + + +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]. + +--- + +#### @@ -252,57 +305,43 @@ ordering as follows: ``` yaml plugins: - tags: - tags_compare_reverse: true + tags_sort_reverse: true ``` --- -#### +#### - - + + -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]. - ---- - -#### - - - - - -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 +``` + +--- + +#### + + + + + +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: + +--- + +#### + + + + + +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 + +--- + +#### + + + + + +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 + +``` + +See the [listings section] for a list of all available settings. + + [listings section]: #listing_configuration + +--- + +#### + + + + + +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]. + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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]. + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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 + +``` + +--- + +#### + + + + + +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: + +--- + +#### + + + + + +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 + ``` + +--- + +#### + + + + + +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 + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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: _ +``` + +--- + +#### + + + + + +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: + +--- + +#### + + + + + +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 +``` + +--- + +#### + + + + + +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]. + +--- + +#### + + + + + +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: + +--- + +#### + + + + + +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 + + ``` + +=== "Usage in `mkdocs.yml`" + + ``` yaml + plugins: + - tags: + listings_map: + custom-id: + scope: false + ``` + + Then, just reference the listing identifier: + + ``` html + + ``` + +--- + +#### + + + + + +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 + + ``` + +=== "Usage in `mkdocs.yml`" + + ``` yaml + plugins: + - tags: + listings_map: + custom-id: + shadow: true + ``` + + Then, just reference the listing identifier: + + ``` html + + ``` + +--- + +#### + + + + + +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 + + ``` + +=== "Usage in `mkdocs.yml`" + + ``` yaml + plugins: + - tags: + listings_map: + custom-id: + toc: true + ``` + + Then, just reference the listing identifier: + + ``` html + + ``` + +--- + +#### + + + + + +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 + + ``` + +=== "Usage in `mkdocs.yml`" + + ``` yaml + plugins: + - tags: + listings_map: + custom-id: + include: + - foo + - bar + ``` + + Then, just reference the listing identifier: + + ``` html + + ``` + +If this setting is left empty, all tags and pages are included. + +--- + +#### + + + + + +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 + + ``` + +=== "Usage in `mkdocs.yml`" + + ``` yaml + plugins: + - tags: + listings_map: + custom-id: + exclude: + - foo + - bar + ``` + + Then, just reference the listing identifier: + + ``` html + + ``` + +If this setting is left empty, no tags or pages are excluded. diff --git a/docs/schema/plugins/tags.json b/docs/schema/plugins/tags.json index 0261ba32e..447afd5b4 100644 --- a/docs/schema/plugins/tags.json +++ b/docs/schema/plugins/tags.json @@ -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 diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md index 2590b969d..b2a533682 100644 --- a/docs/setup/setting-up-a-blog.md +++ b/docs/setup/setting-up-a-blog.md @@ -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" } @@ -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 diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md index 52d99e63b..0b79eff5b 100644 --- a/docs/setup/setting-up-tags.md +++ b/docs/setup/setting-up-tags.md @@ -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" } + + + + + +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_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 @@ -159,16 +178,16 @@ search preview, which now allows to __find pages by 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] + ``` 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 + + + + + +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 + + ``` + +- __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 + + ``` + +- __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 + + ``` + +- __Enable or disable tags inside the table of contents__: specify whether the + table of contents lists all tags under the nearest headline: + + ``` html + + ``` + +See the [listing configuration] for all options. + + [listing configuration]: ../plugins/tags.md#listing-configuration + +#### Scoped listings + + + + + +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 + +``` + +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 + +``` + +#### Shadow tags + + + + + +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 + + + + + +[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 diff --git a/src/plugins/tags/plugin.py b/src/plugins/tags/plugin.py index e5ce6bdec..a73792839 100644 --- a/src/plugins/tags/plugin.py +++ b/src/plugins/tags/plugin.py @@ -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]", "") + if not "" in markdown: + markdown += "\n" # Replace placeholder in Markdown with rendered tags index - return markdown.replace("[TAGS]", "\n".join([ + return markdown.replace("", "\n".join([ self._render_tag_links(*args) for args in sorted(self.tags.items()) ]))