diff --git a/CHANGELOG b/CHANGELOG index ae28fe575..3cdb82e01 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-7.1.3+insiders.2.7.0 (2021-05-01) + + * Added support for tags (with search integration) + mkdocs-material-7.1.3 (2021-04-24) * Fixed #2586: Empty table of contents shown (7.1.2 regression) diff --git a/docs/assets/screenshots/tags-index.png b/docs/assets/screenshots/tags-index.png new file mode 100644 index 000000000..35de44070 Binary files /dev/null and b/docs/assets/screenshots/tags-index.png differ diff --git a/docs/assets/screenshots/tags-search.png b/docs/assets/screenshots/tags-search.png new file mode 100644 index 000000000..66c6de4a6 Binary files /dev/null and b/docs/assets/screenshots/tags-search.png differ diff --git a/docs/assets/screenshots/tags.png b/docs/assets/screenshots/tags.png new file mode 100644 index 000000000..cf6902fca Binary files /dev/null and b/docs/assets/screenshots/tags.png differ diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 2bbc65234..5eb261278 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 2.7.0 _ May 1, 2021 + +- Added support for tags (with search integration) + ### 2.6.0 _ April 11, 2021 - Stay on page when switching versions diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 0f935e376..8410e9924 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -111,9 +111,10 @@ The following features are currently exclusively available to sponsors:
+- [x] [Tags with search integration :material-new-box:][29] - [x] [Stay on page when switching versions :material-new-box:][28] - [x] [Version warning :material-new-box:][26] -- [x] [Custom admonition icons :material-new-box:][28] +- [x] [Custom admonition icons][28] - [x] [Code block annotations][25] - [x] [Anchor tracking ][24] - [x] [Section index pages][22] @@ -168,22 +169,23 @@ the public for general availability. [24]: ../setup/setting-up-navigation.md#anchor-tracking [25]: ../reference/code-blocks.md#adding-annotations -[26]: ../setup/setting-up-versioning#version-warning +[26]: ../setup/setting-up-versioning.md#version-warning #### $ 5,000 – Aji Panca - [x] [Mermaid.js integration][27] - [x] [Stay on page when switching versions][28] -- [ ] List of last searches +- [x] [Tags with search integration][29] [27]: ../reference/diagrams.md - [28]: ../setup/setting-up-versioning#stay-on-page + [28]: ../setup/setting-up-versioning.md#stay-on-page + [29]: ../setup/setting-up-tags.md #### $ 6,000 – Trinidad Scorpion - [ ] Improved search result summaries -- [ ] Table of contents shows which sections have search results - [ ] Stay on page when switching languages +- [ ] List of last searches #### $ 7,000 – Royal Gold @@ -193,19 +195,19 @@ the public for general availability. #### $ 8,000 – Scotch Bonnet -- [x] [Custom admonition icons][29] -- [ ] TBA +- [x] [Custom admonition icons][30] +- [ ] Table of contents shows which sections have search results - [ ] TBA - [29]: ../reference/admonitions.md#changing-the-icons + [30]: ../reference/admonitions.md#changing-the-icons #### Future -- [ ] [Material for MkDocs Live Edit][30] +- [ ] [Material for MkDocs Live Edit][31] - [ ] New layouts and styles - [ ] Code block palette toggle - [30]: https://twitter.com/squidfunk/status/1338252230265360391 + [31]: https://twitter.com/squidfunk/status/1338252230265360391 ### Goals completed @@ -238,7 +240,7 @@ the public for general availability. [7]: ../setup/setting-up-navigation.md#navigation-sections [8]: ../setup/setting-up-navigation.md#navigation-expansion - [9]: ../setup/setting-up-navigation.md#hide-the-sidebars + [9]: ../setup/setting-up-navigation.md#hiding-the-sidebars [10]: ../setup/setting-up-navigation.md#navigation-integration [11]: ../setup/setting-up-the-header.md#automatic-hiding @@ -260,10 +262,10 @@ implemented behind feature flags; all configuration changes are backward-compatible. This means that your users will be able to build the documentation locally with Material for MkDocs and when they push their changes, it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's -recommended to [install Insiders][31] only in CI, as you don't want to expose +recommended to [install Insiders][32] only in CI, as you don't want to expose your `GH_TOKEN` to users. - [31]: ../publishing-your-site.md#github-pages + [32]: ../publishing-your-site.md#github-pages ### Terms @@ -272,7 +274,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_ Yes. Whether you're an individual or a company, you may use _Material for MkDocs Insiders_ precisely under the same terms as Material for MkDocs, which are given -by the [MIT license][32]. However, we kindly ask you to respect the following +by the [MIT license][33]. However, we kindly ask you to respect the following guidelines: - Please __don't distribute the source code__ of Insiders. You may freely use @@ -283,7 +285,7 @@ guidelines: - If you cancel your subscription, you're removed as a collaborator and will miss out on future updates of Insiders. However, you may __use the latest version__ that's available to you __as long as you like__. Just remember that - [GitHub deletes private forks][33]. + [GitHub deletes private forks][34]. - [32]: ../license.md - [33]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository + [33]: ../license.md + [34]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index a66dd0c60..33661a3b3 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -33,23 +33,6 @@ This will insert a comment system on _every page, except the index page_. [3]: https://www.mkdocs.org/user-guide/configuration/#site_url [4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname -### Metadata - -The [Metadata][5] extension, which is part of the standard Markdown library, -adds the ability to add [front matter][6] to a document and can be enabled via -`mkdocs.yml`: - -``` yaml -markdown_extensions: - - meta -``` - -Front matter is written as a series of key-value pairs at the beginning of the -Markdown document, delimited by a blank line which ends the YAML context. - - [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html - [6]: https://jekyllrb.com/docs/front-matter/ - ## Customization ### Selective integration @@ -58,7 +41,7 @@ Markdown document, delimited by a blank line which ends the YAML context. :octicons-note-24: Metadata · :octicons-mortar-board-24: Difficulty: _easy_ -If the [Metadata][7] extension is enabled, you can disable or enable Disqus for +If the [Metadata][5] extension is enabled, you can disable or enable Disqus for specific pages by adding the following to the front matter of a page: === "Enable Disqus" @@ -81,15 +64,15 @@ specific pages by adding the following to the front matter of a page: ... ``` - [7]: #metadata + [5]: ../../reference/meta-tags/#metadata ### Other comment systems -[:octicons-file-code-24: Source][8] · +[:octicons-file-code-24: Source][6] · :octicons-mortar-board-24: Difficulty: _easy_ In order to integrate another JavaScript-based comment system provider, you can -[extend the theme][9] and [override the `disqus` block][10]: +[extend the theme][7] and [override the `disqus` block][8]: ``` html {% block disqus %} @@ -97,6 +80,6 @@ In order to integrate another JavaScript-based comment system provider, you can {% endblock %} ``` - [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html - [9]: ../customization.md#extending-the-theme - [10]: ../customization.md#overriding-blocks + [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html + [7]: ../customization.md#extending-the-theme + [8]: ../customization.md#overriding-blocks diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index c8d223225..44be8eb0a 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -377,7 +377,9 @@ The content section will now always stretch to the right side, resulting in more space for your content. This feature flag can be combined with all other feature flags, e.g. [tabs][1] and [sections][2]. -### Hide the sidebars +## Usage + +### Hiding the sidebars [:octicons-file-code-24: Source][28] · :octicons-note-24: Metadata diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md new file mode 100644 index 000000000..29274e969 --- /dev/null +++ b/docs/setup/setting-up-tags.md @@ -0,0 +1,127 @@ +--- +template: overrides/main.html +tags: + - insiders + - brand new +--- + +# Setting up tags + +Material for MkDocs adds first-class support for categorizing pages with tags, +which adds the possibility to group related pages and make them discoverable +via search and a dedicated tags index. If your documentation is large, tags +can help to discover relevant information faster. + +## Configuration + +### Built-in tags + +[:octicons-file-code-24: Source][1] · +[:octicons-cpu-24: Plugin][1] · +:octicons-beaker-24: Experimental · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][1]{ .mdx-insiders } + +The [built-in tags plugin][1] adds the ability to categorize any page with tags +as part of the front matter of the page. In order to add support for tags, add +the following lines to `mkdocs.yml`: + +``` yaml +plugins: + - tags +``` + +Note that no third-party plugin[^1] needs to be installed, as Material for +MkDocs provides its own implementation to allow for a meaningful integration. +The following options are available: + +`tags_file`{ #tags_file } + +: :octicons-milestone-24: Default: _none_ – This option specifies which file + should be used to render the tags index. See the section on [adding a tags + index][3] for more information. If this option is specified, tags will + 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` section + of `mkdocs.yml`. Note, however, that this options is not required. If this + option is not specified, tags are still rendered and searchable, + but without a tags index. + + [^1]: + The built-in tags plugin has no affiliation with [mkdocs-plugin-tags][2], + another option to add tag support to MkDocs, which has several caveats: + it requires a `title` set in the front matter for every page for which tags + should be added, doesn't support all syntactic flavors of front matter, + doesn't integrate tags in search and doesn't render tags on pages without + additional effort. The built-in tags plugin supports all of these + features out-of-the-box. + + [1]: ../insiders/index.md + [2]: https://github.com/jldiaz/mkdocs-plugin-tags + [3]: #adding-a-tags-index + +## Usage + +### Adding tags + +[:octicons-file-code-24: Source][1] · +:octicons-note-24: Metadata + +If the [built-in tags plugin][4] and [Metadata][5] extension are enabled, tags +can be added for any page as part of the front matter, e.g. to add the tags +`insiders` and `brand new` to this page, add: + +``` yaml +--- +tags: + - insiders + - brand new +--- + +... +``` + +The page will now render with those tags below the main headline and within the +search preview, which now allows to __search for tags__, as shown in the +following screenshots: + +=== "Tags" + + [![Tags][6]][6] + +=== "Tag search" + + [![Tag search][7]][7] + + [4]: #built-in-tags + [5]: ../../reference/meta-tags/#metadata + [6]: ../assets/screenshots/tags.png + [7]: ../assets/screenshots/tags-search.png + +### Adding a tags index + +The [built-in tags plugin][4] allows to define a file to render a [tags +index][8], 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] +``` + +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: + +[![Tags index][9]][9] + + [8]: #tags_file + [9]: ../assets/screenshots/tags-index.png diff --git a/mkdocs.yml b/mkdocs.yml index 8d798f1fe..934e1aaa4 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -175,6 +175,7 @@ nav: - Setting up navigation: setup/setting-up-navigation.md - Setting up site search: setup/setting-up-site-search.md - Setting up site analytics: setup/setting-up-site-analytics.md + - Setting up tags: setup/setting-up-tags.md - Setting up versioning: setup/setting-up-versioning.md - Setting up the header: setup/setting-up-the-header.md - Setting up the footer: setup/setting-up-the-footer.md