diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml new file mode 100644 index 000000000..1e2b34d3b --- /dev/null +++ b/docs/blog/.authors.yml @@ -0,0 +1,4 @@ +squidfunk: + name: Martin Donath + description: Creator + avatar: https://avatars.githubusercontent.com/u/932156 diff --git a/docs/blog/.meta.yml b/docs/blog/.meta.yml new file mode 100644 index 000000000..ea01dc9ab --- /dev/null +++ b/docs/blog/.meta.yml @@ -0,0 +1,3 @@ +comments: true +hide: + - feedback diff --git a/docs/blog/index.md b/docs/blog/index.md index 7330c027f..002f24c31 100644 --- a/docs/blog/index.md +++ b/docs/blog/index.md @@ -1,146 +1,4 @@ ---- -template: overrides/main.html -title: Blog -search: - exclude: true ---- - - - # Blog -## [Chinese search support – 中文搜索​支持] - -__Insiders adds experimental Chinese language support for the [built-in search -plugin] – a feature that has been requested for a long time given the large -number of Chinese users.__ - - - ---- - -After the United States and Germany, the third-largest country of origin of -Material for MkDocs users is China. For a long time, the [built-in search plugin] -didn't allow for proper segmentation of Chinese characters, mainly due to -missing support in [`lunr-languages`][lunr-languages] which is used for search -tokenization and stemming. The latest Insiders release adds long-awaited Chinese -language support for the built-in search plugin, something that has been -requested by many users. - - [:octicons-arrow-right-24: Continue reading][Chinese search support – 中文搜索​支持] - - [built-in search plugin]: ../setup/setting-up-site-search.md#built-in-search-plugin - [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 - [insiders-4.14.0]: ../insiders/changelog.md#4.14.0 - [lunr-languages]: https://github.com/MihaiValentin/lunr-languages - [Chinese search support – 中文搜索​支持]: 2022/chinese-search-support.md - -## [The past, present and future] - -__2021 was a fantastic year for this project as we shipped many new awesome -features, saw significant user growth and leveraged GitHub Sponsors to make the -project sustainable.__ - - - ---- - -Today, together, MkDocs and Material for MkDocs are among the most popular -options when it comes to choosing a static site generator and theme for your -technical documentation project. Material for MkDocs ensures that your -content is always perfectly presented to your audience, regardless of screen -resolution or device capabilities. It has evolved to a framework for technical -writing, offering many features, some of which are yet to be found in other -static site generators. However, we're far from the end, as 2022 is going to -bring some interesting new capabilities. - - [:octicons-arrow-right-24: Continue reading][The past, present and future] - - [The past, present and future]: 2021/the-past-present-and-future.md - -## [Excluding content from search] - -__The latest Insiders release brings three new simple ways to exclude dedicated -parts of a document from the search index, allowing for more fine-grained -control.__ - - - ---- - -Two weeks ago, Material for MkDocs Insiders shipped a brand new search plugin, -yielding massive improvements in usability, but also in speed and size of the -search index. Interestingly, as discussed in the previous blog article, we only -scratched the surface of what's now possible. This release brings some useful -features that enhance the writing experience, allowing for more fine-grained -control of what pages, sections and blocks of a Markdown file should be indexed -by the built-in search functionality. - -[:octicons-arrow-right-24: Continue reading][Excluding content from search] - - [Excluding content from search]: 2021/excluding-content-from-search.md - [insiders-3.1.1]: ../insiders/changelog.md#3.1.1 - -## [Search: better, faster, smaller] - -__This is the story of how we managed to completely rebuild client-side search, -delivering a significantly better user experience while making it faster and -smaller at the same time.__ - - - ---- - -The search of Material for MkDocs is by far one of its best and most-loved -assets: multilingual, offline-capable, and most importantly: _all client-side_. -It provides a solution to empower the users of your documentation to find what -they're searching for instantly without the headache of managing additional -servers. However, even though several iterations have been made, there's still -some room for improvement, which is why we rebuilt the search plugin and -integration from the ground up. This article shines some light on the internals -of the new search, why it's much more powerful than the previous version, and -what's about to come. - -[:octicons-arrow-right-24: Continue reading][Search: better, faster, smaller] - - [Search: better, faster, smaller]: 2021/search-better-faster-smaller.md - [insiders-3.0.0]: ../insiders/changelog.md#3.0.0 +This is our blog where we write about new features, performance improvements +and the project in general. diff --git a/docs/blog/posts/blog-support-just-landed.md b/docs/blog/posts/blog-support-just-landed.md new file mode 100644 index 000000000..689a06c33 --- /dev/null +++ b/docs/blog/posts/blog-support-just-landed.md @@ -0,0 +1,246 @@ +--- +date: 2022-09-12 +authors: [squidfunk] +description: > + Our new blog is built with the brand new built-in blog plugin. You can build + a blog alongside your documentation or standalone +categories: + - Blog +links: + - Getting started with Insiders: insiders/getting-started.md#requirements + - setup/setting-up-a-blog.md#built-in-blog-plugin +--- + +# Blog support just landed + +__Hey there! You're looking at our new blog, built with the brand new +[built-in blog plugin]. With this plugin, you can easily build a blog alongside +your documentation or standalone.__ + +Proper support for blogging, as requested by many users over the past few years, +was something that was desperately missing from Material for MkDocs' feature set. +While everybody agreed that blogging support was a blind spot, it was not +obvious whether MkDocs could be extended in a way to allow for blogging as we +know it from [Jekyll] and friends. The [built-in blog plugin] proves that it is, +after all, possible to build a blogging engine on top of MkDocs, in order to +create a technical blog alongside your documentation, or as the main thing. + + + +_This article explains how to build a standalone blog with Material for MkDocs. +If you want to build a blog alongside your documentation, please refer to +[the plugin's documentation][built-in blog plugin]._ + + [built-in blog plugin]: ../../setup/setting-up-a-blog.md#built-in-blog-plugin + [Jekyll]: https://jekyllrb.com/ + +## Quick start + +### Setting up Insiders + +Before we can start bootstrapping a blog and [write our first post], we need to +set up [Insiders], since the [built-in blog plugin] is currently reserved to +sponsors. Without the funds this project receives through sponsorships, this +plugin wouldn't exist. Three steps are necessary: + +1. [Subscribe to a monthly sponsorship] +2. [Create a personal access token] +3. [Install Insiders] + + [write our first post]: #writing-your-first-post + [Insiders]: ../../insiders/index.md + [Subscribe to a monthly sponsorship]: ../../insiders/index.md#how-to-become-a-sponsor + [Create a personal access token]: ../../insiders/getting-started.md#requirements + [Install Insiders]: ../../insiders/getting-started.md#installation + +### Creating a standalone blog + +After Insiders is installed, you can bootstrap a new project using the `mkdocs` +executable: + +``` +mkdocs new . +``` + +This will create the following structure: + +``` +. +├─ docs/ +│ └─ index.md +└─ mkdocs.yml +``` + +#### Configuration + +In this article, we're going to build a standalone blog, which means that the +blog lives at the root of your project. For this reason, open `mkdocs.yml`, +and replace its contents with: + +``` yaml +site_name: My Blog +theme: + name: material + features: + - navigation.sections +plugins: + - blog: + blog_dir: . # (1)! + - search + - tags +nav: + - index.md +``` + +1. This is the important part – we're hosting the blog at the root of the + project, and not in a subdirectory. For more information, see the + [`blog_dir`][blog_dir] configuration option. + + [blog_dir]: ../../setup/setting-up-a-blog.md#+blog.blog_dir + +#### Blog setup + +The blog index page lives in `docs/index.md`. This page was pre-filled by +MkDocs with some content, so we're going to replace it with what we need to +bootstrap the blog: + +``` markdown +# Blog +``` + +That's it. + +### Writing your first post + +Now that we have set up the [built-in blog plugin], we can start writing our +first post. All blog posts are written with the [exact same Markdown flavor] as +already included with Material for MkDocs. First, create a folder called `posts` +with a file called `hello-world.md`: + +``` sh +. +├─ docs/ +│ ├─ posts/ +│ │ └─ hello-world.md # (1)! +│ └─ index.md +└─ mkdocs.yml +``` + +1. If you'd like to arrange posts differently, you're free to do so. The URLs + are built from the format specified in [`post_url_format`][post slugs] and + the titles and dates of posts, no matter how they are organized + inside the `posts` directory. + +Then, open up `hello-world.md`, and add the following lines: + +``` yaml +--- +draft: true # (1)! +date: 2022-01-31 +categories: + - Hello + - World +--- + +# Hello world! + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec +maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula +erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst. +Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris +Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in +sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac +metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet. + + + +Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum +massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam +tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet +molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus. + +Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat. +In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc +pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis +arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue. +In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque +tellus id elit ultricies, vel finibus erat cursus. +``` + +1. If you mark a post as a [draft], a red marker appears next to the post date + on index pages. When the site is built, drafts are not included in the + output. [This behavior can be changed], e.g. for rendering drafts when + building deploy previews. + +When you spin up the [live preview server], you should be greeted by your first +post! You'll also realize, that [archive] and [category] indexes have been +automatically generated for you: + + ![Blog] + +However, this is just the start. The [built-in blog plugin] packs a lot of +functionality needed in day-to-day blogging. Visit the documentation of the +plugin to learn about the following topics: + +
+ +- [Adding an excerpt] +- [Adding authors] +- [Adding categories] +- [Adding tags] +- [Adding related links] +- [Linking from and to posts] +- [Setting the reading time] +- [Setting defaults] + +
+ +Additionally, the [built-in blog plugin] has dozens of [configuration options] +which allow for fine-tuning the output. You can configure post slugs, general +behavior and much more. + + [exact same Markdown flavor]: ../../reference/index.md + [post slugs]: ../../setup/setting-up-a-blog.md#+blog.post_url_format + [draft]: ../../setup/setting-up-a-blog.md#drafts + [This behavior can be changed]: ../../setup/setting-up-a-blog.md#+blog.draft + [live preview server]: ../../creating-your-site.md#previewing-as-you-write + [archive]: ../../setup/setting-up-a-blog.md#archive + [category]: ../../setup/setting-up-a-blog.md#categories + [Blog]: blog-support-just-landed/blog.png + [Blog post]: blog-support-just-landed/blog-post.png + [Adding an excerpt]: ../../setup/setting-up-a-blog.md#adding-an-excerpt + [Adding authors]: ../../setup/setting-up-a-blog.md#adding-authors + [Adding categories]: ../../setup/setting-up-a-blog.md#adding-categories + [Adding tags]: ../../setup/setting-up-a-blog.md#adding-tags + [Adding related links]: ../../setup/setting-up-a-blog.md#adding-related-links + [Linking from and to posts]: ../../setup/setting-up-a-blog.md#linking-from-and-to-posts + [Setting the reading time]: ../../setup/setting-up-a-blog.md#setting-the-reading-time + [Setting defaults]: ../../setup/setting-up-a-blog.md#setting-defaults + [configuration options]: ../../setup/setting-up-a-blog.md#configuration + +## What's next? + +Getting basic blogging support out the door was quite a challenge – the +[built-in blog plugin] is probably the biggest release this year and already +packs a lot of functionality. However, Material for MkDocs is used in many +different contexts, which is why we'd expect to iterate, as always. + +Some ideas already proposed by users: + +- __Blog series__: Authors should be able to create so called blog series and + assign posts to a blog series using simple identifiers. For each post that is + part of a series, a list with links to all other posts should be included in + the post's content. + +- __Author indexes__: Besides [archive] and [category] indexes, authors should + be able to create per-author indexes, which list all posts linked to an + author. Additionally, a profile should be created for each author and linked + from posts. + +- __Social share buttons__: It should be easy to share blog posts via social + media or other ways. For this reason, it should be possible to automatically + include social sharing buttons with each post. + +What's still missing from the brand new [built-in blog plugin]? Feel free to +share your ideas in the comments. Together, we can build one of the best modern +engines for technical blogging! diff --git a/docs/blog/posts/blog-support-just-landed/blog.png b/docs/blog/posts/blog-support-just-landed/blog.png new file mode 100644 index 000000000..a1ea1eaa0 Binary files /dev/null and b/docs/blog/posts/blog-support-just-landed/blog.png differ diff --git a/docs/blog/2022/chinese-search-support.md b/docs/blog/posts/chinese-search-support.md similarity index 86% rename from docs/blog/2022/chinese-search-support.md rename to docs/blog/posts/chinese-search-support.md index 243d09209..cf675cd61 100644 --- a/docs/blog/2022/chinese-search-support.md +++ b/docs/blog/posts/chinese-search-support.md @@ -1,11 +1,16 @@ --- -template: overrides/blog.html +date: 2022-05-05 +authors: [squidfunk] title: Chinese search support description: > Insiders adds Chinese language support for the built-in search plugin – a feature that has been requested many times -hide: - - feedback +categories: + - Search +links: + - blog/posts/search-better-faster-smaller.md + - setup/setting-up-site-search.md#chinese-language-support + - insiders/index.md#how-to-become-a-sponsor --- # Chinese search support – 中文搜索​支持 @@ -14,23 +19,6 @@ __Insiders adds experimental Chinese language support for the [built-in search plugin] – a feature that has been requested for a long time given the large number of Chinese users.__ - - - [built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin - [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 - [insiders-4.14.0]: ../../insiders/changelog.md#4.14.0 - ---- - After the United States and Germany, the third-largest country of origin of Material for MkDocs users is China. For a long time, the [built-in search plugin] didn't allow for proper segmentation of Chinese characters, mainly due to @@ -38,6 +26,8 @@ missing support in [lunr-languages] which is used for search tokenization and stemming. The latest Insiders release adds long-awaited Chinese language support for the built-in search plugin, something that has been requested by many users. + + _Material for MkDocs終於​支持​中文​了！文本​被​正確​分割​並且​更​容易​找到。_ { style="display: inline" } @@ -45,6 +35,7 @@ _This article explains how to set up Chinese language support for the built-in search plugin in a few minutes._ { style="display: inline" } + [built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin [lunr-languages]: https://github.com/MihaiValentin/lunr-languages ## Configuration diff --git a/docs/blog/2021/excluding-content-from-search.md b/docs/blog/posts/excluding-content-from-search.md similarity index 89% rename from docs/blog/2021/excluding-content-from-search.md rename to docs/blog/posts/excluding-content-from-search.md index 064aa41ac..6c7b0d7b5 100644 --- a/docs/blog/2021/excluding-content-from-search.md +++ b/docs/blog/posts/excluding-content-from-search.md @@ -1,12 +1,15 @@ --- -template: overrides/blog.html +date: 2021-09-26 +authors: [squidfunk] description: > Three new simple ways to exclude dedicated parts of a document from the search index, allowing for more fine-grained control -search: - exclude: true -hide: - - feedback +categories: + - Search +links: + - blog/posts/search-better-faster-smaller.md + - setup/setting-up-site-search.md#search-exclusion + - insiders/index.md#how-to-become-a-sponsor --- # Excluding content from search @@ -15,22 +18,6 @@ __The latest Insiders release brings three new simple ways to exclude dedicated parts of a document from the search index, allowing for more fine-grained control.__ - - - [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 - [insiders-3.1.1]: ../../insiders/changelog.md#3.1.1 - ---- - Two weeks ago, Material for MkDocs Insiders shipped a [brand new search plugin], yielding [massive improvements in usability], but also in [speed and size] of the search index. Interestingly, as discussed in the previous @@ -39,6 +26,8 @@ release brings some useful features that enhance the writing experience, allowing for more fine-grained control of what pages, sections and blocks of a Markdown file should be indexed by the built-in search functionality. + + _The following section discusses existing solutions for excluding pages and sections from the search index. If you immediately want to learn what's new, skip to the [section just after that][what's new]._ @@ -124,7 +113,7 @@ directive to the front matter of the respective Markdown file. The good thing is that the author now only has to check the top of the document to learn whether it is excluded or not: -``` sh +``` yaml --- search: exclude: true @@ -137,11 +126,11 @@ search: ### Excluding sections If a section should be excluded, the author can use the [Attribute Lists] -extension to add a __pragma__ called `{ data-search-exclude }` at the end of a +extension to add a __pragma__ called `data-search-exclude` at the end of a heading. The pragma is not included in the final HTML, as search pragmas are filtered by the search plugin before the page is rendered: -=== ":octicons-file-code-16: docs/page.md" +=== ":octicons-file-code-16: `docs/page.md`" ``` markdown # Document title @@ -155,7 +144,7 @@ filtered by the search plugin before the page is rendered: The content of this section is excluded ``` -=== ":octicons-codescan-16: search_index.json" +=== ":octicons-codescan-16: `search_index.json`" ``` json { @@ -181,7 +170,7 @@ If even more fine-grained control is desired, the __pragma__ can be added to any [block-level element] or [inline-level element] that is officially supported by the [Attribute Lists] extension: -=== ":octicons-file-code-16: docs/page.md" +=== ":octicons-file-code-16: `docs/page.md`" ``` markdown # Document title @@ -192,7 +181,7 @@ supported by the [Attribute Lists] extension: { data-search-exclude } ``` -=== ":octicons-codescan-16: search_index.json" +=== ":octicons-codescan-16: `search_index.json`" ``` json { diff --git a/docs/blog/2021/search-better-faster-smaller.md b/docs/blog/posts/search-better-faster-smaller.md similarity index 97% rename from docs/blog/2021/search-better-faster-smaller.md rename to docs/blog/posts/search-better-faster-smaller.md index be2315e21..a6375d867 100644 --- a/docs/blog/2021/search-better-faster-smaller.md +++ b/docs/blog/posts/search-better-faster-smaller.md @@ -1,12 +1,16 @@ --- -template: overrides/blog.html +date: 2021-09-13 +authors: [squidfunk] +readtime: 15 description: > How we rebuilt client-side search, delivering a better user experience while making it faster and smaller at the same time -search: - exclude: true -hide: - - feedback +categories: + - Search + - Performance +links: + - setup/setting-up-site-search.md#built-in-search-plugin + - insiders/index.md#how-to-become-a-sponsor --- # Search: better, faster, smaller @@ -15,22 +19,6 @@ __This is the story of how we managed to completely rebuild client-side search, delivering a significantly better user experience while making it faster and smaller at the same time.__ - - - [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 - [insiders-3.0.0]: ../../insiders/changelog.md#3.0.0 - ---- - The [search] of Material for MkDocs is by far one of its best and most-loved assets: [multilingual], [offline-capable], and most importantly: _all client-side_. It provides a solution to empower the users of your documentation @@ -41,6 +29,8 @@ plugin and integration from the ground up. This article shines some light on the internals of the new search, why it's much more powerful than the previous version, and what's about to come. + + _The next section discusses the architecture and issues of the current search implementation. If you immediately want to learn what's new, skip to the [section just after that][what's new]._ @@ -78,7 +68,7 @@ the original Markdown file: ??? example "Expand to inspect example" - === ":octicons-file-code-16: docs/page.md" + === ":octicons-file-code-16: `docs/page.md`" ```` markdown # Example @@ -108,7 +98,7 @@ the original Markdown file: * Profit! ```` - === ":octicons-codescan-16: search_index.json" + === ":octicons-codescan-16: `search_index.json`" ``` json { diff --git a/docs/blog/2021/search-better-faster-smaller/search-preview-before.png b/docs/blog/posts/search-better-faster-smaller/search-preview-before.png similarity index 100% rename from docs/blog/2021/search-better-faster-smaller/search-preview-before.png rename to docs/blog/posts/search-better-faster-smaller/search-preview-before.png diff --git a/docs/blog/2021/search-better-faster-smaller/search-preview-now.png b/docs/blog/posts/search-better-faster-smaller/search-preview-now.png similarity index 100% rename from docs/blog/2021/search-better-faster-smaller/search-preview-now.png rename to docs/blog/posts/search-better-faster-smaller/search-preview-now.png diff --git a/docs/blog/2021/search-better-faster-smaller/search-preview.png b/docs/blog/posts/search-better-faster-smaller/search-preview.png similarity index 100% rename from docs/blog/2021/search-better-faster-smaller/search-preview.png rename to docs/blog/posts/search-better-faster-smaller/search-preview.png diff --git a/docs/blog/2021/the-past-present-and-future.md b/docs/blog/posts/the-past-present-and-future.md similarity index 96% rename from docs/blog/2021/the-past-present-and-future.md rename to docs/blog/posts/the-past-present-and-future.md index cbe2e3d8b..2cd783f36 100644 --- a/docs/blog/2021/the-past-present-and-future.md +++ b/docs/blog/posts/the-past-present-and-future.md @@ -1,12 +1,11 @@ --- -template: overrides/blog.html +date: 2021-12-27 +authors: [squidfunk] description: > 2021 was a fantastic year for this project as we shipped many new awesome features and made this project sustainable -search: - exclude: true -hide: - - feedback +categories: + - General --- # The past, present and future @@ -15,20 +14,6 @@ __2021 was a fantastic year for this project as we shipped many new awesome features, saw significant user growth and leveraged GitHub Sponsors to make the project sustainable.__ - - - [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156 - ---- - Today, together, [MkDocs] and Material for MkDocs are among the most popular options when it comes to choosing a static site generator and theme for your technical documentation project. Material for MkDocs ensures that your @@ -38,6 +23,8 @@ writing, offering many features, some of which are yet to be found in other static site generators. However, we're far from the end, as 2022 is going to bring some interesting new capabilities. + + _This article showcases all features that were added in 2021 and gives an outlook on what's going to drop in 2022. Additionally, it provides some context on the history of the project._ @@ -187,7 +174,7 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times. [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle [Content tabs: improved support]: ../../reference/content-tabs.md [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs - [Cookie consent]: ../../setup/ensuring-data-privacy.md#native-cookie-consent + [Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read diff --git a/docs/blog/2021/the-past-present-and-future/funding.png b/docs/blog/posts/the-past-present-and-future/funding.png similarity index 100% rename from docs/blog/2021/the-past-present-and-future/funding.png rename to docs/blog/posts/the-past-present-and-future/funding.png diff --git a/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png similarity index 100% rename from docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0-search.png rename to docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0-search.png diff --git a/docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png b/docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png similarity index 100% rename from docs/blog/2021/the-past-present-and-future/mkdocs-material-0.1.0.png rename to docs/blog/posts/the-past-present-and-future/mkdocs-material-0.1.0.png diff --git a/docs/browser-support.md b/docs/browser-support.md index bc7a8e190..11879b706 100644 --- a/docs/browser-support.md +++ b/docs/browser-support.md @@ -15,8 +15,8 @@ modern CSS features like [custom properties] and [mask images]. The following table lists all browsers for which Material for MkDocs offers full support, so it can be assumed that all features work without degradation. If you -find a feature not to be working in a browser in the supported version range, -please [open an issue]: +find that something doesn't look right in a browser which is in the supported +version range, please [open an issue]:
diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 275846d02..f611c597c 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -153,6 +153,7 @@ and much more: - [Setting up site search] - [Setting up site analytics] - [Setting up social cards] +- [Setting up a blog] - [Setting up tags] - [Setting up versioning] - [Setting up the header] @@ -164,7 +165,7 @@ and much more: Furthermore, see the list of supported [Markdown extensions] that are natively -integrated with Material for MkDocs, delivering a low-effort and unprecedented +integrated with Material for MkDocs, delivering an unprecedented low-effort technical writing experience. [Changing the colors]: setup/changing-the-colors.md @@ -176,6 +177,7 @@ technical writing experience. [Setting up site search]: setup/setting-up-site-search.md [Setting up site analytics]: setup/setting-up-site-analytics.md [Setting up social cards]: setup/setting-up-social-cards.md + [Setting up a blog]: setup/setting-up-a-blog.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 diff --git a/docs/customization.md b/docs/customization.md index 0a1480d3b..516601c2c 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -103,26 +103,38 @@ assets may also be put in the `overrides` directory: │ │ ├─ analytics/ # Analytics integrations │ │ └─ analytics.html # Analytics setup │ ├─ languages/ # Translation languages +│ ├─ actions.html # Actions +│ ├─ comments.html # Comment system (empty by default) +│ ├─ consent.html # Consent │ ├─ content.html # Page content │ ├─ copyright.html # Copyright and theme information +│ ├─ feedback.html # Was this page helpful? │ ├─ footer.html # Footer bar │ ├─ header.html # Header bar +│ ├─ icons.html # Custom icons │ ├─ language.html # Translation setup │ ├─ logo.html # Logo in header and sidebar │ ├─ nav.html # Main navigation │ ├─ nav-item.html # Main navigation item +│ ├─ pagination.html # Pagination (used for blog) │ ├─ palette.html # Color palette +│ ├─ post.html # Blog post excerpt │ ├─ search.html # Search interface │ ├─ social.html # Social links │ ├─ source.html # Repository information │ ├─ source-file.html # Source file information │ ├─ tabs.html # Tabs navigation │ ├─ tabs-item.html # Tabs navigation item +│ ├─ tags.html # Tags │ ├─ toc.html # Table of contents │ └─ toc-item.html # Table of contents item ├─ 404.html # 404 error page ├─ base.html # Base template -└─ main.html # Default page +├─ blog.html # Blog index +├─ blog-archive.html # Blog archive index +├─ blog-category.html # Blog category index +├─ blog-post.html # Blog post +└─ main.html # Page ``` [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir @@ -192,6 +204,7 @@ The following template blocks are provided by the theme: | `analytics` | Wraps the Google Analytics integration | | `announce` | Wraps the announcement bar | | `config` | Wraps the JavaScript application config | +| `container` | Wraps the main content container | | `content` | Wraps the main content | | `extrahead` | Empty block to add custom meta tags | | `fonts` | Wraps the font definitions | diff --git a/docs/getting-started.md b/docs/getting-started.md index bd8e26bd6..a0bb59369 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,5 @@ --- template: overrides/main.html -title: Getting started --- # Getting started @@ -19,8 +18,8 @@ If not, we recommend using [`docker`][docker]. ### with pip recommended { #with-pip data-toc-label="with pip" } Material for MkDocs is published as a [Python package] and can be installed with -`pip`, ideally by using a [virtual environment]. If not, scroll down and expand -the help box. Install with: +`pip`, ideally by using a [virtual environment]. Open up a terminal and install +Material for MkDocs with: === "Latest" @@ -38,7 +37,7 @@ the help box. Install with: good idea to limit upgrades to the current major version. This will make sure that you don't accidentally [upgrade to the next - major version], which may include breaking changes that silently break + major version], which may include breaking changes that silently corrupt your site. Additionally, you can use `pip freeze` to create a lockfile, so builds are reproducible at all times: @@ -81,8 +80,8 @@ troubleshoot if you run into errors. ### with docker The official [Docker image] is a great way to get up and running in a few -minutes, as it comes with all dependencies pre-installed. Pull the image for the -`latest` version with: +minutes, as it comes with all dependencies pre-installed. Open up a terminal +and pull the image with: === "Latest" @@ -151,8 +150,8 @@ want to use the very latest version: git clone https://github.com/squidfunk/mkdocs-material.git ``` -The theme will reside in the folder `mkdocs-material/material`. When cloning -from `git`, you must install all required dependencies yourself: +The theme will reside in the folder `mkdocs-material/material`. After cloning +from `git`, you must install all required dependencies with: ``` pip install -e mkdocs-material diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md index b7cb4468a..916b085e8 100644 --- a/docs/insiders/getting-started.md +++ b/docs/insiders/getting-started.md @@ -97,10 +97,9 @@ docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders dedicated token which you'll only use for publishing the Docker image. [^5]: - The Insiders repository contains three GitHub Actions workflows: + The Insiders repository contains two GitHub Actions workflows: - `build.yml` – Build and lint the project (disabled on forks) - - `documentation.yml` – Build and deploy the documentation (disabled on forks) - `publish.yml` – Build and publish the Docker image ### with git @@ -162,7 +161,7 @@ necessary to split the `mkdocs.yml` configuration into a base configuration, and one with plugin overrides. Note that this is a limitation of MkDocs, which can be mitigated by using [configuration inheritance]: -=== ":octicons-file-code-16: mkdocs.insiders.yml" +=== ":octicons-file-code-16: `mkdocs.insiders.yml`" ``` yaml INHERIT: mkdocs.yml @@ -172,7 +171,7 @@ be mitigated by using [configuration inheritance]: - tags ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml # Configuration with everything except Insiders plugins @@ -192,7 +191,7 @@ mkdocs build --config-file mkdocs.insiders.yml the alternative key-value syntax in both files. The above example would then look like: - === ":octicons-file-code-16: mkdocs.insiders.yml" + === ":octicons-file-code-16: `mkdocs.insiders.yml`" ``` yaml INHERIT: mkdocs.yml @@ -200,7 +199,7 @@ mkdocs build --config-file mkdocs.insiders.yml social: {} ``` - === ":octicons-file-code-16: mkdocs.yml" + === ":octicons-file-code-16 `mkdocs.yml`" ``` yaml # Additional configuration above diff --git a/docs/insiders/index.md b/docs/insiders/index.md index d5efef7f3..3d7146300 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -82,14 +82,16 @@ a handful of them, [thanks to our awesome sponsors]! ## What's in for me? The moment you [become a sponsor][how to become a sponsor], you'll get __immediate -access to 25 additional features__ that you can start using right away, and +access to 27 additional features__ that you can start using right away, and which are currently exclusively available to sponsors:
+- [x] [Blog plugin] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" } +- [x] [Blog plugin: related links] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" } - [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" } - [x] [Meta plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" } -- [x] [Additional tags indexes] :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" } +- [x] [Additional tags indexes] - [x] [Document contributors] - [x] [Automatic light / dark mode] - [x] [Content tabs: anchor links] @@ -258,10 +260,10 @@ are released for general availability. - [x] [Excluding content from search] - [x] [Offline plugin] - [Brand new search plugin]: ../blog/2021/search-better-faster-smaller.md - [Rich search previews]: ../blog/2021/search-better-faster-smaller.md#rich-search-previews - [Tokenizer with lookahead]: ../blog/2021/search-better-faster-smaller.md#tokenizer-lookahead - [Advanced search highlighting]: ../blog/2021/search-better-faster-smaller.md#accurate-highlighting + [Brand new search plugin]: ../blog/posts/search-better-faster-smaller.md + [Rich search previews]: ../blog/posts/search-better-faster-smaller.md#rich-search-previews + [Tokenizer with lookahead]: ../blog/posts/search-better-faster-smaller.md#tokenizer-lookahead + [Advanced search highlighting]: ../blog/posts/search-better-faster-smaller.md#accurate-highlighting [Excluding content from search]: ../setup/setting-up-site-search.md#search-exclusion [Offline plugin]: ../setup/building-for-offline-usage.md @@ -272,13 +274,14 @@ are released for general availability. - [x] [Navigation icons] - [x] [Navigation pruning] - [x] [Navigation status] -- [ ] Blog plugin +- [x] [Blog plugin] [Annotations]: ../reference/annotations.md - [Chinese search support]: ../blog/2022/chinese-search-support.md + [Chinese search support]: ../blog/posts/chinese-search-support.md [Navigation icons]: ../reference/index.md#setting-the-page-icon [Navigation pruning]: ../setup/setting-up-navigation.md#navigation-pruning [Navigation status]: ../reference/index.md#setting-the-page-status + [Blog plugin]: ../setup/setting-up-a-blog.md #### $ 14,000 – Goat's Horn @@ -298,14 +301,17 @@ are released for general availability. #### $ 16,000 – Chipotle +- [x] [Blog plugin: related links] - [x] [Meta plugin] - [x] [Additional tags indexes] +- [ ] [Navigation subtitles] - [ ] [Instant previews] - [ ] ... more to be announced [Meta plugin]: ../reference/index.md#built-in-meta-plugin [Additional tags indexes]: ../setup/setting-up-tags.md#tags-extra-files [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743 + [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links ### Goals completed @@ -319,7 +325,7 @@ can be used by all users. - [x] [Was this page helpful?] - [x] [Dismissable announcement bar] - [Cookie consent]: ../setup/ensuring-data-privacy.md#native-cookie-consent + [Cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent [Was this page helpful?]: ../setup/setting-up-site-analytics.md#was-this-page-helpful [Dismissable announcement bar]: ../setup/setting-up-the-header.md#mark-as-read diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 8ad307de6..60078a6e1 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -35,7 +35,7 @@ See additional configuration options: ### Admonition icons -[:octicons-tag-24: 8.3.0][icon support] · +[:octicons-tag-24: 8.3.0][Admonition icons support] · :octicons-beaker-24: Experimental Each of the supported admonition types has a distinct icon, which can be changed @@ -103,7 +103,7 @@ theme: quote: fontawesome/solid/quote-left ``` - [icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0 + [Admonition icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0 [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons [supported types]: #supported-types [icon search]: icons-emojis.md#search @@ -231,7 +231,7 @@ Adding a `+` after the `???` token renders the block expanded: ### Inline blocks -[:octicons-tag-24: 7.0.0][Inline support] · +[:octicons-tag-24: 7.0.0][Inline blocks support] · :octicons-beaker-24: Experimental Admonitions can also be rendered as inline blocks (i.e. for sidebars), placing @@ -283,14 +283,14 @@ prior to the content block you want to place them beside. If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g. on mobile viewports. - [Inline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0 + [Inline blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0 ### Supported types Following is a list of type qualifiers provided by Material for MkDocs, whereas the default type, and thus fallback for unknown type qualifiers, is `note`: -`note`{ #type-note } +[`note`](#type:note){ #type:note } : !!! note @@ -298,7 +298,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`abstract`{ #type-abstract }, `summary`, `tldr` +[`abstract`](#type:abstract){ #type:abstract }, `summary`, `tldr` : !!! abstract @@ -306,7 +306,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`info`{ #type-info }, `todo` +[`info`](#type:info){ #type:info }, `todo` : !!! info @@ -314,7 +314,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`tip`{ #type-tip }, `hint`, `important` +[`tip`](#type:tip){ #type:tip }, `hint`, `important` : !!! tip @@ -322,7 +322,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`success`{ #type-success }, `check`, `done` +[`success`](#type:success){ #type:success }, `check`, `done` : !!! success @@ -330,7 +330,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`question`{ #type-question }, `help`, `faq` +[`question`](#type:question){ #type:question }, `help`, `faq` : !!! question @@ -338,7 +338,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`warning`{ #type-warning }, `caution`, `attention` +[`warning`](#type:warning){ #type:warning }, `caution`, `attention` : !!! warning @@ -346,7 +346,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`failure`{ #type-failure }, `fail`, `missing` +[`failure`](#type:failure){ #type:failure }, `fail`, `missing` : !!! failure @@ -354,7 +354,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`danger`{ #type-danger }, `error` +[`danger`](#type:danger){ #type:danger }, `error` : !!! danger @@ -362,7 +362,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`bug`{ #type-bug } +[`bug`](#type:bug){ #type:bug } : !!! bug @@ -370,7 +370,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`example`{ #type-example } +[`example`](#type:example){ #type:example } : !!! example @@ -378,7 +378,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. -`quote`{ #type-quote }, `cite` +[`quote`](#type:quote){ #type:quote }, `cite` : !!! quote @@ -414,7 +414,7 @@ and add the following CSS to an [additional style sheet]: } -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css :root { @@ -436,7 +436,7 @@ and add the following CSS to an [additional style sheet]: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 3d1a5f9de..e6b770aab 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -126,8 +126,6 @@ import tensorflow as tf ### Adding a title -[:octicons-tag-24: 7.3.6][Title support] - In order to provide additional context, a custom title can be added to a code block by using the `title=""` option directly after the shortcode, e.g. to display the name of a file: @@ -154,8 +152,6 @@ def bubble_sort(items):
- [Title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.6 - ### Adding annotations Code annotations can be placed anywhere in a code block where a comment for the @@ -354,7 +350,7 @@ Let's say you want to change the color of `#!js "strings"`. While there are several [types of string tokens], they use the same color. You can assign a new color by using an [additional style sheet]: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css :root > * { @@ -362,7 +358,7 @@ a new color by using an [additional style sheet]: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: @@ -373,7 +369,7 @@ If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you can lookup the specific CSS class name in the [syntax theme definition], and override it as part of your [additional style sheet]: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css .highlight .sb { @@ -381,7 +377,7 @@ override it as part of your [additional style sheet]: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: @@ -400,7 +396,7 @@ If you have a lot of content hosted inside your code annotations, it can be a good idea to increase the width of the tooltip by adding the following as part of an [additional style sheet]: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css :root { @@ -408,7 +404,7 @@ of an [additional style sheet]: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: @@ -439,7 +435,7 @@ will close them. If you wish to revert to the prior behavior and display code annotation numbers, you can add an [additional style sheet] and copy and paste the following CSS: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css .md-typeset .md-annotation__index > ::before { @@ -450,7 +446,7 @@ you can add an [additional style sheet] and copy and paste the following CSS: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md index 8ec36c7f5..180ca6a87 100644 --- a/docs/reference/content-tabs.md +++ b/docs/reference/content-tabs.md @@ -57,7 +57,7 @@ or to the [publishing guide for Insiders][tab_2]. ### Linked content tabs -[:octicons-tag-24: 8.3.0][link support] · +[:octicons-tag-24: 8.3.0][Linked content tabs support] · :octicons-unlock-24: Feature flag · :octicons-beaker-24: Experimental @@ -76,18 +76,18 @@ tabs with the same label will be activated when a user clicks a content tab regardless of order inside a container. Furthermore, this feature is fully integrated with [instant loading] and persisted across page loads. -=== ":octicons-check-circle-fill-16: Enabled" +=== "Feature enabled" - [![content.tabs.link enabled]][content.tabs.link enabled] + [![Linked content tabs enabled]][Linked content tabs enabled] -=== ":octicons-skip-16: Disabled" +=== "Feature disabled" - [![content.tabs.link disabled]][content.tabs.link disabled] + [![Linked content tabs disabled]][Linked content tabs disabled] - [link support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0 + [Linked content tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0 [instant loading]: ../setup/setting-up-navigation.md#instant-loading - [content.tabs.link enabled]: ../assets/screenshots/content-tabs-link.png - [content.tabs.link disabled]: ../assets/screenshots/content-tabs.png + [Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png + [Linked content tabs disabled]: ../assets/screenshots/content-tabs.png ## Usage diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md index 8f6d83ea2..100cecc34 100644 --- a/docs/reference/data-tables.md +++ b/docs/reference/data-tables.md @@ -131,7 +131,7 @@ If you want to make data tables sortable, you can add [tablesort], which is natively integrated with Material for MkDocs and will also work with [instant loading] via [additional JavaScript]: -=== ":octicons-file-code-16: docs/javascripts/tablesort.js" +=== ":octicons-file-code-16: `docs/javascripts/tablesort.js`" ``` js document$.subscribe(function() { @@ -142,7 +142,7 @@ loading] via [additional JavaScript]: }) ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_javascript: diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index 2b33229eb..e2d824141 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -118,7 +118,7 @@ declarations into dedicated CSS classes: } -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css .twitter { @@ -126,7 +126,7 @@ declarations into dedicated CSS classes: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: @@ -155,7 +155,7 @@ Similar to adding [colors], it's just as easy to add [animations] to icons by using an [additional style sheet], defining a `@keyframes` rule and adding a dedicated CSS class to the icon: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css @keyframes heart { @@ -171,7 +171,7 @@ dedicated CSS class to the icon: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: diff --git a/docs/reference/images.md b/docs/reference/images.md index bc23abfd4..88192bd9c 100644 --- a/docs/reference/images.md +++ b/docs/reference/images.md @@ -32,7 +32,7 @@ See additional configuration options: ### Lightbox -[:octicons-tag-24: 0.1.0][glightbox support] · +[:octicons-tag-24: 0.1.0][Lightbox support] · [:octicons-cpu-24: Plugin][glightbox] If you want to add image zoom functionality to your documentation, the @@ -53,7 +53,7 @@ plugins: We recommend checking out the available [configuration options][glightbox options]. - [glightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Lightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [glightbox]: https://github.com/blueswen/mkdocs-glightbox [glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage diff --git a/docs/reference/index.md b/docs/reference/index.md index 032ef47b1..2d2826031 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -33,7 +33,7 @@ plugins: The following configuration options are available: -`meta_file`{ #meta-file } +[`meta_file`](#+meta.meta_file){ #+meta.meta_file } : :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the name of the meta files that the plugin should look for. The default setting @@ -57,7 +57,7 @@ The following configuration options are available: The page title can be overridden for a document with the front matter `title` property. Add the following lines at the top of a Markdown file: -``` sh +``` yaml --- title: Lorem ipsum dolor sit amet # (1)! --- @@ -79,7 +79,7 @@ title: Lorem ipsum dolor sit amet # (1)! The page description can be overridden for a document with the front matter `description` property. Add the following lines at the top of a Markdown file: -``` sh +``` yaml --- description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! --- @@ -100,7 +100,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)! An icon can be assigned to each page, which is then rendered as part of the navigation sidebar. Add the following lines at the top of a Markdown file: -``` sh +``` yaml --- icon: material/emoticon-happy # (1)! --- @@ -153,7 +153,7 @@ The page status can now be set for a document with the front matter `status` property. For example, you can mark a page as `new` with the following lines at the top of a Markdown file: -``` sh +``` yaml --- status: new --- @@ -173,7 +173,7 @@ If you're using [theme extension] and created a new page template in the `overrides` directory, you can enable it for a specific page. Add the following lines at the top of a Markdown file: -``` sh +``` yaml --- template: custom.html --- @@ -185,7 +185,7 @@ template: custom.html ??? question "How to set a page template for an entire folder?" With the help of the [built-in meta plugin], you can set a custom template - for an entire section and all nested pages, by creating a `.meta.yml` + for an entire section and all nested pages, by creating a `.meta.yml` file in the corresponding folder with the following content: ``` yaml diff --git a/docs/reference/mathjax.md b/docs/reference/mathjax.md index dd4c99738..960828465 100644 --- a/docs/reference/mathjax.md +++ b/docs/reference/mathjax.md @@ -21,7 +21,7 @@ This configuration enables support for rendering block and inline block equations through [MathJax]. Create a configuration file and add the following lines to `mkdocs.yml`: -=== ":octicons-file-code-16: docs/javascripts/mathjax.js" +=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`" ``` js window.MathJax = { @@ -44,7 +44,7 @@ lines to `mkdocs.yml`: 1. This integrates MathJax with [instant loading]. -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml markdown_extensions: diff --git a/docs/reference/tooltips.md b/docs/reference/tooltips.md index b65c7b1c0..efdebb339 100644 --- a/docs/reference/tooltips.md +++ b/docs/reference/tooltips.md @@ -4,18 +4,18 @@ icon: material/tooltip-plus status: new --- -# Tooltips +# Abbreviations -Material for MkDocs makes it trivial to add tooltips to links, abbreviations -and all other elements, which allows for implementing glossary-like -functionality, as well as small hints that are shown when the user hovers or -focuses an element. +Technical documentation often incurs the usage of many acronyms, which may +need additional explanation, especially for new user of your project. For these +matters, Material for MkDocs uses a combination of Markdown extensions to +enable site-wide glossaries. ## Configuration -This configuration enables support for tooltips and abbreviations and allows to -build a simple glossary, sourcing definitions from a central location. Add the -following lines to `mkdocs.yml`: +This configuration enables abbreviations and allows to build a simple +project-wide glossary, sourcing definitions from a central location. Add the +following line to `mkdocs.yml`: ``` yaml markdown_extensions: @@ -108,7 +108,7 @@ extension: ### Adding abbreviations -Abbreviations can be defined by using a special syntax similar to [links] and +Abbreviations can be defined by using a special syntax similar to URLs and [footnotes], starting with a `*` and immediately followed by the term or acronym to be associated in square brackets: @@ -128,7 +128,6 @@ The HTML specification is maintained by the W3C. - [links]: #adding-tooltips [footnotes]: footnotes.md ### Adding a glossary @@ -143,14 +142,14 @@ pages with the following configuration: `includes` is used), as MkDocs might otherwise complain about an unreferenced file. -=== ":octicons-file-code-16: includes/abbreviations.md" +=== ":octicons-file-code-16: `includes/abbreviations.md`" ```` markdown *[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium ```` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ```` yaml markdown_extensions: diff --git a/docs/schema/extensions/markdown.json b/docs/schema/extensions/markdown.json index 99563b0a6..bb2f9ddbd 100644 --- a/docs/schema/extensions/markdown.json +++ b/docs/schema/extensions/markdown.json @@ -91,17 +91,17 @@ "type": "object", "properties": { "title": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-title", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.title", "type": "string" }, "permalink": { "oneOf": [ { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-permalink", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink", "type": "boolean" }, { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-permalink", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink", "type": "string" } ], @@ -113,15 +113,15 @@ "default": false }, "permalink_title": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-permalink-title", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.permalink_title", "type": "string" }, "slugify": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-slugify", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.slugify", "type": "string" }, "toc_depth": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#toc-depth", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.toc_depth", "type": "number", "enum": [ 0, diff --git a/docs/schema/extensions/pymdownx.json b/docs/schema/extensions/pymdownx.json index 6617b857f..917b7859f 100644 --- a/docs/schema/extensions/pymdownx.json +++ b/docs/schema/extensions/pymdownx.json @@ -127,7 +127,7 @@ "type": "object", "properties": { "mode": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#critic-mode", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.critic.mode", "enum": [ "view", "accept", @@ -158,24 +158,24 @@ "type": "object", "properties": { "emoji_generator": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#options", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator", "type": "string", "default": "!!python/name:materialx.emoji.to_svg" }, "emoji_index": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#options", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index", "type": "string", "default": "!!python/name:materialx.emoji.twemoji" }, "options": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#custom-icons", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons", "type": "object", "properties": { "custom_icons": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#custom-icons", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons", "type": "array", "items": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#custom-icons", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons", "type": "string" }, "uniqueItems": true, @@ -212,11 +212,11 @@ "type": "object", "properties": { "use_pygments": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-use-pygments", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.use_pygments", "type": "boolean" }, "auto_title": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-auto-title", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.auto_title", "type": "boolean" }, "auto_title_map": { @@ -224,11 +224,11 @@ "type": "object" }, "linenums": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-linenums", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.linenums", "type": "boolean" }, "linenums_style": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-linenums-style", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.linenums_style", "enum": [ "inline", "pymdownx-inline", @@ -236,7 +236,7 @@ ] }, "anchor_linenums": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight-anchor-linenums", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.anchor_linenums", "type": "boolean" } }, @@ -359,7 +359,8 @@ "properties": { "smart_mark": { "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "type": "boolean", + "default": true } }, "additionalProperties": false @@ -386,45 +387,50 @@ "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#smartsymbols", "type": "object", "properties": { - "smart_mark": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" - }, "trademark": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "copyright": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "registered": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "care_of": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "plusminus": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "arrows": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "notequal": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "fractions": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true }, "ordinal_numbers": { - "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/mark/#options", - "type": "boolean" + "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/#options", + "type": "boolean", + "default": true } }, "additionalProperties": false @@ -496,10 +502,10 @@ "type": "object", "properties": { "custom_fences": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences-custom-fences", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.superfences.custom_fences", "type": "array", "items": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences-custom-fences", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.superfences.custom_fences", "type": "object", "properties": { "name": { @@ -561,12 +567,12 @@ "type": "object", "properties": { "custom_checkbox": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist-custom-checkbox", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tasklist.custom_checkbox", "type": "boolean", "default": true }, "clickable_checkbox": { - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tasklist-clickable-checkbox", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tasklist.clickable_checkbox", "type": "boolean" } }, diff --git a/docs/schema/extra.json b/docs/schema/extra.json index 118f26fd2..b4f657cf6 100644 --- a/docs/schema/extra.json +++ b/docs/schema/extra.json @@ -72,17 +72,17 @@ }, "name": { "title": "Feedback rating name", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#feedback-rating-name", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.name", "type": "string" }, "data": { "title": "Feedback rating data", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#feedback-rating-data", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.data", "type": "number" }, "note": { "title": "Feedback rating data", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#feedback-rating-note", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/#+analytics.feedback.ratings.note", "type": "string" } }, @@ -139,18 +139,18 @@ "properties": { "title": { "title": "Cookie consent title", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.title", "type": "string", "default": "Cookie consent" }, "description": { "title": "Cookie consent description", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.description", "type": "string" }, "cookies": { "title": "Cookies", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.cookies", "type": "object", "properties": { "analytics": { @@ -166,7 +166,7 @@ "defaultSnippets": [ { "label": "analytics (default)", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.cookies", "body": { "analytics": { "name": "Google Analytics", @@ -178,7 +178,7 @@ }, "actions": { "title": "Cookie consent actions", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.actions", "type": "array", "items": { "oneOf": [ @@ -208,7 +208,7 @@ "defaultSnippets": [ { "label": "actions (default)", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+consent.actions", "body": { "actions": [ "accept", @@ -235,12 +235,12 @@ }, "link": { "title": "Social link", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-link", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#+social.link", "type": "string" }, "name": { "title": "Social link name", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-name", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#+social.name", "type": "string" } }, @@ -262,17 +262,17 @@ "properties": { "name": { "title": "Alternate language name", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#language-name", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#+alternate.name", "type": "string" }, "link": { "title": "Alternate language link", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#language-link", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#+alternate.link", "type": "string" }, "lang": { "title": "Alternate language code (ISO 639-1)", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#language-lang", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#+alternate.lang", "type": "string" } }, diff --git a/docs/schema/plugins.json b/docs/schema/plugins.json index adcb7dce8..b46719581 100644 --- a/docs/schema/plugins.json +++ b/docs/schema/plugins.json @@ -22,6 +22,9 @@ "built-in": { "description": "Built-in plugins", "oneOf": [ + { + "$ref": "plugins/blog.json" + }, { "$ref": "plugins/meta.json" }, diff --git a/docs/schema/plugins/blog.json b/docs/schema/plugins/blog.json new file mode 100644 index 000000000..84f714f6f --- /dev/null +++ b/docs/schema/plugins/blog.json @@ -0,0 +1,327 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema", + "title": "Built-in blog plugin", + "oneOf": [ + { + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin", + "enum": [ + "blog" + ] + }, + { + "type": "object", + "properties": { + "blog": { + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin", + "type": "object", + "properties": { + "enabled": { + "title": "Enable plugin", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.enabled", + "type": "boolean", + "default": true + }, + "blog_dir": { + "title": "Blog directory", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_dir", + "type": "string", + "default": "blog" + }, + "blog_custom_dir": { + "title": "Blog template directory (internal)", + "markdownDescription": "Warning: this option is for internal use only, use at your own risk", + "type": "string" + }, + "post_date_format": { + "title": "Format string for post dates", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format", + "oneOf": [ + { + "enum": [ + "full", + "long", + "medium", + "short" + ] + }, + { + "type": "string" + } + ], + "default": "long" + }, + "post_url_date_format": { + "title": "Format string for post dates in URLs", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_date_format", + "oneOf": [ + { + "enum": [ + "YYYY", + "YYYY/MM", + "YYYY/MM/dd" + ] + }, + { + "type": "string" + } + ], + "default": "YYYY" + }, + "post_url_format": { + "title": "Format string for post URLs", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_format", + "oneOf": [ + { + "enum": [ + "\"{date}/{slug}\"", + "\"{slug}\"" + ] + }, + { + "type": "string" + } + ] + }, + "post_slugify": { + "title": "Post slugify function", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify", + "type": "string", + "default": "!!python/name:pymdownx.slugs.uslugify" + }, + "post_slugify_separator": { + "title": "Post slugify separator", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify_separator", + "type": "string", + "default": "\"-\"" + }, + "post_excerpt": { + "title": "Post excerpts", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt", + "oneOf": [ + { + "title": "Post excerpts are optional", + "enum": [ + "optional" + ] + }, + { + "title": "Post excerpts are required, thus the build will fail", + "enum": [ + "required" + ] + } + ], + "default": "optional" + }, + "post_excerpt_separator": { + "title": "Post excerpt separator", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_separator", + "type": "string", + "default": "" + }, + "post_readtime": { + "title": "Post reading time computation", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime", + "type": "boolean", + "default": true + }, + "post_readtime_words_per_minute": { + "title": "Post reading time words per minute", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime_words_per_minute", + "type": "number", + "default": 265 + }, + "archive": { + "title": "Archive", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive", + "type": "boolean", + "default": true + }, + "archive_name": { + "title": "Archive name", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_name", + "type": "string", + "default": "Archive" + }, + "archive_date_format": { + "title": "Format string for archive dates", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_date_format", + "oneOf": [ + { + "enum": [ + "YYYY", + "MMMM YYYY" + ] + }, + { + "type": "string" + } + ], + "default": "YYYY" + }, + "archive_url_date_format": { + "title": "Format string for archive dates in URLs", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_date_format", + "oneOf": [ + { + "enum": [ + "YYYY", + "YYYY/MM" + ] + }, + { + "type": "string" + } + ], + "default": "YYYY" + }, + "archive_url_format": { + "title": "Format string for archive URLs", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_format", + "oneOf": [ + { + "enum": [ + "\"archive/{date}\"" + ] + }, + { + "type": "string" + } + ] + }, + "categories": { + "title": "Categories", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories", + "type": "boolean", + "default": true + }, + "categories_name": { + "title": "Categories name", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_name", + "type": "string", + "default": "Categories" + }, + "categories_url_format": { + "title": "Format string for category URLs", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_url_format", + "oneOf": [ + { + "enum": [ + "\"category/{slug}\"", + "\"{slug}\"" + ] + }, + { + "type": "string" + } + ] + }, + "categories_slugify": { + "title": "Categories slugify function", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify", + "type": "string", + "default": "!!python/name:pymdownx.slugs.uslugify" + }, + "categories_slugify_separator": { + "title": "Categories slugify separator", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify_separator", + "type": "string", + "default": "\"-\"" + }, + "categories_allowed": { + "title": "Categories allowed", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed", + "type": "array", + "items": { + "type": "string" + }, + "default": [] + }, + "pagination": { + "title": "Pagination", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination", + "type": "boolean", + "default": true + }, + "pagination_per_page": { + "title": "Posts per page", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_per_page", + "type": "number", + "default": 10 + }, + "pagination_url_format": { + "title": "Format string for pagination URLs", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_url_format", + "oneOf": [ + { + "enum": [ + "\"page/{page}\"", + "\"{page}\"" + ] + }, + { + "type": "string" + } + ] + }, + "pagination_template": { + "title": "Template string for pagination", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_template", + "oneOf": [ + { + "enum": [ + "~2~", + "$link_first $link_previous ~2~ $link_next $link_last", + "$link_previous $page $link_next" + ] + }, + { + "type": "string" + } + ], + "default": "~2~" + }, + "authors": { + "title": "Author info", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors", + "type": "boolean", + "default": true + }, + "authors_file": { + "title": "Authors file", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file", + "type": "string", + "default": ".authors.yml" + }, + "authors_in_excerpt": { + "title": "Number of authors to render in post excerpts", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_in_excerpt", + "type": "number", + "default": 1 + }, + "draft": { + "title": "Render posts marked as drafts", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft", + "type": "boolean", + "default": false + }, + "draft_on_serve": { + "title": "Render posts marked as drafts when previewing", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_on_serve", + "type": "boolean", + "default": true + }, + "draft_if_future_date": { + "title": "Automatically mark posts with future dates as drafts", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_if_future_date", + "type": "boolean", + "default": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + ] +} diff --git a/docs/schema/plugins/external/git-committers.json b/docs/schema/plugins/external/git-committers.json index c6c43f0ab..2d1caf5d4 100644 --- a/docs/schema/plugins/external/git-committers.json +++ b/docs/schema/plugins/external/git-committers.json @@ -23,12 +23,12 @@ }, "repository": { "title": "Repository slug", - "markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#+git-committers.repository", "type": "string" }, "token": { "title": "Personal access token", - "markdownDescription": "https://github.com/ojacques/mkdocs-git-committers-plugin-2#config", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#+git-committers.token", "type": "string" } }, diff --git a/docs/schema/plugins/meta.json b/docs/schema/plugins/meta.json index d1d9cb1b0..aef3495dd 100644 --- a/docs/schema/plugins/meta.json +++ b/docs/schema/plugins/meta.json @@ -17,7 +17,7 @@ "properties": { "meta_file": { "title": "Meta file name", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#meta-file", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+meta.meta_file", "pattern": "\\.yml$", "default": "\"**/.meta.yml\"" } diff --git a/docs/schema/plugins/offline.json b/docs/schema/plugins/offline.json index 36281cad2..e97b620aa 100644 --- a/docs/schema/plugins/offline.json +++ b/docs/schema/plugins/offline.json @@ -17,7 +17,7 @@ "properties": { "enabled": { "title": "Enable plugin", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#enabled", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#+offline.enabled", "type": "boolean", "default": true } diff --git a/docs/schema/plugins/privacy.json b/docs/schema/plugins/privacy.json index d229704d5..5ee1675e1 100644 --- a/docs/schema/plugins/privacy.json +++ b/docs/schema/plugins/privacy.json @@ -17,13 +17,13 @@ "properties": { "enabled": { "title": "Enable plugin", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#enabled", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.enabled", "type": "boolean", "default": true }, "externals": { "title": "External assets", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals", "oneOf": [ { "title": "Bundle external assets", @@ -42,17 +42,17 @@ }, "externals_dir": { "title": "External assets download directory", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals-dir", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_dir", "type": "string", "default": "assets/externals" }, "externals_exclude": { "title": "External assets to be excluded", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals-exclude", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_exclude", "type": "array", "items": { "title": "External assets matching this pattern will not be bundled", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#externals-exclude", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.externals_exclude", "pattern": ".*" }, "uniqueItems": true, diff --git a/docs/schema/plugins/search.json b/docs/schema/plugins/search.json index ce4892090..f99370e31 100644 --- a/docs/schema/plugins/search.json +++ b/docs/schema/plugins/search.json @@ -33,17 +33,17 @@ }, "separator": { "title": "Separator for indexing and query tokenization", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-separator", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.separator", "type": "string" }, "jieba_dict": { "title": "Jieba dictionary replacement", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#jieba-dict", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict", "type": "string" }, "jieba_dict_user": { "title": "Jieba dictionary augmentation", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#jieba-dict", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict_user", "type": "string" } }, @@ -56,7 +56,7 @@ "definitions": { "lang": { "title": "Site search language", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-lang", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.lang", "oneOf": [ { "title": "Site search language: Arabic", diff --git a/docs/schema/plugins/social.json b/docs/schema/plugins/social.json index e70c9cc8a..161d7cf8c 100644 --- a/docs/schema/plugins/social.json +++ b/docs/schema/plugins/social.json @@ -17,23 +17,23 @@ "properties": { "cards": { "title": "Social card generation", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards", "type": "boolean", "default": true }, "cards_color": { "title": "Social card color palette", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-color", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color", "type": "object", "properties": { "fill": { "title": "Background fill color", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-color", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color", "type": "string" }, "text": { "title": "Foreground text color", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-color", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color", "type": "string" } }, @@ -48,7 +48,7 @@ }, "cards_dir": { "title": "Social card directory", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#cards-dir", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir", "type": "string", "default": "assets/images/social" } diff --git a/docs/schema/plugins/tags.json b/docs/schema/plugins/tags.json index 5a7ab1aa8..72b89b966 100644 --- a/docs/schema/plugins/tags.json +++ b/docs/schema/plugins/tags.json @@ -17,13 +17,13 @@ "properties": { "tags_file": { "title": "Markdown file to render tags index", - "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#tags-file", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.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/setup/setting-up-tags/#tags-extra-files", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_extra_files", "type": "object", "patternProperties": { "\\.md$": { diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 045bae784..a1a3eafed 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -42,24 +42,14 @@ Before you can use [Giscus], you need to complete the following steps: ``` -You can either integrate [Giscus] on every page by overriding the `main.html` -template, or create a new template (e.g. `blog.html`) to extend from `main.html` -which includes the comment system, so you can decide for each page whether you -want to allow comments or not. +The by default empty [`comments.html`][comments] partial is the best place to +add the code snippet generated by [Giscus]. Follow the guide on [theme extension] +and [override the `comments.html` partial][overriding partials] with: -In order to integrate [Giscus], follow the guide on [theme extension] and -[override the `content` block][overriding blocks], extending the default by -calling the `super()` function at the beginning of the block: - -``` html hl_lines="8" -{% extends "base.html" %} - -{% block content %} - {{ super() }} - - +``` html hl_lines="3" +{% if page.meta.comments %}

{{ lang.t("meta.comments") }}

- + -{% endblock %} +{% endif %} ``` 1. This code block ensures that [Giscus] renders with a dark theme when the @@ -98,12 +88,24 @@ calling the `super()` function at the beginning of the block: so you can change it to your liking. Replace the highlighted line with the snippet you generated with the [Giscus] -configuration tool in the previous step. If you extended `main.html`, you should -now see the [Giscus] comment system at the bottom of each page. If you created -a new, separate template, you can enable Giscus by [setting the page template] -via front matter. +configuration tool in the previous step. If you copied the snippet from above, +you can enable comments on a page by setting the `comments` front matter +property to `true`: + +``` yaml +--- +comments: true +--- + +# Document title +... +``` + +If you wish to enable comments for an entire folder, you can use the +[built-in meta plugin]. [Giscus GitHub App]: https://github.com/apps/giscus [theme extension]: ../customization.md#extending-the-theme - [overriding blocks]: ../customization.md#overriding-blocks - [setting the page template]: ../reference/index.md#setting-the-page-template + [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html + [overriding partials]: ../customization.md#overriding-partials + [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index 6da55fd13..8b6f0634c 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -13,7 +13,7 @@ static site, including stars and forks. Furthermore, the ### Repository -[:octicons-tag-24: 0.1.0][repo_url support] · +[:octicons-tag-24: 0.1.0][Repository support] · :octicons-milestone-24: Default: _none_ In order to display a link to the repository of your project as part of your @@ -37,14 +37,14 @@ GitHub repositories also include the tag of the latest release.[^1] pre-release) for the latest tag you want to display next to the number of stars and forks. - [repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Repository support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url [latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release [create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release #### Repository name -[:octicons-tag-24: 0.1.0][repo_name support] · +[:octicons-tag-24: 0.1.0][Repository name support] · :octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket` @@ -56,14 +56,14 @@ _repository name_ automatically. If you wish to customize the name, set repo_name: squidfunk/mkdocs-material ``` - [repo_name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Repository name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name #### Repository icon -[:octicons-tag-24: 5.0.0][icon.repo support] · +[:octicons-tag-24: 5.0.0][Repository icon support] · :octicons-milestone-24: Default: -[`fontawesome/brands/git-alt`][icon.repo default] +:fontawesome-brands-git-alt: – `fontawesome/brands/git-alt` While the default repository icon is a generic git icon, it can be set to any icon bundled with the theme by referencing a valid icon path in @@ -97,13 +97,13 @@ Some popular choices: - :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket` - :fontawesome-solid-trash: – `fontawesome/solid/trash` - [icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0 - [icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg + [Repository icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0 + [Repository icon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg [icon search]: ../reference/icons-emojis.md#search #### Edit button -[:octicons-tag-24: 0.1.0][edit_uri support] · +[:octicons-tag-24: 0.1.0][Edit button support] · :octicons-milestone-24: Default: _automatically set_ If the repository URL points to a [GitHub], [GitLab] or [Bitbucket] repository, @@ -122,7 +122,26 @@ changed by setting [`edit_uri`][edit_uri] in `mkdocs.yml`: edit_uri: "" ``` - [edit_uri support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 +The icon of the edit button can be changed with the following lines: + +``` yaml +theme: + icon: + edit: material/pencil # (1)! +``` + +1. Enter a few keywords to find the perfect icon using our [icon search] and + click on the shortcode to copy it to your clipboard: + +
+ +
+
+
    +
    +
    + + [Edit button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri [GitHub]: https://github.com/ [GitLab]: https://about.gitlab.com/ @@ -140,7 +159,7 @@ links to all [contributors] or [authors] involved. #### Document dates -[:octicons-tag-24: 4.6.0][git-revision-date-localized support] · +[:octicons-tag-24: 4.6.0][Document dates support] · [:octicons-cpu-24: Plugin][git-revision-date-localized] The [git-revision-date-localized] plugin adds support for adding the date of @@ -161,7 +180,7 @@ plugins: The following configuration options are supported: -`type`{ #type } +[`type`](#+git-revision-date-localized.type){ #+git-revision-date-localized.type } : :octicons-milestone-24: Default: `date` – The format of the date to be displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime` @@ -173,10 +192,9 @@ The following configuration options are supported: type: date ``` -`enable_creation_date`{ #enable-creation-date } +[`enable_creation_date`](#+git-revision-date-localized.enable_creation_date){ #+git-revision-date-localized.enable_creation_date } -: [:octicons-tag-24: 7.1.4][enable_creation_date support] · - :octicons-milestone-24: Default: `false` – Enables the display of the +: :octicons-milestone-24: Default: `false` – Enables the display of the creation date of the file associated with the page next to the last updated date at the bottom of the page: @@ -186,7 +204,7 @@ The following configuration options are supported: enable_creation_date: true ``` -`fallback_to_build_date`{ #fallback-to-build-date } +[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date } : :octicons-milestone-24: Default: `false` – Enables falling back to the time when `mkdocs build` was executed. Can be used as a fallback when @@ -202,9 +220,8 @@ The other configuration options of this extension are not officially supported by Material for MkDocs, which is why they may yield unexpected results. Use them at your own risk. - [git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0 + [Document dates support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0 [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin - [enable_creation_date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.4 #### Document contributors @@ -238,9 +255,9 @@ plugins: The following configuration options are supported: -`repository`{ #committers-repository } +[`repository`](#+git-committers.repository){ #+git-committers.repository } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property must be set to the slug of the repository that contains your documentation. The slug must follow the pattern `/`: @@ -250,7 +267,7 @@ The following configuration options are supported: repository: squidfunk/mkdocs-material ``` -`token`{ #committers-repository } +[`token`](#+git-committers.token){ #+git-committers.token } : :octicons-milestone-24: Default: _none_ – This property should[^3] be set to a [personal access token], which is used by the plugin to query GitHub's API diff --git a/docs/setup/building-for-offline-usage.md b/docs/setup/building-for-offline-usage.md index 3dfaab680..ddba28612 100644 --- a/docs/setup/building-for-offline-usage.md +++ b/docs/setup/building-for-offline-usage.md @@ -49,7 +49,7 @@ from the local file system. The following configuration options are available: -`enabled`{ #enabled } +[`enabled`](#+offline.enabled){ #+offline.enabled } : :octicons-milestone-24: Default: `true` – This option specifies whether the plugin is enabled when building your project. If you want to switch diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index bf503e530..a40d45aa8 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -18,7 +18,7 @@ fit your brand's identity by using [CSS variables][custom colors]. #### Color scheme -[:octicons-tag-24: 5.2.0][palette.scheme support] · +[:octicons-tag-24: 5.2.0][Color scheme support] · :octicons-milestone-24: Default: `default` Material for MkDocs supports two color schemes: a __light mode__, which is just @@ -50,11 +50,11 @@ Click on a tile to change the color scheme: }) - [palette.scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 + [Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 #### Primary color -[:octicons-tag-24: 0.2.0][palette.primary support] · +[:octicons-tag-24: 0.2.0][Primary color support] · :octicons-milestone-24: Default: `indigo` The primary color is used for the header, the sidebar, text links and several @@ -105,11 +105,11 @@ Click on a tile to change the primary color: }) - [palette.primary support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 + [Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 #### Accent color -[:octicons-tag-24: 0.2.0][palette.accent support] · +[:octicons-tag-24: 0.2.0][Accent color support] · :octicons-milestone-24: Default: `indigo` The accent color is used to denote elements that can be interacted with, e.g. @@ -162,11 +162,11 @@ Click on a tile to change the accent color: }) - [palette.accent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 + [Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0 ### Color palette toggle -[:octicons-tag-24: 7.1.0][palette.toggle support] · +[:octicons-tag-24: 7.1.0][Color palette toggle support] · :octicons-milestone-24: Default: _none_ Offering a light _and_ dark color palette makes your documentation pleasant to @@ -209,9 +209,9 @@ and [`accent`][palette.accent] per color palette. The following properties must be set for each toggle: -`icon`{ #toggle-icon } +[`icon`](#+palette.toggle.icon){ #+palette.toggle.icon } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations: @@ -221,13 +221,13 @@ The following properties must be set for each toggle: * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline` * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline` -`name`{ #toggle-name } +[`name`](#+palette.toggle.name){ #+palette.toggle.name } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property is used as the toggle's `title` attribute and should be set to a discernable name to improve accessibility. It's rendered as a [tooltip]. - [palette.toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 + [Color palette toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 [palette.scheme]: #color-scheme [palette.primary]: #primary-color [palette.accent]: #accent-color @@ -236,7 +236,7 @@ The following properties must be set for each toggle: ### System preference -[:octicons-tag-24: 7.1.0][palette.media support] · +[:octicons-tag-24: 7.1.0][System preference support] · :octicons-milestone-24: Default: _none_ Each color palette can be linked to the user's system preference for light and @@ -266,7 +266,7 @@ When the user first visits your site, the media queries are evaluated in the order of their definition. The first media query that matches selects the default color palette. - [palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 + [System preference support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 #### Automatic light / dark mode @@ -327,7 +327,7 @@ Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" } __YouTube__, and want to set the primary color to your brand's palette. Just add: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css :root > * { @@ -337,7 +337,7 @@ add: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: @@ -358,7 +358,7 @@ by wrapping the definitions in a `[data-md-color-scheme="..."]` [attribute selector], which you can then set via `mkdocs.yml` as described in the [color schemes][palette.scheme] section: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css [data-md-color-scheme="youtube"] { @@ -368,7 +368,7 @@ in the [color schemes][palette.scheme] section: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml theme: diff --git a/docs/setup/changing-the-fonts.md b/docs/setup/changing-the-fonts.md index d431c937b..ab8a5d239 100644 --- a/docs/setup/changing-the-fonts.md +++ b/docs/setup/changing-the-fonts.md @@ -15,7 +15,7 @@ or another destination should be used. ### Regular font -[:octicons-tag-24: 0.1.2][font support] · +[:octicons-tag-24: 0.1.2][Font support] · :octicons-milestone-24: Default: [`Roboto`][Roboto] The regular font is used for all body copy, headlines, and essentially @@ -31,11 +31,11 @@ theme: The typeface will be loaded in 300, 400, _400i_ and __700__. [Roboto]: https://fonts.google.com/specimen/Roboto - [font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2 + [Font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2 ### Monospaced font -[:octicons-tag-24: 0.1.2][font support] · +[:octicons-tag-24: 0.1.2][Font support] · :octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono] The _monospaced font_ is used for code blocks and can be configured separately. @@ -54,7 +54,7 @@ The typeface will be loaded in 400. ### Autoloading -[:octicons-tag-24: 1.0.0][font=false support] · +[:octicons-tag-24: 1.0.0][Autoloading support] · :octicons-milestone-24: Default: _none_ If you want to prevent typefaces from being loaded from [Google Fonts], e.g. @@ -73,7 +73,7 @@ theme: by automatically downloading and self-hosting the web font files. [data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users - [font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 + [Autoloading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0 [built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin ## Customization @@ -84,7 +84,7 @@ If you want to load an (additional) font from another destination or override the system font, you can use an [additional style sheet] to add the corresponding `@font-face` definition: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css @font-face { @@ -93,7 +93,7 @@ corresponding `@font-face` definition: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md index b1eb0a67e..598f53dd5 100644 --- a/docs/setup/changing-the-language.md +++ b/docs/setup/changing-the-language.md @@ -13,7 +13,7 @@ available. ### Site language -[:octicons-tag-24: 1.12.0][language support] · +[:octicons-tag-24: 1.12.0][Site language support] · :octicons-milestone-24: Default: `en` You can set the site language in `mkdocs.yml` with: @@ -100,7 +100,7 @@ The following languages are supported: Note that some languages will produce unreadable anchor links due to the way the default slug function works. Consider using a [Unicode-aware slug function]. - [language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0 + [Site language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0 [single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes [language selector]: #site-language-selector [Unicode-aware slug function]: extensions/python-markdown.md#toc-slugify @@ -108,7 +108,7 @@ the default slug function works. Consider using a [Unicode-aware slug function]. ### Site language selector -[:octicons-tag-24: 7.0.0][alternate support] · +[:octicons-tag-24: 7.0.0][Site language selector support] · :octicons-milestone-24: Default: _none_ · :octicons-beaker-24: Experimental @@ -133,35 +133,35 @@ extra: The following properties are available for each alternate language: -`name`{ #language-name } +[`name`](#+alternate.name){ #+alternate.name } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This value of this property is used inside the language selector as the name of the language and must be set to a non-empty string. -`link`{ #language-link } +[`link`](#+alternate.link){ #+alternate.link } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property must be set to an absolute link, which might also point to another domain or subdomain not necessarily generated with MkDocs. -`lang`{ #language-lang } +[`lang`](#+alternate.lang){ #+alternate.lang } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property must contain an [ISO 639-1 language code] and is used for the `hreflang` attribute of the link, improving discoverability via search engines. [![Language selector preview]][Language selector preview] - [alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0 + [Site language selector support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0 [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes [Language selector preview]: ../assets/screenshots/language-selection.png ### Directionality -[:octicons-tag-24: 2.5.0][direction support] · +[:octicons-tag-24: 2.5.0][Directionality support] · :octicons-milestone-24: Default: _automatically set_ While many languages are read `ltr` (left-to-right), Material for MkDocs also @@ -192,7 +192,7 @@ Click on a tile to change the directionality: }) - [direction support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0 + [Directionality support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0 ## Customization @@ -203,7 +203,7 @@ the guide on [theme extension] and create a new partial in the `overrides` folder. Then, import the [translations] of the language as a fallback and only adjust the ones you want to override: -=== ":octicons-file-code-16: overrides/partials/languages/custom.html" +=== ":octicons-file-code-16: `overrides/partials/languages/custom.html`" ``` html @@ -228,7 +228,7 @@ adjust the ones you want to override: 2. Check the [list of available languages], pick the translation you want to override for your language and add them here. -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml theme: diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md index 54e9da5f3..57cbcc9c6 100644 --- a/docs/setup/changing-the-logo-and-icons.md +++ b/docs/setup/changing-the-logo-and-icons.md @@ -15,8 +15,8 @@ when writing your documentation in Markdown. Not enough? You can also add ### Logo -[:octicons-tag-24: 0.1.0][logo support] · -:octicons-milestone-24: Default: [`material/library`][logo default] +[:octicons-tag-24: 0.1.0][Logo support] · +:octicons-milestone-24: Default: :material-library: – `material/library` The logo can be changed to a user-provided image (any type, incl. `*.png` and `*.svg`) located in the `docs` folder, or to any icon bundled with the theme. @@ -48,8 +48,7 @@ Add the following lines to `mkdocs.yml`: - [logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 - [logo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/material/library.svg + [Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 [icon search]: ../reference/icons-emojis.md#search Normally, the logo in the header and sidebar links to the homepage of the @@ -63,8 +62,8 @@ extra: ### Favicon -[:octicons-tag-24: 0.1.0][favicon support] · -:octicons-milestone-24: Default: [`assets/images/favicon.png`][favicon default] +[:octicons-tag-24: 0.1.0][Favicon support] · +:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default] The favicon can be changed to a path pointing to a user-provided image, which must be located in the `docs` folder. Add the following lines to `mkdocs.yml`: @@ -74,8 +73,8 @@ theme: favicon: images/favicon.png ``` - [favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 - [favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png + [Favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0 + [Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png ## Customization diff --git a/docs/setup/ensuring-data-privacy.md b/docs/setup/ensuring-data-privacy.md index 8d7a04271..cf2ba7306 100644 --- a/docs/setup/ensuring-data-privacy.md +++ b/docs/setup/ensuring-data-privacy.md @@ -9,15 +9,15 @@ as it offers a native [cookie consent] solution to seek explicit consent from users before setting up [tracking]. Additionally, external assets can be automatically downloaded for [self-hosting]. - [cookie consent]: #native-cookie-consent + [cookie consent]: #cookie-consent [tracking]: setting-up-site-analytics.md [self-hosting]: #built-in-privacy-plugin ## Configuration -### Cookie consent { #native-cookie-consent } +### Cookie consent { #cookie-consent } -[:octicons-tag-24: 8.4.0][cookie consent support] · +[:octicons-tag-24: 8.4.0][Cookie consent support] · :octicons-milestone-24: Default: _none_ · :octicons-beaker-24: Experimental @@ -41,19 +41,19 @@ extra: The following properties are available: -`title`{ #consent-title } +[`title`](#+consent.title){ #+consent.title } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property sets the title of the cookie consent, which is rendered at the top of the form and must be set to a non-empty string. -`description`{ #consent-description } +[`description`](#+consent.description){ #+consent.description } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property sets the description of the cookie consent, is rendered below the title, and may include raw HTML (e.g. a links to the terms of service). -`cookies`{ #consent-cookies } +[`cookies`](#+consent.cookies){ #+consent.cookies } : :octicons-milestone-24: Default: _none_ – This property allows to add custom cookies or change the initial `checked` state and name of the `analytics` @@ -99,7 +99,7 @@ The following properties are available: If Google Analytics was configured via `mkdocs.yml`, the cookie consent will automatically include a setting for the user to disable it. [Custom cookies] can be used from JavaScript. -`actions`{ #consent-actions } +[`actions`](#+consent.actions){ #+consent.actions } : :octicons-milestone-24: Default: `[accept, manage]` – This property defines which buttons are shown and in which order, e.g. to allow the user to accept @@ -121,11 +121,11 @@ The following properties are available: When a user first visits your site, a cookie consent form is rendered: -[![cookie consent enabled]][cookie consent enabled] +[![Cookie consent enabled]][Cookie consent enabled] [Custom cookies]: #custom-cookies - [cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0 - [cookie consent enabled]: ../assets/screenshots/consent.png + [Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0 + [Cookie consent enabled]: ../assets/screenshots/consent.png #### Change cookie settings @@ -168,7 +168,7 @@ plugins: The following configuration options are available: -`enabled`{ #enabled } +[`enabled`](#+privacy.enabled){ #+privacy.enabled } : :octicons-milestone-24: Default: `true` – This option specifies whether the plugin is enabled when building your project. If you want to switch @@ -180,7 +180,7 @@ The following configuration options are available: enabled: !ENV [PRIVACY, false] ``` -`externals`{ #externals } +[`externals`](#+privacy.externals){ #+privacy.externals } : :octicons-milestone-24: Default: `bundle` – This option specifies what the plugin should do when encountering external assets. There are two options: @@ -204,7 +204,7 @@ The following configuration options are available: [customization]: ../customization.md [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict -`externals_dir`{ #externals-dir } +[`externals_dir`](#+privacy.externals_dir){ #+privacy.externals_dir } : :octicons-milestone-24: Default: `assets/externals` – This option specifies where the downloaded [external assets] will be stored. It's @@ -216,7 +216,7 @@ The following configuration options are available: externals_dir: assets/externals ``` -`externals_exclude`{ #externals-exclude } +[`externals_exclude`](#+privacy.externals_exclude){ #+privacy.externals_exclude } : :octicons-milestone-24: Default: _none_ – This option allows to exclude certain external assets from processing by the privacy plugin, so they will @@ -440,7 +440,7 @@ If you've customized the [cookie consent] and added a `custom` cookie, the user will be prompted to accept your custom cookie. Use [additional JavaScript] to check whether the user accepted it: -=== ":octicons-file-code-16: docs/javascripts/consent.js" +=== ":octicons-file-code-16: `docs/javascripts/consent.js`" ``` js var consent = __md_get("__consent") @@ -449,7 +449,7 @@ check whether the user accepted it: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_javascript: diff --git a/docs/setup/extensions/python-markdown-extensions.md b/docs/setup/extensions/python-markdown-extensions.md index 5335ef90a..18644eb3c 100644 --- a/docs/setup/extensions/python-markdown-extensions.md +++ b/docs/setup/extensions/python-markdown-extensions.md @@ -37,7 +37,7 @@ Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and the JavaScript runtime need to be included, which can be done with a few lines of [additional JavaScript]: -=== ":octicons-file-code-16: docs/javascripts/mathjax.js" +=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`" ``` js window.MathJax = { @@ -58,7 +58,7 @@ of [additional JavaScript]: }) ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_javascript: @@ -154,7 +154,7 @@ markdown_extensions: The following configuration options are supported: -`mode`{ #critic-mode } +[`mode`](#+pymdownx.critic.mode){ #+pymdownx.critic.mode } : :octicons-milestone-24: Default: `view` – This option defines how the markup should be parsed, i.e. whether to just `view` all suggested changes, or @@ -237,7 +237,7 @@ markdown_extensions: The following configuration options are supported: -`emoji_index`{ #emoji-index } +[`emoji_index`](#+pymdownx.emoji.emoji_index){ #+pymdownx.emoji.emoji_index } : :octicons-milestone-24: Default: `emojione` – This option defines which set of emojis is used for rendering. Note that the use of `emojione` is not @@ -249,7 +249,7 @@ The following configuration options are supported: emoji_index: !!python/name:materialx.emoji.twemoji ``` -`emoji_generator`{ #emoji-generator } +[`emoji_generator`](#+pymdownx.emoji.emoji_generator){ #+pymdownx.emoji.emoji_generator } : :octicons-milestone-24: Default: `to_png` – This option defines how the resolved emoji or icon shortcode is render. Note that icons can only be @@ -261,7 +261,7 @@ The following configuration options are supported: emoji_generator: !!python/name:materialx.emoji.to_svg ``` -`options.custom_icons`{ #custom-icons } +[`options.custom_icons`](#+pymdownx.emoji.options.custom_icons){ #+pymdownx.emoji.options.custom_icons } : :octicons-milestone-24: Default: _none_ – This option allows to list folders with additional icon sets to be used in Markdown or `mkdocs.yml`, which is @@ -319,7 +319,7 @@ markdown_extensions: The following configuration options are supported: -`use_pygments`{ #highlight-use-pygments } +[`use_pygments`](#+pymdownx.highlight.use_pygments){ #+pymdownx.highlight.use_pygments } : :octicons-milestone-24: Default: `true` – This option allows to control whether highlighting should be carried out during build time using @@ -346,7 +346,7 @@ The following configuration options are supported: integrated with some [additional JavaScript] and an [additional style sheet] in `mkdocs.yml`: - === ":octicons-file-code-16: docs/javascripts/highlight.js" + === ":octicons-file-code-16: `docs/javascripts/highlight.js`" ``` js document$.subscribe(() => { @@ -354,7 +354,7 @@ The following configuration options are supported: }) ``` - === ":octicons-file-code-16: mkdocs.yml" + === ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_javascript: @@ -371,7 +371,7 @@ The following configuration options are supported: syntax highlighting using [Pygments], so they don't apply if `use_pygments` is set to `false`. -`auto_title`{ #highlight-auto-title } +[`auto_title`](#+pymdownx.highlight.auto_title){ #+pymdownx.highlight.auto_title } : :octicons-milestone-24: Default: `false` – This option will automatically add a [title] to all code blocks that shows the name of the language being @@ -383,7 +383,7 @@ The following configuration options are supported: auto_title: true ``` -`linenums`{ #highlight-linenums } +[`linenums`](#+pymdownx.highlight.linenums){ #+pymdownx.highlight.linenums } : :octicons-milestone-24: Default: `false` – This option will add line numbers to _all_ code blocks. If you wish to add line numbers to _some_, but not all @@ -397,7 +397,7 @@ The following configuration options are supported: linenums: true ``` -`linenums_style`{ #highlight-linenums-style } +[`linenums_style`](#+pymdownx.highlight.linenums_style){ #+pymdownx.highlight.linenums_style } : :octicons-milestone-24: Default: `table` – The [Highlight] extension provides three ways to add line numbers, two of which are supported by @@ -415,7 +415,7 @@ The following configuration options are supported: copying a code block to the clipboard. Thus, the usage of either `table` or `pymdownx-inline` is recommended. -`anchor_linenums`{ #highlight-anchor-linenums } +[`anchor_linenums`](#+pymdownx.highlight.anchor_linenums){ #+pymdownx.highlight.anchor_linenums } : [:octicons-tag-24: 8.1.0][anchor_linenums support] · :octicons-milestone-24: Default: `false` – If a code blocks contains line numbers, enabling this @@ -579,7 +579,7 @@ markdown_extensions: The following configuration options are supported: -`custom_fences`{ #superfences-custom-fences } +[`custom_fences`](#+pymdownx.superfences.custom_fences){ #+pymdownx.superfences.custom_fences } : :octicons-milestone-24: Default: _none_ – This option allows to define a handler for custom fences, e.g. to preserve the definitions of [Mermaid.js] @@ -643,11 +643,11 @@ markdown_extensions: The following configuration options are supported: -`alternate_style`{ #tabbed-alternate-style } +[`alternate_style`](#+pymdownx.tabbed.alternate_style){ #+pymdownx.tabbed:alternate_style } : [:octicons-tag-24: 7.3.1][Tabbed alternate support] · - :octicons-milestone-24: Default: `false` · :octicons-alert-24: Required – - This option enables the content tabs [alternate style], which has + :octicons-milestone-24: Default: `false` · :octicons-alert-24: __Required__ + – This option enables the content tabs [alternate style], which has [better behavior on mobile viewports], and is the only supported style: ``` yaml @@ -692,7 +692,7 @@ markdown_extensions: The following configuration options are supported: -`custom_checkbox`{ #tasklist-custom-checkbox } +[`custom_checkbox`](#+pymdownx.tasklist.custom_checkbox){ #+pymdownx.tasklist:custom_checkbox } : :octicons-milestone-24: Default: `false` · This option toggles the rendering style of checkboxes, replacing native checkbox styles with beautiful icons, @@ -704,7 +704,7 @@ The following configuration options are supported: custom_checkbox: true ``` -`clickable_checkbox`{ #tasklist-clickable-checkbox } +[`clickable_checkbox`](#+pymdownx.tasklist.clickable_checkbox){ #+pymdownx.tasklist:clickable_checkbox } : :octicons-milestone-24: Default: `false` · This option toggles whether checkboxes are clickable. As the state is not persisted, the use of this diff --git a/docs/setup/extensions/python-markdown.md b/docs/setup/extensions/python-markdown.md index bcd9c2ac7..d29bba97e 100644 --- a/docs/setup/extensions/python-markdown.md +++ b/docs/setup/extensions/python-markdown.md @@ -196,7 +196,7 @@ markdown_extensions: The following configuration options are supported: -`title`{ #toc-title } +[`title`](#+toc.title){ #+toc.title } : [:octicons-tag-24: 7.3.5][title support] · :octicons-milestone-24: Default: _automatically set_ – This option sets the @@ -210,7 +210,7 @@ The following configuration options are supported: title: On this page ``` -`permalink`{ #toc-permalink } +[`permalink`](#+toc.permalink){ #+toc.permalink } : :octicons-milestone-24: Default: `false` – This option adds an anchor link containing the paragraph symbol `¶` or another custom symbol at the end of @@ -233,7 +233,7 @@ The following configuration options are supported: permalink: ⚓︎ ``` -`permalink_title`{ #toc-permalink-title } +[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title } : :octicons-milestone-24: Default: `Permanent link` – This option sets the title of the anchor link which is shown on hover and read by screen readers. @@ -246,7 +246,7 @@ The following configuration options are supported: permalink_title: Anchor link to this section for reference ``` -`slugify`{ #toc-slugify } +[`slugify`](#+toc.slugify){ #+toc.slugify } : :octicons-milestone-24: Default: `headerid.slugify` – This option allows for customization of the slug function. For some languages, the default may not @@ -269,7 +269,7 @@ The following configuration options are supported: slugify: !!python/name:pymdownx.slugs.uslugify_cased ``` -`toc_depth`{ #toc-depth } +[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth } : :octicons-milestone-24: Default: `6` – Define the range of levels to be included in the table of contents. This may be useful for project diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md new file mode 100644 index 000000000..8001956a4 --- /dev/null +++ b/docs/setup/setting-up-a-blog.md @@ -0,0 +1,1209 @@ +--- +template: overrides/main.html +status: new +--- + +# Setting up a blog + +Material for MkDocs makes it very easy to build a blog, either as a sidecar to +your documentation or standalone. Focus on your content while the engine does +all the heavy lifting, automatically generating [archive] and [category] +indexes, [post slugs], configurable [pagination] and more. + +--- + +__Check out our [blog], which is created with the new [built-in blog plugin]!__ + + [archive]: #archive + [category]: #categories + [post slugs]: #+blog.post_url_format + [pagination]: #pagination + [blog]: ../blog/index.md + +## Configuration + +### Built-in blog plugin + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.23.0][Insiders] · +:octicons-cpu-24: Plugin · +:octicons-beaker-24: Experimental + +The built-in blog plugin adds support for building a blog from a folder of +posts, which are annotated with dates and other structured data. First, add the +following lines to `mkdocs.yml`: + +``` yaml +plugins: + - blog +``` + +> If you need to be able to build your documentation with and without +> [Insiders], please refer to the [built-in plugins] section to learn how +> shared configurations help to achieve this. + +By default, the built-in blog plugin assumes that your blog is hosted inside +the `blog` subfolder of your documentation ([this is configurable]). Next, +you need to create the following structure: + +``` sh +. +├─ docs/ +│ └─ blog/ +│ ├─ posts/ +│ └─ index.md +└─ mkdocs.yml +``` + +Since the built-in blog plugin auto-generates [archive] and [category] indexes, +it must know where to add those to the navigation. Thus, make sure to add a +`blog/index.md` file in `mkdocs.yml`: + +``` yaml +nav: + - Blog: + - blog/index.md # (1)! +``` + +1. Within this file, you can specify the title of your blog, which is then + picked up and used by the built-in blog plugin: + + ``` markdown + # Blog + ``` + +The following configuration options are available: + +[`enabled`](#+blog.enabled){ #+blog.enabled } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + the plugin is enabled when building your project. If you want to switch + the plugin off, you can disable it with the following lines: + + ``` yaml + plugins: + - blog: + enabled: false + ``` + +[`blog_dir`](#+blog.blog_dir){ #+blog.blog_dir } + +: :octicons-milestone-24: Default: `blog` – This option specifies the folder + where your posts and metadata live. The name of the folder will also be + included in the generated URLs as a prefix to all blog-related pages. If + you want to build a standalone blog, change it to `.`: + + === "Subdirectory" + + ``` yaml + plugins: + - blog: + blog_dir: path/to/folder + ``` + + === "Standalone" + + ``` yaml + plugins: + - blog: + blog_dir: . + ``` + + The path must be defined relative to [`docs_dir`][docs_dir]. + +__The built-in blog plugin has dozens of options that allow for advanced +configuration. It's a good idea to [start writing your first post], and come +back here later for fine-tuning the output.__ + +--- + + [Insiders]: ../insiders/index.md + [built-in plugins]: ../insiders/getting-started.md#built-in-plugins + [this is configurable]: #+blog.blog_dir + [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables + [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir + [start writing your first post]: #writing-your-first-post + +#### Posts + +The following configuration options are available for posts: + +[`post_date_format`](#+blog.post_date_format){ #+blog.post_date_format } + +: :octicons-milestone-24: Default: `long` – This option specifies the date + format that is used when posts are rendered. Under the hood, the + [built-in blog plugin] leverages [Babel] to render dates locale-aware using + the configured [site language]. The following formats are supported: + + === "Monday, January 31, 2022" + + ``` yaml + plugins: + - blog: + post_date_format: full + ``` + + === "January 31, 2022" + + ``` yaml + plugins: + - blog: + post_date_format: long + ``` + + === "Jan 31, 2022" + + ``` yaml + plugins: + - blog: + post_date_format: medium + ``` + + === "1/31/22" + + ``` yaml + plugins: + - blog: + post_date_format: short + ``` + + Note that depending on the [site language], formats might look different + for other languages. Additionally, [Babel] supports a [pattern syntax] + which allows for custom formats. + +[`post_url_date_format`](#+blog.post_url_date_format){ #+blog.post_url_date_format } + +: :octicons-milestone-24: Default: `YYYY/MM/dd` – This option specifies the + date format that is used in the URL of the post. The format string must + adhere to [Babel]'s [pattern syntax]. Some examples: + + === ":material-link: blog/2022/01/31/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + post_url_date_format: YYYY/MM/dd + ``` + + === ":material-link: blog/2022/01/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + post_url_date_format: YYYY/MM + ``` + + === ":material-link: blog/2022/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + post_url_date_format: YYYY + ``` + + If you want to exclude the date altogether, e.g. when your blog features + mostly evergreen content, you can remove the `date` placeholder from + the format string (see below). + +[`post_url_format`](#+blog.post_url_format){ #+blog.post_url_format } + +: :octicons-milestone-24: Default: `{date}/{slug}` – This option specifies the + format string that is used for the URL of the post. The following + placeholders are currently supported: + + - `date`: Replaced with the post's date, as configured in + [`post_url_date_format`][post_url_date_format]. + + - `slug`: Replaced with a slug generated from the post's title. + + === ":material-link: blog/2022/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + post_url_format: "{date}/{slug}" + ``` + + === ":material-link: blog/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + post_url_format: "{slug}" + ``` + + If you remove the `date` placeholder, make sure that post URLs don't + collide with other the URLs of other pages added to the blog section, as + this leads to undefined behavior. + +[`post_slugify`](#+blog.post_slugify){ #+blog.post_slugify } + +: :octicons-milestone-24: Default: `headerid.slugify` – This option specifies + which function to use for generating URL-compatible slugs from post titles. + [Python Markdown Extensions] comes with several Unicode-aware + slug functions which should be a good choice for non-ASCII languages: + + === "Unicode" + + ``` yaml + plugins: + - blog: + post_slugify: !!python/name:pymdownx.slugs.uslugify + ``` + + === "Unicode, case-sensitive" + + ``` yaml + plugins: + - blog: + post_slugify: !!python/name:pymdownx.slugs.uslugify_cased + ``` + +[`post_slugify_separator`](#+blog.post_slugify_separator){ #+blog.post_slugify_separator } + +: :octicons-milestone-24: Default: `-` – This option specifies the separator + which is used by the slug function. By default, a hyphen is used, but it can + be changed to any string, including the empty string: + + ``` yaml + plugins: + - blog: + post_slugify_separator: "-" + ``` + +[`post_excerpt`](#+blog.post_excerpt){ #+blog.post_excerpt } + +: :octicons-milestone-24: Default: `optional` – This option specifies whether + [post excerpts] should be considered being optional or required by the + [built-in blog plugin] when generating indexes. If excerpts are required, + the plugin terminates with an error if a post doesn't define an excerpt: + + === "Optional" + + ``` yaml + plugins: + - blog: + post_excerpt: optional + ``` + + === "Required" + + ``` yaml + plugins: + - blog: + post_excerpt: required + ``` + +[`post_excerpt_separator`](#+blog.post_excerpt_separator){ #+blog.post_excerpt_separator } + +: :octicons-milestone-24: Default: `` – This option specifies + the separator the [built-in blog plugin] will look for in a post' content + when generating [post excerpts]. All content after the separator is not + considered to be part of the excerpt. + +[`post_readtime`](#+blog.post_readtime){ #+blog.post_readtime } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + [built-in blog plugin] should compute the reading time of a post + automatically, which is then rendered in post excerpts, as well as in the + posts themselves. If you want to disable reading time computation, add: + + ``` yaml + plugins: + - blog: + post_readtime: false + ``` + +[`post_readtime_words_per_minute`](#+blog.post_readtime_words_per_minute){ #+blog.post_readtime_words_per_minute } + +: :octicons-milestone-24: Default: `265` – This option specifies the number + of words that a reader is expected to read per minute when computing the + reading time of a post. If you feel that estimation is not quite right, + you can fine-tune reading time computation with the following setting: + + ``` yaml + plugins: + - blog: + post_readtime_words_per_minute: 265 + ``` + + [built-in blog plugin]: #built-in-blog-plugin + [site language]: changing-the-language.md#site-language + [Babel]: https://pypi.org/project/Babel/ + [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax + [post_url_date_format]: #+blog.post_url_date_format + [post excerpts]: #adding-an-excerpt + [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ + +#### Archive + +The following configuration options are available for archive index generation: + +[`archive`](#+blog.archive){ #+blog.archive } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + [built-in blog plugin] should generate archive indexes. An archive indexes + shows all posts for a specific interval (e.g. year, month, etc.) in + reverse chronological order. If you want to disable archive index + generation, add: + + ``` yaml + plugins: + - blog: + archive: false + ``` + +[`archive_name`](#+blog.archive_name){ #+blog.archive_name } + +: :octicons-milestone-24: Default: _automatically set_ – This option specifies + the title of the archive section which the [built-in blog plugin] will + generate and add to the navigation. If this setting is omitted, it's + sourced from the translations, falling back to English. Change it with: + + ``` yaml + plugins: + - blog: + archive_name: Archive + ``` + +[`archive_date_format`](#+blog.archive_date_format){ #+blog.archive_date_format } + +: :octicons-milestone-24: Default: `YYYY` – This option specifies the date + format that is used when archive indexes are rendered. The format string + must adhere to [Babel]'s [pattern syntax]. Popular settings are: + + === "2022" + + ``` yaml + plugins: + - blog: + archive_date_format: YYYY + ``` + + === "January 2022" + + ``` yaml + plugins: + - blog: + archive_date_format: MMMM YYYY + ``` + +[`archive_url_date_format`](#+blog.archive_url_date_format){ #+blog.archive_url_date_format } + +: :octicons-milestone-24: Default: `YYYY` – This option specifies the date + format that is used in the archive index URL. The format string must adhere + to [Babel]'s [pattern syntax]. Some examples: + + === ":material-link: blog/archive/2022/" + + ``` yaml + plugins: + - blog: + archive_url_date_format: YYYY + ``` + + === ":material-link: blog/archive/2022/01/" + + ``` yaml + plugins: + - blog: + archive_url_date_format: YYYY/MM + ``` + +[`archive_url_format`](#+blog.archive_url_format){ #+blog.archive_url_format } + +: :octicons-milestone-24: Default: `archive/{date}` – This option specifies + the format string that is used for the URL of the archive index, and can + be used to localize the URL: + + === ":material-link: blog/archive/2022/" + + ``` yaml + plugins: + - blog: + archive_url_format: "archive/{date}" + ``` + + === ":material-link: blog/2022/" + + ``` yaml + plugins: + - blog: + archive_url_format: "{date}" + ``` + +#### Categories + +The following configurations options are available for category index generation: + +[`categories`](#+blog.categories){ #+blog.categories } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + [built-in blog plugin] should generate category indexes. A category indexes + shows all posts for a specific category in reverse chronological order. If + you want to disable category index generation, add: + + ``` yaml + plugins: + - blog: + categories: false + ``` + +[`categories_name`](#+blog.categories_name){ #+blog.categories_name } + +: :octicons-milestone-24: Default: _automatically set_ – This option specifies + the title of the category section which the [built-in blog plugin] will + generate and add to the navigation. If this setting is omitted, it's + sourced from the translations, falling back to English. Change it with: + + ``` yaml + plugins: + - blog: + categories_name: Categories + ``` + +[`categories_url_format`](#+blog.categories_url_format){ #+blog.categories_url_format } + +: :octicons-milestone-24: Default: `category/{slug}` – This option specifies + the format string that is used for the URL of the category index, and can + be used to localize the URL: + + === ":material-link: blog/category/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + categories_url_format: "category/{slug}" + ``` + + === ":material-link: blog/:material-dots-horizontal:/" + + ``` yaml + plugins: + - blog: + categories_url_format: "{slug}" + ``` + +[`categories_slugify`](#+blog.categories_slugify){ #+blog.categories_slugify } + +: :octicons-milestone-24: Default: `headerid.slugify` – This option specifies + which function to use for generating URL-compatible slugs from categories. + [Python Markdown Extensions] comes with several Unicode-aware + slug functions which should be a good choice for non-ASCII languages: + + === "Unicode" + + ``` yaml + plugins: + - blog: + categories_slugify: !!python/name:pymdownx.slugs.uslugify + ``` + + === "Unicode, case-sensitive" + + ``` yaml + plugins: + - blog: + categories_slugify: !!python/name:pymdownx.slugs.uslugify_cased + ``` + +[`categories_slugify_separator`](#+blog.categories_slugify_separator){ #+blog.categories_slugify_separator } + +: :octicons-milestone-24: Default: `-` – This option specifies the separator + which is used by the slug function. By default, a hyphen is used, but it can + be changed to any string, including the empty string: + + ``` yaml + plugins: + - blog: + categories_slugify_separator: "-" + ``` + +[`categories_allowed`](#+blog.categories_allowed){ #+blog.categories_allowed } + +: :octicons-milestone-24: Default: _none_ – This option specifies the + categories that are allowed to be used in posts. If this setting is omitted, + the [built-in blog plugin] will not check category names. Use this option to + define a list of categories in order to catch typos: + + ``` yaml + plugins: + - blog: + categories_allowed: + - General + - Search + - Performance + ``` + +#### Pagination + +The following configurations options are available for index pagination: + +[`pagination`](#+blog.pagination){ #+blog.pagination } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + [built-in blog plugin] should paginate the index. The index shows all posts + in reverse chronological order, which can be many. If you want to disable + index pagination, add: + + ``` yaml + plugins: + - blog: + pagination: false + ``` + +[`pagination_per_page`](#+blog.pagination_per_page){ #+blog.pagination_per_page } + +: :octicons-milestone-24: Default: `10` – This option specifies the number + of posts rendered on a single index page. If more posts are found, they are + assigned to a 2nd page, and so on. If you have large [post excerpts], it + might be a good idea to reduce the number of posts per page: + + ``` yaml + plugins: + - blog: + pagination_per_page: 5 + ``` + +[`pagination_url_format`](#+blog.pagination_url_format){ #+blog.pagination_url_format } + +: :octicons-milestone-24: Default: `page/{page}` – This option specifies + the format string that is used for the URL of the paginated index, and can + be used to localize the URL: + + === ":material-link: blog/page/n/" + + ``` yaml + plugins: + - blog: + pagination_url_format: "page/{page}" + ``` + + === ":material-link: blog/n/" + + ``` yaml + plugins: + - blog: + pagination_url_format: "{page}" + ``` + +[`pagination_template`](#+blog.pagination_template){ #+blog.pagination_template } + +: :octicons-milestone-24: Default: `~2~` – This option specifies the format + string that is provided to the [paginate] module, which allows to customize + how pagination is constructed. Popular choices: + + === "1 2 3 .. n" + + ``` yaml + plugins: + - blog: + pagination_template: "~2~" + ``` + + === "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:" + + ``` yaml + plugins: + - blog: + pagination_template: "$link_first $link_previous ~2~ $link_next $link_last" + ``` + + === "1 :material-chevron-right:" + + ``` yaml + plugins: + - blog: + pagination_template: "$link_previous $page $link_next" + ``` + + The [paginate] module exposes the following placeholders: + + - `$first_page` – number of first reachable page + - `$last_page` – number of last reachable page + - `$page` – number of currently selected page + - `$page_count` – number of reachable pages + - `$items_per_page` – maximal number of items per page + - `$first_item` – index of first item on the current page + - `$last_item` – index of last item on the current page + - `$item_count` – total number of items + - `$link_first` – link to first page (unless this is first page) + - `$link_last` – link to last page (unless this is last page) + - `$link_previous` – link to previous page (unless this is first page) + - `$link_next` – link to next page (unless this is last page) + + [paginate]: https://pypi.org/project/paginate/ + +#### Authors + +The following configuration options are available for author info: + +[`authors`](#+blog.authors){ #+blog.authors } + +: :octicons-milestone-24: Default: `true` – This option specifies whether the + [built-in blog plugin] should generate author info. If it is enabled, the + plugin will look up authors in a file called `.authors.yml` and include + authors in indexes and in posts. If you want to disable this behavior, add: + + ``` yaml + plugins: + - blog: + authors: false + ``` + +[`authors_file`](#+blog.authors_file){ #+blog.authors_file } + +: :octicons-milestone-24: Default: `.authors.yml` – This option specifies the + name of the file where the authors for your posts resides. The default + settings assumes that the file is called `.authors.yml` (mind the `.` at + the beginning): + + ``` yaml + plugins: + - blog: + authors_file: .authors.yml + ``` + + The path must be defined relative to [`docs_dir`][docs_dir]. Also see the + section on [adding authors]. + +[`authors_in_excerpt`](#+blog.authors_in_excerpt){ #+blog.authors_in_excerpt } + +: :octicons-milestone-24: Default: `1` – This option specifies the number of + authors rendered in post excerpts. While each post may be written by + multiple authors, this setting allows to limit the display to just a few or + even a single author, or disable authors in excerpts altogether: + + === "Render up to 2 authors in excerpts" + + ``` yaml + plugins: + - blog: + authors_in_excerpt: 2 + ``` + + === "Disable authors in excerpts" + + ``` yaml + plugins: + - blog: + authors_in_excerpt: 0 + ``` + + [adding authors]: #adding-authors + +#### Drafts + +The following configuration options are available for drafts: + +[`draft`](#+blog.draft){ #+blog.draft } + +: :octicons-milestone-24: Default: `false` – This option specifies whether the + [built-in blog plugin] should also include posts marked as drafts when the + site is being built. Including draft posts might be desired in deploy + previews, which is why it exists in the first place: + + === "Render drafts" + + ``` yaml + plugins: + - blog: + draft: true + ``` + + === "Don't render drafts" + + ``` yaml + plugins: + - blog: + draft: false + ``` + +[`draft_on_serve`](#+blog.draft_on_serve){ #+blog.draft_on_serve } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + posts marked as drafts should be included [when previewing your site] with + `mkdocs serve`. By default, drafts are rendered when previewing, but skipped + when the site is being built: + + ``` yaml + plugins: + - blog: + draft_on_serve: true + ``` + +[`draft_if_future_date`](#+blog.draft_if_future_date){ #+blog.draft_if_future_date } + +: :octicons-milestone-24: Default: `false` – This option specifies whether the + [built-in blog plugin] should mark posts with a future date as drafts. When + the date passed today, the post is automatically unmarked and included when + the site is being built: + + ``` yaml + plugins: + - blog: + draft_if_future_date: true + ``` + + [when previewing your site]: ../creating-your-site.md#previewing-as-you-write + +### RSS + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders+4.23.1][Insiders] · +[:octicons-cpu-24: Plugin][rss] + +The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss], +which provides a simple way to add an RSS feed to your blog (or to your whole +documentation). Install it with `pip`: + +``` +pip install mkdocs-rss-plugin +``` + +Then, add the following lines to `mkdocs.yml`: + +``` yaml +plugins: + - rss: + match_path: blog/posts/.* # (1)! + date_from_meta: + as_creation: date + categories: + - categories + - tags # (2)! +``` + +1. The RSS plugin allows to filter for URLs to be included in the feed. In + this example, only blog posts will be part of the feed. + +2. If you want to include a post's categories as well as its tags in the feed, + add both `categories` and `tags` here. + +The following configuration options are supported: + +[`enabled`](#+rss.enabled){ #+rss.enabled } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + the plugin is enabled when building your project. If you want to switch + the plugin off, you can disable it with the following lines: + + ``` yaml + plugins: + - rss: + enabled: false + ``` + +[`match_path`](#+rss.match_path){ #+rss.match_path } + +: :octicons-milestone-24: Default: `.*` – This option specifies which + pages should be included in the feed. For example, to only include blog + posts in the feed, use the following regular expression: + + ``` yaml + plugins: + - rss: + match_path: blog/posts/.* + ``` + +[`date_from_meta`](#+rss.date_from_meta){ #+rss.date_from_meta } + +: :octicons-milestone-24: Default: _none_ – This option specifies which + front matter property should be used as a creation date of a page in the + feed. It's recommended to use the `date` property: + + ``` yaml + plugins: + - rss: + date_from_meta: + as_creation: date + ``` + +[`categories`](#+rss.categories){ #+rss.categories } + +: :octicons-milestone-24: Default: _none_ – This option specifies which + front matter properties are used as categories as part of the feed. If you + use [categories] and [tags], add both with the following lines: + + ``` yaml + plugins: + - rss: + categories: + - categories + - tags + ``` + +[`comments_path`](#+rss.comments_path){ #+rss.comments_path } + +: :octicons-milestone-24: Default: _none_ – This option specifies the anchor + at which comments for a post or page can be found. If you've integrated a + [comment system], add the following lines: + + ``` yaml + plugins: + - rss: + comments_path: "#__comments" + ``` + +Material for MkDocs will automatically add the [necessary metadata] to your site +which will make the RSS feed discoverable by browsers and feed readers. Note +that the [RSS plugin][rss] comes with several other configuration options. +For further information, see the [documentation]. + + [rss]: https://guts.github.io/mkdocs-rss-plugin/ + [categories]: #categories + [tags]: setting-up-tags.md#built-in-tags-plugin + [comment system]: adding-a-comment-system.md + [necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration + [theme extension]: ../customization.md + [documentation]: https://guts.github.io/mkdocs-rss-plugin/configuration/ + +## Usage + +### Writing your first post + +After you've successfully set up the [built-in blog plugin], it's time to write +your first post. The plugin doesn't assume any specific directory structure, so +you're completely free in how you organize your posts, as long as they are all +located inside the `posts` directory: + +``` sh +. +├─ docs/ +│ └─ blog/ +│ ├─ posts/ +│ │ └─ hello-world.md # (1)! +│ └─ index.md +└─ mkdocs.yml +``` + +1. If you'd like to arrange posts differently, you're free to do so. The URLs + are built from the format specified in [`post_url_format`][post slugs] and + the titles and dates of posts, no matter how they are organized + inside the `posts` directory. + +Create a new file called `hello-world.md` and add the following lines: + +``` yaml +--- +draft: true # (1)! +date: 2022-01-31 +categories: + - Hello + - World +--- + +# Hello world! +... +``` + +1. If you mark a post as a [draft], a red marker appears next to the post date + on index pages. When the site is built, drafts are not included in the + output. [This behavior can be changed], e.g. for rendering drafts when + building deploy previews. + +When you spin up the [live preview server], you should be greeted by your first +post! You'll also realize, that [archive] and [category] indexes have been +automatically generated for you. + + [draft]: #drafts + [This behavior can be changed]: #+blog.draft + [live preview server]: ../creating-your-site.md#previewing-as-you-write + +#### Adding an excerpt + +The blog index, as well as [archive] and [category] indexes can either list the +entire content of each post, or excerpts of posts. An excerpt can be created by +adding a `` separator after the first few paragraphs of a post: + +``` py +# Hello world! + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod +nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor +massa, nec semper lorem quam in massa. + + +... +``` + +When the [built-in blog plugin] generates all indexes, the content before the +[excerpt separator] is automatically extracted, allowing the user to start +reading a post before deciding to jump in. + + [excerpt separator]: #+blog.post_excerpt_separator + +#### Adding authors + +In order to add a little more personality to your posts, you can associate each +post with one or multiple [authors]. First, create the +[`.authors.yml`][authors_file] file in your blog directory, and add an author: + +``` yaml +squidfunk: + name: Martin Donath + description: Creator + avatar: https://github.com/squidfunk.png +``` + +The [`.authors.yml`][authors_file] file associates each author with an +identifier (in this example `squidfunk`), which can then be used in posts. +The following properties are available for each author: + +[`name`](#+blog.authors_file.name){ #+blog.authors_file.name } + +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – + This property must define a name for the author. The name is displayed in + the left sidebar of each post as part of the author info. + +[`description`](#+blog.authors_file.description){ #+blog.authors_file.description } + +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – + This property can be used to add a short description for the author, e.g. + the role or profession of the author, or any other title. + +[`avatar`](#+blog.authors_file.avatar){ #+blog.authors_file.avatar } + +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – + This property must point to a valid image URL, internal or external, and is + used as part of posts and excerpts as the author's avatar. + +Now, you can assign one or more authors to a post by referencing their +identifiers in the front matter of the Markdown file under the `authors` +property. For each author, a small profile is rendered in the left sidebar of +each post, as well as in post excerpts on index pages: + +``` yaml +--- +date: 2022-01-31 +authors: + - squidfunk + ... +--- + +# Hello world! +... +``` + + [authors]: #authors + [authors_file]: #+blog.authors_file + +#### Adding categories + +Categories are an excellent way for grouping your posts thematically on +dedicated index pages. This way, a user interested in a specific topic can +explore all of your posts on this topic. Make sure [categories] are enabled and +add them to the `categories` front matter property: + +``` yaml +--- +date: 2022-01-31 +categories: + - Hello + - World +--- + +# Hello world! +... +``` + +If you want to save yourself from typos when typing out categories, you can +define your desired categories in `mkdocs.yml` as part of the +[`categories_allowed`][categories_allowed] configuration option. The +[built-in blog plugin] will stop the build if a category is not found within +the list. + + [categories_allowed]: #+blog.categories_allowed + +#### Adding tags + +Besides [categories], the [built-in blog plugin] also integrates with the +[built-in tags plugin]. If you add tags in the `tags` front matter property as +part of a post, the post is linked from the [tags index]: + +``` yaml +--- +date: 2022-01-31 +tags: + - Foo + - Bar +--- + +# Hello world! +... +``` + +As usual, the tags are rendered above the main headline and posts are linked +on the tags index page, if configured. Note that posts are, as pages, only +linked with their titles. + + [built-in tags plugin]: setting-up-tags.md#built-in-tags-plugin + [tags index]: setting-up-tags.md#adding-a-tags-index + +#### Adding related links + +Related links offer the perfect way to prominently add a _further reading_ +section to your post that is included in the left sidebar, guiding the user to +other destinations of your documentation. Use the `links` front matter property +to add related links to a post: + +``` yaml +--- +date: 2022-01-31 +links: + - setup/setting-up-site-search.md#built-in-search-plugin + - insiders/index.md#how-to-become-a-sponsor +--- + +# Hello world! +... +``` + +You can use the exact same syntax as for the [`nav`][nav] section in +`mkdocs.yml`, which means you can set explicit titles for links, add external +links and even use nesting: + +``` yaml +--- +date: 2022-01-31 +links: + - setup/setting-up-site-search.md#built-in-search-plugin + - insiders/index.md#how-to-become-a-sponsor + - Nested section: + - External link: https://example.com + - setup/setting-up-site-search.md +--- + +# Hello world! +... +``` + +If you look closely, you'll realize that you can even use an anchor to link to +a specific section of a document, extending the possiblities of the [`nav`][nav] +syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets +the title of the anchor as a subtitle of the related link. + +Note that all links must be relative to [`docs_dir`][docs_dir], as is also the case for the [`nav`][nav] setting. + + [nav]: https://www.mkdocs.org/user-guide/configuration/#nav + +#### Linking from and to posts + +While [post URLs][post slugs] are dynamically computed, the [built-in blog +plugin] ensures that all links from and to posts and a post's assets are +correct. If you want to link to a post, just use the path to the Markdown file +as a link reference (links must be relative): + +``` markdown +[Hello World!](blog/posts/hello-world.md) +``` + +Linking from a post to a page, e.g. the index, follows the same method: + +``` markdown +[Blog](../index.md) +``` + +All assets inside the `posts` directory are copied to the `blog/assets` folder +when the site is being built. Of course, you can also reference assets from +posts outside of the `posts` directory. The [built-in blog plugin] ensures that +all links are correct. + +#### Setting the reading time + +When [enabled], the [readtime] package is used to compute the expected reading +time of each post, which is the rendered as part of the post and post excerpt. +Nowadays, many blogs show reading times, which is why the [built-in blog plugin] +offers this capability as well. + +Sometimes, however, the computed reading time might not feel accurate, or +result in odd and unpleasant numbers. For this reason, reading time can be +overriden and explicitly set with the `readtime` front matter property for a +post: + +``` yaml +--- +date: 2022-01-31 +readtime: 15 +--- + +# Hello world! +... +``` + +This will disable automatic reading time computation. + + [readtime]: https://pypi.org/project/readtime/ + [enabled]: #+blog.post_readtime + +#### Setting defaults + +If you have a lot of posts, it might feel redundant to define all of the above +for each post. Luckily, the [built-in meta plugin] allows to set default front +matter properties per folder. You can group your posts by categories, or +authors, and add a `.meta.yml` file to set common properties: + +``` sh +. +├─ docs/ +│ └─ blog/ +│ ├─ posts/ +│ ├─ .meta.yml # (1)! +│ └─ index.md +└─ mkdocs.yml +``` + +1. As already noted, you can also place a `.meta.yml` file in nested folders + of the `posts` directory. This file then can contain any front matter that + is also valid in posts, e.g.: + + ``` yaml + authors: + - squidfunk + categories: + - Hello + - World + ``` + +Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the +values defined for a post, which means you can define common properties in +`.meta.yml` and then add specific properties or overrides for each post. + + [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin + +### Adding pages + +Besides posts, it's also possible to add static pages to your blog by listing +the pages in the [`nav`][nav] section of `mkdocs.yml`. All generated indexes +are included after the last specified page. For example, to add a page on the +authors of the blog, add the following to `mkdocs.yml`: + +``` yaml +nav: + - Blog: + - blog/index.md + - blog/authors.md + ... +``` + +## Customization + +### Overriding templates + +The [built-in blog plugin] is built on the same basis as Material for MkDocs, +which means you can override all templates used for the blog by using +[theme extension] as usual. + +The following templates are added by the [built-in blog plugin]: + +- [`blog.html`][blog.html] – Template for blog index +- [`blog-post.html`][blog-post.html] – Template for blog post +- [`blog-archive.html`][blog-archive.html] – Template for blog archive index +- [`blog-category.html`][blog-category.html] – Template for blog category index + + [theme extension]: ../customization.md#extending-the-theme + + [blog.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog.html + [blog-post.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-post.html + [blog-archive.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-archive.html + [blog-category.html]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/blog-category.html diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index d7e896c89..3f59faae8 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -6,19 +6,18 @@ template: overrides/main.html A clear and concise navigation structure is an important aspect of good project documentation. Material for MkDocs provides a multitude of options to configure -the behavior of navigational elements, including [tabs][navigation.tabs] and -[sections][navigation.sections], and its flag-ship feature: [instant loading] -[navigation.instant]. +the behavior of navigational elements, including [tabs] and [sections], and one +of its flag-ship feature: [instant loading]. - [navigation.tabs]: #navigation-tabs - [navigation.sections]: #navigation-sections - [navigation.instant]: #instant-loading + [tabs]: #navigation-tabs + [sections]: #navigation-sections + [instant loading]: #instant-loading ## Configuration ### Instant loading -[:octicons-tag-24: 5.0.0][navigation.instant support] · +[:octicons-tag-24: 5.0.0][Instant loading support] · :octicons-unlock-24: Feature flag When instant loading is enabled, clicks on all internal links will be @@ -36,7 +35,7 @@ are rebound automatically, i.e., __Material for MkDocs now behaves like a Single Page Application__. Now, the search index survives navigation, which is especially useful for large documentation sites. - [navigation.instant support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 + [Instant loading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0 [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest ### Anchor tracking @@ -59,7 +58,7 @@ theme: ### Navigation tabs -[:octicons-tag-24: 1.1.0][navigation.tabs support] · +[:octicons-tag-24: 1.1.0][Navigation tabs support] · :octicons-unlock-24: Feature flag When tabs are enabled, top-level sections are rendered in a menu layer below @@ -81,21 +80,21 @@ theme: - navigation.tabs ``` -=== ":octicons-check-circle-fill-16: Enabled" +=== "With tabs" - [![navigation.tabs enabled]][navigation.tabs enabled] + [![Navigation tabs enabled]][Navigation tabs enabled] -=== ":octicons-skip-16: Disabled" +=== "Without" - [![navigation.tabs disabled]][navigation.tabs disabled] + [![Navigation tabs disabled]][Navigation tabs disabled] - [navigation.tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0 - [navigation.tabs enabled]: ../assets/screenshots/navigation-tabs.png - [navigation.tabs disabled]: ../assets/screenshots/navigation.png + [Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0 + [Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png + [Navigation tabs disabled]: ../assets/screenshots/navigation.png #### Sticky navigation tabs -[:octicons-tag-24: 7.3.0][navigation.tabs.sticky support] · +[:octicons-tag-24: 7.3.0][Sticky navigation tabs support] · :octicons-unlock-24: Feature flag When sticky tabs are enabled, navigation tabs will lock below the header and @@ -109,21 +108,21 @@ theme: - navigation.tabs.sticky ``` -=== ":octicons-check-circle-fill-16: Enabled" +=== "With sticky tabs" - [![navigation.tabs.sticky enabled]][navigation.tabs.sticky enabled] + [![Sticky navigation tabs enabled]][Sticky navigation tabs enabled] -=== ":octicons-skip-16: Disabled" +=== "Without" - [![navigation.tabs.sticky disabled]][navigation.tabs.sticky disabled] + [![Sticky navigation tabs disabled]][Sticky navigation tabs disabled] - [navigation.tabs.sticky support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 - [navigation.tabs.sticky enabled]: ../assets/screenshots/navigation-tabs-sticky.png - [navigation.tabs.sticky disabled]: ../assets/screenshots/navigation-tabs-collapsed.png + [Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 + [Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png + [Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png ### Navigation sections -[:octicons-tag-24: 6.2.0][navigation.sections support] · +[:octicons-tag-24: 6.2.0][Navigation sections support] · :octicons-unlock-24: Feature flag When sections are enabled, top-level sections are rendered as groups in the @@ -136,26 +135,25 @@ theme: - navigation.sections ``` -=== ":octicons-check-circle-fill-16: Enabled" +=== "With sections" - [![navigation.sections enabled]][navigation.sections enabled] + [![Navigation sections enabled]][Navigation sections enabled] -=== ":octicons-skip-16: Disabled" +=== "Without" - [![navigation.sections disabled]][navigation.sections disabled] + [![Navigation sections disabled]][Navigation sections disabled] - [navigation.sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 - [navigation.sections enabled]: ../assets/screenshots/navigation-sections.png - [navigation.sections disabled]: ../assets/screenshots/navigation.png + [Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 + [Navigation sections enabled]: ../assets/screenshots/navigation-sections.png + [Navigation sections disabled]: ../assets/screenshots/navigation.png -Both feature flags, [`navigation.tabs`][navigation.tabs] and -[`navigation.sections`][navigation.sections], can be combined with each other. -If both feature flags are enabled, sections are rendered for level 2 navigation -items. +Both feature flags, [`navigation.tabs`][tabs] and +[`navigation.sections`][sections], can be combined with each other. If both +feature flags are enabled, sections are rendered for level 2 navigation items. ### Navigation expansion -[:octicons-tag-24: 6.2.0][navigation.expand support] · +[:octicons-tag-24: 6.2.0][Navigation expansion support] · :octicons-unlock-24: Feature flag When expansion is enabled, the left sidebar will expand all collapsible @@ -168,17 +166,17 @@ theme: - navigation.expand ``` -=== ":octicons-check-circle-fill-16: Enabled" +=== "With expansion" - [![navigation.expand enabled]][navigation.expand enabled] + [![Navigation expansion enabled]][Navigation expansion enabled] -=== ":octicons-skip-16: Disabled" +=== "Without" - [![navigation.expand disabled]][navigation.expand disabled] + [![Navigation expansion disabled]][Navigation expansion disabled] - [navigation.expand support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 - [navigation.expand enabled]: ../assets/screenshots/navigation-expand.png - [navigation.expand disabled]: ../assets/screenshots/navigation.png + [Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0 + [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png + [Navigation expansion disabled]: ../assets/screenshots/navigation.png ### Navigation pruning @@ -209,7 +207,7 @@ page in that section (or the section index page). ### Section index pages -[:octicons-tag-24: 7.3.0][navigation.indexes support] · +[:octicons-tag-24: 7.3.0][Section index pages support] · :octicons-unlock-24: Feature flag When section index pages are enabled, documents can be directly attached to @@ -225,13 +223,13 @@ theme: 1. This feature flag is not compatible with [`toc.integrate`][toc.integrate], as sections cannot host the table of contents due to missing space. -=== ":octicons-check-circle-fill-16: Enabled" +=== "With section index pages" - [![navigation.indexes enabled]][navigation.indexes enabled] + [![Section index pages enabled]][Section index pages enabled] -=== ":octicons-skip-16: Disabled" +=== "Without" - [![navigation.indexes disabled]][navigation.indexes disabled] + [![Section index pages disabled]][Section index pages disabled] In order to link a page to a section, create a new document with the name `index.md` in the respective folder, and add it to the beginning of your @@ -246,9 +244,9 @@ nav: - Page n: section/page-n.md ``` - [navigation.indexes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 - [navigation.indexes enabled]: ../assets/screenshots/navigation-index-on.png - [navigation.indexes disabled]: ../assets/screenshots/navigation-index-off.png + [Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 + [Section index pages enabled]: ../assets/screenshots/navigation-index-on.png + [Section index pages disabled]: ../assets/screenshots/navigation-index-off.png [toc.integrate]: #navigation-integration ### Table of contents @@ -273,7 +271,7 @@ theme: #### Navigation integration -[:octicons-tag-24: 6.2.0][toc.integrate support] · +[:octicons-tag-24: 6.2.0][Navigation integration support] · :octicons-unlock-24: Feature flag When navigation integration for the [table of contents] is enabled, it is always @@ -290,23 +288,23 @@ theme: [`navigation.indexes`][navigation.indexes], as sections cannot host the table of contents due to missing space. -=== ":octicons-check-circle-fill-16: Enabled" +=== "With navigation integration" - [![toc.integrate enabled]][toc.integrate enabled] + [![Navigation integration enabled]][Navigation integration enabled] -=== ":octicons-skip-16: Disabled" +=== "Without" - [![toc.integrate disabled]][toc.integrate disabled] + [![Navigation integration disabled]][Navigation integration disabled] [table of contents]: extensions/python-markdown.md#table-of-contents - [toc.integrate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 - [toc.integrate enabled]: ../assets/screenshots/toc-integrate.png - [toc.integrate disabled]: ../assets/screenshots/navigation-tabs.png + [Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0 + [Navigation integration enabled]: ../assets/screenshots/toc-integrate.png + [Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png [navigation.indexes]: #section-index-pages ### Back-to-top button -[:octicons-tag-24: 7.1.0][navigation.top support] · +[:octicons-tag-24: 7.1.0][Back-to-top button support] · :octicons-unlock-24: Feature flag A back-to-top button can be shown when the user, after scrolling down, starts @@ -319,7 +317,7 @@ theme: - navigation.top ``` - [navigation.top support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 + [Back-to-top button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0 ## Usage @@ -329,7 +327,7 @@ The navigation and/or table of contents sidebars can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file: -``` sh +``` yaml --- hide: - navigation @@ -342,19 +340,19 @@ hide: === "Hide navigation" - [![hide.navigation enabled]][hide.navigation enabled] + [![Hide navigation enabled]][Hide navigation enabled] === "Hide table of contents" - [![hide.toc enabled]][hide.toc enabled] + [![Hide table of contents enabled]][Hide table of contents enabled] === "Hide both" - [![hide.* enabled]][hide.* enabled] + [![Hide both enabled]][Hide both enabled] - [hide.navigation enabled]: ../assets/screenshots/hide-navigation.png - [hide.toc enabled]: ../assets/screenshots/hide-toc.png - [hide.* enabled]: ../assets/screenshots/hide-navigation-toc.png + [Navigation hiding enabled]: ../assets/screenshots/hide-navigation.png + [Hide table of contents enabled]: ../assets/screenshots/hide-toc.png + [Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png ## Customization @@ -363,7 +361,7 @@ hide: Material for MkDocs includes several keyboard shortcuts that make it possible to navigate your project documentation via keyboard. There are two modes: -`search`{ #mode-search } +[`search`](#mode:search){ #mode:search } : This mode is active when the _search is focused_. It provides several key bindings to make search accessible and navigable via keyboard: @@ -372,7 +370,7 @@ to navigate your project documentation via keyboard. There are two modes: * ++esc++ , ++tab++ : close search dialog * ++enter++ : follow selected result -`global`{ #mode-global } +[`global`](#mode:global){ #mode:global } : This mode is active when _search is not focussed_ and when there's no other focussed element that is susceptible to keyboard input. The following keys @@ -386,7 +384,7 @@ Let's say you want to bind some action to the ++x++ key. By using [additional JavaScript], you can subscribe to the `keyboard$` observable and attach your custom event listener: -=== ":octicons-file-code-16: docs/javascripts/shortcuts.js" +=== ":octicons-file-code-16: `docs/javascripts/shortcuts.js`" ``` js keyboard$.subscribe(function(key) { @@ -401,7 +399,7 @@ your custom event listener: underlying event, so the keypress will not propagate further and touch other event listeners. -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_javascript: @@ -421,7 +419,7 @@ stretch to the entire available space. This can easily be achieved with an [additional style sheet] and a few lines of CSS: -=== ":octicons-file-code-16: docs/stylesheets/extra.css" +=== ":octicons-file-code-16: `docs/stylesheets/extra.css`" ``` css .md-grid { @@ -438,7 +436,7 @@ of CSS: } ``` -=== ":octicons-file-code-16: mkdocs.yml" +=== ":octicons-file-code-16: `mkdocs.yml`" ``` yaml extra_css: diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 5f0511796..6bfb4edd9 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -10,7 +10,7 @@ MkDocs natively integrates with [Google Analytics] and offers a customizable [cookie consent] and a [feedback widget]. [Google Analytics]: https://developers.google.com/analytics - [cookie consent]: ensuring-data-privacy.md#native-cookie-consent + [cookie consent]: ensuring-data-privacy.md#cookie-consent [feedback widget]: #was-this-page-helpful ## Configuration @@ -70,7 +70,7 @@ following lines to `mkdocs.yml`: ### Was this page helpful? -[:octicons-tag-24: 8.4.0][feedback support] · +[:octicons-tag-24: 8.4.0][Was this page helpful? support] · :octicons-milestone-24: Default: _none_ · :octicons-beaker-24: Experimental @@ -169,9 +169,9 @@ integrated with the [cookie consent] feature[^1]. The following properties are available for each rating: -`icon`{ #feedback-rating-icon } +[`icon`](#+analytics.feedback.ratings.icon){ #+analytics.feedback.ratings.icon } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – This property must point to a valid icon path referencing [any icon bundled with the theme][custom icons], or the build will not succeed. Some popular combinations: @@ -180,24 +180,24 @@ The following properties are available for each rating: * :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline` * :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken` -`name`{ #feedback-rating-name } +[`name`](#+analytics.feedback.ratings.name){ #+analytics.feedback.ratings.name } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – The value of this property is shown on user interaction (i.e. keyboard focus or mouse hover), explaining the meaning of the rating behind the icon. -`data`{ #feedback-rating-data } +[`data`](#+analytics.feedback.ratings.data){ #+analytics.feedback.ratings.data } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – The value of this property is sent as a data value with the custom event that is transmitted to Google Analytics[^2] (or any custom integration). [^2]: Note that for Google Analytics, the data value must be an integer. -`note`{ #feedback-rating-note } +[`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note } -: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – +: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – The value of this property is shown after the user selected the rating. It may contain arbitrary HTML tags, which is especially useful to ask the user to provide more detailed feedback for the current page through a form. @@ -221,7 +221,7 @@ The following properties are available for each rating: An alternative to GitHub issues is [Google Forms]. - [feedback support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0 + [Was this page helpful? support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0 [feedback widget]: #feedback [analytics]: #google-analytics [feedback report]: ../assets/screenshots/feedback-report.png @@ -235,7 +235,7 @@ The following properties are available for each rating: The [feedback widget] can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file: -``` sh +``` yaml --- hide: - feedback @@ -254,7 +254,7 @@ JavaScript-based tracking solution, just follow the guide on [theme extension] and create a new partial in the `overrides` folder. The name of the partial is used to configure the custom integration via `mkdocs.yml`: -=== ":octicons-file-code-16: overrides/partials/integrations/analytics/custom.html" +=== ":octicons-file-code-16: `overrides/partials/integrations/analytics/custom.html`" ``` html