@@ -237,7 +265,9 @@ For detailed installation instructions, configuration options, and a demo, visit
[CloudFlare](https://cloudflare.github.io/itty-router-openapi/),
[Datadog](https://datadoghq.dev/integrations-core/),
[Google](https://google.github.io/accompanist/),
+[Harvard](https://informatics.fas.harvard.edu/),
[Hewlett Packard](https://hewlettpackard.github.io/squest/),
+[HSBC](https://hsbc.github.io/pyratings/),
[ING](https://ing-bank.github.io/baker/),
[Intel](https://open-amt-cloud-toolkit.github.io/docs/),
[JetBrains](https://jetbrains.github.io/projector-client/mkdocs/),
@@ -246,45 +276,59 @@ For detailed installation instructions, configuration options, and a demo, visit
[Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
[Netflix](https://netflix.github.io/titus/),
[Red Hat](https://ansible.readthedocs.io/projects/lint/),
-[Salesforce](https://policy-sentry.readthedocs.io/en/latest/),
+[Roboflow](https://inference.roboflow.com/),
+[Salesforce](https://policy-sentry.readthedocs.io/),
[SIEMENS](https://opensource.siemens.com/),
[Slack](https://slackhq.github.io/circuit/),
[Square](https://square.github.io/okhttp/),
+[Uber](https://uber-go.github.io/fx/),
[Zalando](https://opensource.zalando.com/skipper/)
### ... and successful Open Source projects
+[Amp](https://amp.rs/docs/),
[Arduino](https://arduino.github.io/arduino-cli/),
[Auto-GPT](https://docs.agpt.co/),
[AutoKeras](https://autokeras.com/),
[BFE](https://www.bfe-networks.net/),
[CentOS](https://docs.infra.centos.org/),
[Crystal](https://crystal-lang.org/reference/),
+[eBPF](https://ebpf-go.dev/),
[Electron](https://www.electron.build/),
[FastAPI](https://fastapi.tiangolo.com/),
+[Freqtrade](https://www.freqtrade.io/en/stable/),
[GoReleaser](https://goreleaser.com/),
+[HedgeDoc](https://docs.hedgedoc.org/),
+[Hummingbot](https://hummingbot.org/),
[Knative](https://knative.dev/docs/),
[Kubernetes](https://kops.sigs.k8s.io/),
[kSQL](https://docs.ksqldb.io/),
+[NetBox](https://netboxlabs.com/docs/netbox/en/stable/),
[Nokogiri](https://nokogiri.org/),
[OpenFaaS](https://docs.openfaas.com/),
+[Orchard Core](https://docs.orchardcore.net/en/latest/),
[Percona](https://docs.percona.com/percona-monitoring-and-management/),
[Pi-Hole](https://docs.pi-hole.net/),
[Pydantic](https://pydantic-docs.helpmanual.io/),
[PyPI](https://docs.pypi.org/),
[Renovate](https://docs.renovatebot.com/),
+[RetroPie](https://retropie.org.uk/docs/),
+[Supervision](https://supervision.roboflow.com/latest/),
[Traefik](https://docs.traefik.io/),
[Trivy](https://aquasecurity.github.io/trivy/),
+[Typer](https://typer.tiangolo.com/),
+[tinygrad](https://docs.tinygrad.org/),
+[Ultralytics](https://docs.ultralytics.com/),
[Vapor](https://docs.vapor.codes/),
-[ZeroNet](https://zeronet.io/docs/),
[WebKit](https://docs.webkit.org/),
-[WTF](https://wtfutil.com/)
+[WTF](https://wtfutil.com/),
+[ZeroNet](https://zeronet.io/docs/)
## License
**MIT License**
-Copyright (c) 2016-2023 Martin Donath
+Copyright (c) 2016-2024 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml
index 6a4302069fc..722d92d276c 100644
--- a/docs/blog/.authors.yml
+++ b/docs/blog/.authors.yml
@@ -3,7 +3,14 @@ authors:
name: Martin Donath
description: Creator
avatar: https://avatars.githubusercontent.com/u/932156
+ url: https://github.com/squidfunk
alexvoss:
name: Alex Voss
- description: Community support
+ description: Solutions Architect
avatar: https://avatars.githubusercontent.com/u/4134224
+ url: https://github.com/alexvoss
+ katharinalisalin:
+ name: Kathi
+ description: Communications
+ avatar: https://avatars.githubusercontent.com/u/105352741
+ url: https://github.com/katharinalisalin
diff --git a/docs/blog/posts/adding-a-badge-to-your-project.md b/docs/blog/posts/adding-a-badge-to-your-project.md
new file mode 100644
index 00000000000..26fd7bd9b54
--- /dev/null
+++ b/docs/blog/posts/adding-a-badge-to-your-project.md
@@ -0,0 +1,37 @@
+---
+title: Adding a badge to your project
+date: 2023-11-30
+authors: [squidfunk]
+slug: adding-a-badge-to-your-project
+description: >
+ Share the love – you can now add a badge to your README, showing that your
+ project is built with Material for MkDocs
+categories:
+ - General
+---
+
+# Adding a :simple-materialformkdocs: badge to your project
+
+__You enjoy working with Material for MkDocs? Share the love! You can now add
+a badge to your project's README, showing that your project is built with
+Material for MkDocs.__
+
+Material for MkDocs' logo was just added to [Simple Icons], which is used by
+[Shields.io] to include logos in badges. We generated a badge for you, which
+you can add to your project's README:
+
+[![Material for MkDocs][badge]](#usage)
+
+
+
+## Usage
+
+Just copy the following snippet and paste it into your project's `README.md`:
+
+``` markdown
+[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
+```
+
+ [Simple Icons]: https://simpleicons.org/
+ [Shields.io]: https://shields.io/
+ [badge]: https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white
diff --git a/docs/blog/posts/blog-support-just-landed.md b/docs/blog/posts/blog-support-just-landed.md
index 9b0efa2c804..8d83ecf307a 100644
--- a/docs/blog/posts/blog-support-just-landed.md
+++ b/docs/blog/posts/blog-support-just-landed.md
@@ -78,7 +78,7 @@ nav:
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_dir]: ../../plugins/blog.md#config.blog_dir
#### Blog setup
@@ -182,12 +182,12 @@ 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
+ [post slugs]: ../../plugins/blog.md#config.post_url_format
+ [draft]: ../../plugins/blog.md#meta.draft
+ [This behavior can be changed]: ../../plugins/blog.md#config.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
+ [archive]: ../../plugins/blog.md#config.archive
+ [category]: ../../plugins/blog.md#config.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
diff --git a/docs/blog/posts/chinese-search-support.md b/docs/blog/posts/chinese-search-support.md
index 0652696b4ed..c1ab7b735df 100644
--- a/docs/blog/posts/chinese-search-support.md
+++ b/docs/blog/posts/chinese-search-support.md
@@ -10,7 +10,7 @@ categories:
links:
- blog/posts/search-better-faster-smaller.md
- plugins/search.md#segmentation
- - insiders/index.md#how-to-become-a-sponsor
+ - insiders/how-to-sponsor.md
---
# Chinese search support – 中文搜索支持
@@ -78,6 +78,6 @@ improved, please [open an issue].
[jieba]: https://pypi.org/project/jieba/
[zero-width whitespace]: https://en.wikipedia.org/wiki/Zero-width_space
- [separator]: ../../setup/setting-up-site-search.md#separator
+ [separator]: ../../plugins/search.md#config.separator
[q=支持]: ?q=支持
[open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
diff --git a/docs/blog/posts/excluding-content-from-search.md b/docs/blog/posts/excluding-content-from-search.md
index d84ef54c100..85428ea70e0 100644
--- a/docs/blog/posts/excluding-content-from-search.md
+++ b/docs/blog/posts/excluding-content-from-search.md
@@ -9,7 +9,7 @@ categories:
links:
- blog/posts/search-better-faster-smaller.md
- setup/setting-up-site-search.md#search-exclusion
- - insiders/index.md#how-to-become-a-sponsor
+ - insiders/how-to-sponsor.md
---
# Excluding content from search
diff --git a/docs/blog/posts/search-better-faster-smaller.md b/docs/blog/posts/search-better-faster-smaller.md
index 5e3ab2d3d1d..dcdeec96128 100644
--- a/docs/blog/posts/search-better-faster-smaller.md
+++ b/docs/blog/posts/search-better-faster-smaller.md
@@ -10,7 +10,7 @@ categories:
- Performance
links:
- plugins/search.md
- - insiders/index.md#how-to-become-a-sponsor
+ - insiders/how-to-sponsor.md
---
# Search: better, faster, smaller
@@ -36,7 +36,7 @@ implementation. If you immediately want to learn what's new, skip to the
[section just after that][what's new]._
[search]: ../../setup/setting-up-site-search.md
- [multilingual]: ../../setup/setting-up-site-search.md#lang
+ [multilingual]: ../../plugins/search.md#config.lang
[offline-capable]: ../../setup/building-for-offline-usage.md
[what's new]: #whats-new
@@ -206,7 +206,7 @@ more magic involved, e.g., search results are [post-processed] and [rescored] to
account for some shortcomings of [lunr], but in general, this is how data gets
into and out of the index.
- [separator]: ../../setup/setting-up-site-search.md#search-separator
+ [separator]: ../../plugins/search.md#config.separator
[default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
[post-processed]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L249-L272
[rescored]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L274-L275
@@ -486,7 +486,7 @@ digit `\d`, which leaves version numbers discoverable. Searching for
[:octicons-search-24: 7.2.6][q=7.2.6] brings up the [7.2.6] release notes.
[q=7.2.6]: ?q=7.2.6
- [7.2.6]: ../../changelog/index.md#726-_-september-1-2021
+ [7.2.6]: ../../changelog/index.md#7.2.6
#### HTML/XML tags
@@ -499,19 +499,12 @@ following expression to the separator allows for just that:
&[lg]t;
```
-Searching for [:octicons-search-24: custom search worker script][q=script]
-brings up the section on [custom search] and matches the `script` tag among the
-other search terms discovered.
-
---
_We've only just begun to scratch the surface of the new possibilities
tokenizer lookahead brings. If you found other useful expressions, you're
invited to share them in the comment section._
- [q=script]: ?q=custom+search+worker+script
- [custom search]: ../../setup/setting-up-site-search.md#custom-search
-
### Accurate highlighting
Highlighting is the last step in the process of search and involves the
@@ -634,4 +627,4 @@ for MkDocs! This is the first blog article that I decided to write after a
short [Twitter survey] made me to. You're invited to leave a comment
to share your experiences with the new search implementation.
- [Twitter survey]: https://twitter.com/squidfunk/status/1434477478823743488
+ [X survey]: https://x.com/squidfunk/status/1434477478823743488
diff --git a/docs/blog/posts/sunsetting-gitter.md b/docs/blog/posts/sunsetting-gitter.md
index 837fe453a26..4cc96601977 100644
--- a/docs/blog/posts/sunsetting-gitter.md
+++ b/docs/blog/posts/sunsetting-gitter.md
@@ -18,7 +18,6 @@ allow to ask the community for support and to discuss ideas and issues. In the
past weeks, we have begun to question whether this duplication is in the best
interest of our project. This post explains the rationale behind our decision.
- [our sponsors]: ../../insiders/index.md#how-to-become-a-sponsor
[Gitter]: https://gitter.im/squidfunk/mkdocs-material
[GitHub discussions]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/docs/blog/posts/the-past-present-and-future.md b/docs/blog/posts/the-past-present-and-future.md
index a95a722148b..1179d390c2a 100644
--- a/docs/blog/posts/the-past-present-and-future.md
+++ b/docs/blog/posts/the-past-present-and-future.md
@@ -169,7 +169,7 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times.
[Code annotations]: ../../reference/code-blocks.md#adding-annotations
[Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments
[Code block titles]: ../../reference/code-blocks.md#adding-a-title
- [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#anchor-linenums
+ [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#+pymdownx.highlight.anchor_linenums
[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
@@ -213,7 +213,7 @@ Source projects sustainable by following a well-designed release strategy.
You can learn about the strategy in the [Insiders] guide.
- [awesome sponsors]: ../../insiders/index.md#how-to-become-a-sponsor
+ [awesome sponsors]: ../../insiders/how-to-sponsor.md
## 2022
@@ -254,12 +254,12 @@ features that will see the light of day in 2022:
Material for MkDocs.
This list is incomplete. Additionally, many new smaller features will be added
-next year, just as in 2021. You can follow [@squidfunk on Twitter] to stay
+next year, just as in 2021. You can follow [@squidfunk on X] to stay
updated.
__Happy new year!__ :tada:
- [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
+ [Instant previews]: https://x.com/squidfunk/status/1466794654213492743
[card grids]: https://github.com/squidfunk/mkdocs-material/issues/3018
[under investigation]: https://github.com/squidfunk/mkdocs-material/issues/3353
- [@squidfunk on Twitter]: https://twitter.com/squidfunk
+ [@squidfunk on X]: https://x.com/squidfunk
diff --git a/docs/blog/posts/transforming-material-for-mkdocs.md b/docs/blog/posts/transforming-material-for-mkdocs.md
new file mode 100644
index 00000000000..d1df1935b65
--- /dev/null
+++ b/docs/blog/posts/transforming-material-for-mkdocs.md
@@ -0,0 +1,213 @@
+---
+date: 2024-08-19
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+categories:
+ - General
+description: >
+ We are transforming Material for MkDocs to ensure its community continues to thrive and doubling down on our commitment to Open Source.
+title: How we're transforming Material for MkDocs
+---
+
+# Transforming Material for MkDocs
+
+__We are working on an amazing set of features which has required some behind-the-scenes work we are now ready to share in a series of posts. Here, we give an overview of our goals, features in the making, things that kept us up at night, and our commitment to Open Source.__
+
+We know it's been quite a while since our last update, which is why we're eager to share what's happening in and around Material for MkDocs with you. For the largest part of 2024, we've been focused on transforming the core of Material for MkDocs preparing the ground for new, interconnected features that are amongst the most frequently requested.
+
+This article is the first in a series where we'll explore how we aim to support our users through improved information retrieval, provide better support for multi-lingual sites and versioning, as well as improve the overall authoring experience. We outline our vision for the projects' evolution and describe what we have been working on. In this and the coming blog posts, we will share our progress with you, and we're excited to hear your thoughts.
+
+
+
+_Please note that this post includes several technical details in the footnotes, specifically on challenges. Feel free to skip them if you're not interested in the specifics._
+
+## A success story
+
+In 2024, Material for MkDocs has firmly established itself as a leading tool in the documentation framework landscape, with more than 5 million downloads each month as of this writing. What began as @squidfunk's personal project has evolved into a versatile resource for creating comprehensive documentation sites, personal websites, blogs, and notably, for managing knowledge both within and outside of organizations.
+
+With almost [50,000] public GitHub projects depending on Material for MkDocs, it's clear that the framework has made a substantial impact. Tens of thousands of authors rely on us to deliver documentation to millions of users each month.[^1] Beyond its adoption by [many popular Open Source projects], Material for MkDocs is trusted and financially supported by major corporations such as [AWS], [Microsoft], and [Siemens], among many other companies and individuals. We're very grateful for the continued support we receive, which allows us to devote our time to this project, making writing documentation enjoyable.
+
+ [^1]:
+ We've collected invaluable feedback from enterprises and other Open Source maintainers, which revealed that the actual numbers are even higher. Many organizations leverage the framework within private infrastructures, such as self-hosted platforms like GitLab, for internal knowledge management. This suggests that the true reach of Material for MkDocs extends far beyond what is publicly visible.
+
+ [50,000]: https://github.com/squidfunk/mkdocs-material/network/dependents
+ [many popular Open Source projects]: https://github.com/squidfunk/mkdocs-material?tab=readme-ov-file#trusted-by-
+ [AWS]: https://x.com/squidfunk/status/1740389441284579767
+ [Microsoft]: https://x.com/squidfunk/status/1801909506391105840
+ [Siemens]: https://x.com/squidfunk/status/1699799988069646761
+
+Our users particularly appreciate Material for MkDocs for its ease of use and straightforward setup. It simplifies the process by handling the complexities of web technologies for you, so you can build a production-ready static site in minutes without needing to invest years into mastering frontend development or JavaScript. This makes it accessible to a wide range of users, regardless of their technical background. Additionally, Material for MkDocs is MIT-licensed and free to use, which has contributed to its widespread adoption, and allows everybody to build sophisticated documentation sites at no cost.
+
+Our vision is to provide you with the tools that allow you to __own your docs__, enable you to develop your own processes for producing amazing documentation and to avoid being locked into costly subscription services even for doing simple things. We believe it is important that these tools should be easy to set up and configure to suit your needs but should also give you the freedom to adapt them further, if needed. This is why we are always striving to ensure our architectures are modular and future-proof.[^2]
+
+ [^2]:
+ The [built-in plugins] that Material for MkDocs ships perfectly outline this principle, as they are complementary to each other and can be used in combination to build sophisticated pipelines. This modular design allows users to pick and choose the features they need, ensuring that the framework remains lightweight and flexible.
+
+ For instance, the [privacy plugin] can work together with the [optimize plugin] so that external assets can be passed through the same optimization pipeline as the rest of your documentation. This means you can store and edit unoptimized files outside of your repository, and let both plugins automatically build an optimized site for you.
+
+ [built-in plugins]: ../../plugins/index.md
+ [privacy plugin]: ../../plugins/privacy.md
+ [optimize plugin]: ../../plugins/optimize.md
+
+## Challenges
+
+Now, let's talk about our journey and the particular challenges we're addressing. With "we", we're referring to the incredible team that @squidfunk was fortunate to build around his original work, thanks to the financial support he receives from his [sponsors]. This remarkable team includes @alexvoss and @katharinalisalin, whose invaluable contributions in research, development, and community support have been essential to the project's ongoing success.
+
+Together, we've started exploring new technologies, incorporating the feedback we received from our users, and rethinking critical components from first principles, serving our growing community one of the best frameworks to create documentation.
+
+ [sponsors]: https://github.com/sponsors/squidfunk
+
+This section highlights the key areas we've been focusing on.
+
+### Search and discovery
+
+From our perspective, search is a cornerstone of any effective documentation site, enabling users to swiftly locate the information they need. From the start, we've relied on [Lunr.js], a popular client-side search library that has streamlined the deployment of documentation sites without needing an external service. Over the years, Lunr.js has served us well by answering millions of queries on sites built with Material for MkDocs. Yet, as our users' needs evolved, we encountered limitations that proved difficult to overcome.
+
+ [Lunr.js]: https://github.com/olivernn/lunr.js
+
+We learned that the [BM25 ranking algorithm] at the core of Lunr.js (as in many other search implementations) isn't well-suited for effective and stable typeahead. Adding new documents can influence existing rankings, requiring manual adjustments[^3] that are cumbersome and hard to scale. Furthermore, Lunr.js has performance issues that stem from its design not fully leveraging modern JavaScript engines and optimizations, making it slower and memory-intensive.[^4]
+
+ [^3]:
+ Boosting documents in [BM25][BM25 ranking algorithm] can lead to challenges, particularly with a changing corpus of documents. Relevance is calculated based on term frequency and the importance of terms across the entire corpus. Boosting a document involves adjusting its weight to make it more prominent in search results.
+
+ As new documents are added or existing ones are modified, the overall distribution of term frequencies and their importance can shift. This recalibration can diminish the effectiveness of the boost, making it harder to maintain consistent ranking across a changing dataset. Essentially, the boosted documents may not stay as prominent or relevant as intended, leading to imbalances and scalability issues in search results.
+
+ [^4]:
+ Lunr.js uses JavaScript objects to index and manage search data, which introduces inefficiencies due to how JavaScript engines handle object operations. JavaScript engines optimize performance using techniques like inline caching and object shape optimization. However, these optimizations rely on predictable and consistent object structures.
+
+ The dynamic nature of Lunr.js' indexing — where documents can have varying structures — prevents the engine from applying these optimizations effectively. This means that while JavaScript engines can optimize for fixed, predictable object structures, they struggle with the polymorphic and fluid nature of Lunr.js's indexing, leading to performance issues as the amount of data grows.
+
+ [BM25 ranking algorithm]: https://en.wikipedia.org/wiki/Okapi_BM25
+
+Over the last years, we've invested substantially into [improving the search experience]. For instance, expanding Lunr.js' functionality to add support for [rich search previews] and [tokenizer lookahead] demanded substantial engineering effort. Lunr.js allows to customize tasks such as stemming, stopword filtering, and trimming with [pipeline functions], but it makes it particularly hard to add extensions like term highlighting or alternative ranking methods. Compounded by the fact that Lunr.js has been [unmaintained since 2020], it became clear that we needed to find a more powerful solution. We've looked at alternative JavaScript-based libraries to keep our client-side search, but none met our requirements or lived up to our expectations.
+
+ [improving the search experience]: search-better-faster-smaller.md
+ [rich search previews]: search-better-faster-smaller.md#rich-search-previews
+ [tokenizer lookahead]: search-better-faster-smaller.md#tokenizer-lookahead
+ [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+ [unmaintained since 2020]: https://github.com/olivernn/lunr.js/releases/tag/
+
+To address these challenges, we've embarked on developing a new search system from first principles that not only matches but already exceeds the capabilities of Lunr.js. Built from the ground up, this system is faster, more compact, and most importantly: modular. It is based on a growing core evolving around two core concepts we isolated to be essential – engines and plugins – allowing for flexible configuration and assembly of components like text indexing, vector embeddings, filtering, ranking, highlighting, and more. Every part of it can be replaced or extended, enabling users to tailor the search system to their specific needs.
+
+Our new search system, which we will release as a separate MIT-licensed Open Source project, is designed to handle a wide range of scenarios — from small blogs to large documentation projects. Of course, it supports offline use and integrates seamlessly with both client and server environments. The advanced ranking system provides fine-tuned control, and integration with third-party services is now more straightforward.
+
+__:octicons-goal-16: Goal – Empower users to quickly find the information they need while freeing authors from managing external services, by providing a search system that adapts to diverse content types.__
+
+You might wonder why it's not yet available. The process of developing this system from scratch and uncovering its potential has led us to re-evaluate core concepts of Material for MkDocs. As a result, we've decided to postpone the release of the new search system to integrate it into the broader update that we've started to work on. If you keep on reading, you'll learn about further reasons why we've decided to follow this approach.
+
+We're excited to share more details about this update in one of the next posts in this series.
+
+### Translations and versioning
+
+Supporting multi-language sites in MkDocs is the [most requested feature on our discussion board] and in conversations with users, yet it presents significant challenges, as MkDocs does not natively support it. The same applies to versioning, which also involves synchronisation of multi-project builds. While the MkDocs ecosystem has developed [various plugins and tools] to address these issues, there is still substantial untapped potential. We began exploring these areas but quickly encountered problems that hindered our progress.
+
+ [most requested feature on our discussion board]: https://github.com/squidfunk/mkdocs-material/discussions/2346
+ [various plugins and tools]: https://github.com/mkdocs/catalog?tab=readme-ov-file#-site-building-site-management
+
+As you may know, our initial effort involved the [projects plugin] that aims to extend MkDocs to add support for multi-project environments as a solid foundation to support multi-language sites and versioning. Unfortunately, we encountered significant challenges due to MkDocs' internal architecture and design constraints, which we're working actively on resolving.[^5]
+
+ [^5]:
+ When developing the [projects plugin], we initially made [good progress], including adding support for nested projects and allowing for a tree structure where sub-projects can have further sub-projects. However, we quickly encountered difficulties, particularly with cross-project navigation. To illustrate, imagine that each project can link to any other project, which makes handling these interconnections complex, especially when dealing with circular dependencies — such as Project A linking to Project B and vice versa.
+
+ Implementing multi-project support in MkDocs is particularly challenging due to the lack of an official programmatic API, which complicates efforts to extend its functionality. Moreover, resolving navigation issues before building projects is crucial for ensuring proper interconnectivity. These challenges combined made the development of the projects plugin a complex endeavor.
+
+ [projects plugin]: ../../plugins/projects.md
+ [good progress]: https://github.com/squidfunk/mkdocs-material/discussions/5800
+
+__:octicons-goal-16: Goal – Enable scaling documentation to any size or team structure by offering seamless methods for integrating multiple documentation projects, whether they involve different languages, versions, or distinct sections of an overall body of work.__
+
+As a result, we are developing a new approach to offer a more comprehensive and robust solution for both multi-language support and versioning. This new approach also intersects with adjacent functionalities like search, as many of our users are interested in [federated search] capabilities that combine results from multiple documentation sites into a unified search interface. Overcoming this challenge is one of the major hurdles we need to address before releasing the new search system.
+
+ [federated search]: https://github.com/squidfunk/mkdocs-material/issues/5230
+
+### Editing and collaboration
+
+We had considered developing a live editor in response to MkDocs' [performance issues with large projects], which in most cases stem from compute-intensive plugins that don't employ caching. A [proof of concept] based on [Pyodide] (= running Python in the browser) [generated significant interest] among users and prompted many organizations and individuals to share their collaborative workflows for feedback. Sadly, implementing this live editor proved to be very challenging, as it would require rebuilding substantial parts of MkDocs.[^6] After discontinuing work on this approach, our progress with multi-project support has renewed our belief that we can finally solve the sluggish editing experience that was reported several times over the last years.[^7]
+
+ [performance issues with large projects]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2093299518
+ [proof of concept]: https://x.com/squidfunk/status/1338252230265360391
+ [Pyodide]: https://pyodide.org/
+ [generated significant interest]: https://github.com/squidfunk/mkdocs-material/issues/2110
+
+ [^6]:
+ Our [proof of concept] supported some features of Material for MkDocs but didn't cover them all. For instance, integrating support for icons or linking between documents would have necessitated reimplementing parts of MkDocs to bypass a full rebuild — something we obviously wanted to avoid. Additionally, certain links, such as those to blog posts generated from schemas, are not merely translated but computed dynamically, which means they cannot be inferred by replacing the `.md` extension with `.html`.
+
+ [^7]:
+ After [we raised this issue] with the maintainers of MkDocs again[^8], and [maintainership changed] mid 2024, work on a [ground-up rewrite] that aims to address slow reloads by [rendering only the page currently being built] has started. It's still unclear how this rewrite will integrate with the requirements of existing plugins. Complex plugins such as [mkdocstrings], or our [built-in blog] and [tags] plugins require a coordinated build of all pages to accurately resolve links between pages and to computed resources, which cannot be determined without building the entire project.
+
+ __Update__{ title="August 21, 2024" }: The new maintainer now publicly stated that he's working towards a new version of MkDocs that [does not require or support plugins], and mentions it will be equally capable through offering customization via templating, themes, and styling, which he also mentioned to us and several other users in [a team call on August 1]. In this call, [we raised objections multiple times] in regards to how this will impact the ecosystem, to no avail. No intention or roadmap for plugin support was provided. This development is orthogonal to our goal empowering users and organizations to adapt the core framework to their requirements by the means of modularity. We're working on resolving this situation, and will provide a way forward for our community.
+
+ [we raised this issue]: https://github.com/mkdocs/mkdocs/issues/3695
+ [maintainership changed]: https://github.com/mkdocs/mkdocs/discussions/3677
+ [ground-up rewrite]: https://github.com/mkdocs/sketch
+ [rendering only the page currently being built]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2117939743
+ [mkdocstrings]: https://mkdocstrings.github.io/
+ [built-in blog]: ../../plugins/blog.md
+ [tags]: ../../plugins/tags.md
+ [does not require or support plugins]: https://github.com/mkdocs/mkdocs/discussions/3815#discussioncomment-10398312
+ [a team call on August 1]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10164237
+ [we raised objections multiple times]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10215445
+
+ [^8]:
+ Previously raised issues include [#2418], [#2384], and [#1900].
+
+ [#1900]: https://github.com/mkdocs/mkdocs/issues/1900
+ [#2384]: https://github.com/mkdocs/mkdocs/issues/2384
+ [#2418]: https://github.com/mkdocs/mkdocs/issues/2418
+
+This brings us to collaboration, which wasn't initially on our list of priorities. However, throughout 2024, conversations with various organizations and maintainers of popular Open Source projects highlighted a frequent request for enhanced collaboration features. Many users expressed a need for capabilities that would allow non-technical team members to suggest and make changes to the documentation. We're genuinely grateful for this feedback, as it has come at a pivotal time. We recognize the need to streamline tracking and discussing changes, as well as to facilitate drive-by contributions.
+
+__:octicons-goal-16: Goal – Everyone, regardless of their technical skill level, can easily work on and improve the documentation and contribute to a growing corpus of knowledge.__[^9]
+
+ [^9]:
+ We are actively aligning our future development efforts to address this, recognizing it as a key area for improvement. While it's not something we can deliver immediately, we are committed to making this vision a reality in our work.
+
+This focus on collaboration aligns with how knowledge is managed in enterprises. In large organizations, documentation often exists in [information silos] — decentralized yet essential repositories of information. We understand the need to be able to unify these disparate sources into a coherent body of knowledge while preserving decentralized ownership. This also nicely aligns with our previously outlined work on multi-project support, as well as the new search system to implement [federated search] among multiple projects.
+
+ [information silos]: https://en.wikipedia.org/wiki/Information_silo
+
+### Large Language Models (LLMs)
+
+Almost a year ago, we introduced an [experimental chatbot] on our documentation site. It quickly became one of the most anticipated features, with users requesting the ability to deploy similar functionality on their own sites, underscoring the growing demand for interactive documentation tools. However, we found that adding to the myriad of existing chat solutions and simply building another thin wrapper on top of ChatGPT is nonsense.
+
+__:octicons-goal-16: Goal – We're envisioning creating a unified interface that seamlessly integrates advanced search, chat, and summarization features, providing an interactive documentation experience.__
+
+ [experimental chatbot]: https://github.com/squidfunk/mkdocs-material/discussions/6240
+
+As we delved into this ambitious project, we gained valuable insights from user feedback. Users began interacting with the chatbot in their native languages, an outcome we hadn't anticipated given that our documentation is in English. Remarkably (or obviously to those that work on LLMs year round), the chatbot responded in the same language. This ability of LLMs is one of the genuinely exciting features of these machine learning models as it has the potential to improve the accessibility of the documentation. However, while we employed state-of-the-art RAG methodologies, the results were mixed, and occasional hallucinations surfaced.
+
+These experiences led us to prioritize enhancing our search capabilities before integrating LLM-based features. Building a search engine from scratch was already a substantial effort, and adding more complexity without a solid search foundation would be premature. By rearchitecting our search functionalities, we aim to create a robust platform that will seamlessly support advanced information retrieval and deliver a cohesive interactive documentation experience.
+
+## Team, transparency, and growth
+
+While we navigate the challenges and explore the opportunities of this project, we consider it essential to demonstrate how we're building a solid foundation for its continued growth and success. Please consider this an overview rather than a formal roadmap — our detailed plans are in the works. The goals we've highlighted represent the most impactful areas we aim to address.
+
+Thanks to the generous support from our sponsors, we're fortunate to be assembling a team capable of dedicating significant time and expertise to this endeavor. This newfound capacity allows us to delve deeper into core development while also engaging more comprehensively with our user community. A special mention goes to @kamilkrzyskow, one of our invaluable [community experts], who has been essential in supporting users and fostering discussions on our platform.
+
+ [community experts]: http://localhost:3000/mkdocs-material/insiders/community-experts-program/
+
+With the team's support, @squidfunk can concentrate on the heart of development, while we have begun investing in user research. This effort is helping us understand how organizations and individuals interact with our tools, guiding the project's future direction based on real feedback from numerous conversations with users and companies.
+
+Looking to expand our team further, we are committed to improving transparency and communication. Our previous work often happened behind the scenes due to time constraints, but we're now focused on making our processes more open and inviting for new contributors. By embracing this collaborative approach, we aim to enhance our tools and ensure they meet the evolving needs of our community.
+
+## What's ahead of us
+
+As we look into the future, some of the groundwork we're laying now is crucial for the exciting developments on the horizon. Many of the initiatives we've discussed represent foundational work that will set the stage for much more ambitious and innovative features. Once these core elements are in place, we'll deliver a range of exciting new functionalities that align with our vision and goals.
+
+In the coming months, we'll be sharing more details about our plans and how they will contribute to our overarching objectives. While growth and innovation are at the forefront of our plans, we want to assure you that our core values remain unchanged. We are committed to maintaining the principles that have guided us thus far, ensuring that our growth is both healthy and consistent:
+
+- Against recent industry trends with companies moving away from core ideas of Open Source, we are doubling down on our commitment to Open Source because we believe it's at the heart of the value proposition of our work and the [docs as code] approach.
+
+ [docs as code]: https://www.writethedocs.org/guide/docs-as-code/
+
+- Our [organic approach to growth] is part of this strategy as it keeps us independent of individual funding sources and pressures to provide a return on investment, which is what causes many other projects to turn away from the principles of Open Source.
+
+ [organic approach to growth]: https://star-history.com/#squidfunk/mkdocs-material
+
+- Likewise, we are driven by the needs of the community for a rich ecosystem of adaptations of the core framework. Extensibility and modularity are key for this and we are working hard to improve the developer experience by providing clear interfaces.
+
+Stay tuned for updates as we continue to build on our progress and explore new possibilities. We're excited about the future and look forward to sharing more with you as we advance.
+
+_Martin, Alex and Kathi_ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
diff --git a/docs/changelog/index.md b/docs/changelog/index.md
index bc7b0654200..29e712cef48 100644
--- a/docs/changelog/index.md
+++ b/docs/changelog/index.md
@@ -2,6 +2,305 @@
## Material for MkDocs
+### 9.5.43 October 31, 2024 { id="9.5.43" }
+
+- Added support for external images in SVGs in privacy plugin
+- Fixed #7651: Privacy plugin doesn't handle quoted URLs in CSS
+
+### 9.5.42 October 20, 2024 { id="9.5.42" }
+
+- Fixed #7625: Invalid encoding of boolean attributes in privacy plugin
+- Fixed #7624: Crash when disabling privacy plugin (9.5.41 regression)
+
+### 9.5.41 October 15, 2024 { id="9.5.41" }
+
+- Fixed #7619: Improved tooltip on logo disappears after instant navigation
+- Fixed #7616: Race condition in built-in privacy plugin when inlining assets
+- Fixed #7615: Comments and "Was this page helpful?" visible when printing
+
+### 9.5.40 October 10, 2024 { id="9.5.40" }
+
+- Updated Latvian translations
+- Fixed #7597: Social cards not using site name on home page
+
+### 9.5.39 September 29, 2024 { id="9.5.39" }
+
+- Fixed #7226: not staying on page when using mike's canonical versioning
+
+### 9.5.38 September 26, 2024 { id="9.5.38" }
+
+- Added Albanian translations
+
+### 9.5.37 September 25, 2024 { id="9.5.37" }
+
+- Added 4th and 5th level ordered list styles
+- Fixed #7548: Tags have no spacing in search
+
+### 9.5.36 September 21, 2024 { id="9.5.36" }
+
+- Fixed #7544: Social cards incorrectly rendering HTML entities
+- Fixed #7542: Improved support for setting custom list styles
+
+### 9.5.35 September 18, 2024 { id="9.5.35" }
+
+- Fixed #7498: Search not showing for Vietnamese language
+
+### 9.5.34 August 31, 2024 { id="9.5.34" }
+
+- Updated Mermaid.js to version 11 (latest)
+
+### 9.5.33 August 23, 2024 { id="9.5.33" }
+
+- Fixed #7453: Incorrect position of tooltip when sorting table
+
+### 9.5.32 August 19, 2024 { id="9.5.32" }
+
+- Fixed RXSS vulnerability via deep link in search results
+- Added support for fetching latest release from GitLab
+
+### 9.5.31 August 2, 2024 { id="9.5.31" }
+
+- Fixed #7405: DockerHub missing images > 9.5.27 due to change in Alpine/APK
+
+### 9.5.30 July 23, 2024 { id="9.5.30" }
+
+- Fixed #7380: Navigation icons disappearing on hover in Safari
+- Fixed #7367: Blog readtime computation includes SVG text content
+
+### 9.5.29 July 14, 2024 { id="9.5.29" }
+
+- Updated Galician translations
+- Fixed #7362: Annotations in figure captions rendering incorrectly
+
+### 9.5.28 July 2, 2024 { id="9.5.28" }
+
+- Fixed #7313: Improved tooltips mounted in sidebar when feature is disabled
+
+### 9.5.27 June 16, 2024 { id="9.5.27" }
+
+- Updated Estonian translations
+
+### 9.5.26 June 6, 2024 { id="9.5.26" }
+
+- Fixed #7232: Tab switches on scroll when linking tabs (9.5.19 regression)
+- Fixed #7230: Blog author avatar broken when referring to local file
+
+### 9.5.25 May 27, 2024 { id="9.5.25" }
+
+- Fixed #7209: Tags plugin crashing on numeric tags
+
+### 9.5.24 May 20, 2024 { id="9.5.24" }
+
+- Fixed #7187: Version selector title rendering issue
+
+### 9.5.23 May 15, 2024 { id="9.5.23" }
+
+- Fixed #7183: Edge case in anchor navigation when using instant navigation
+- Fixed #6436: Version selector not showing version alias
+
+### 9.5.22 May 12, 2024 { id="9.5.22" }
+
+- Fixed #7170: Copy button adds empty lines for line spans (9.5.18 regression)
+- Fixed #7160: Version switching doesn't stay on page (9.5.5 regression)
+- Fixed #5619: Links in Mermaid.js diagrams not discernible
+
+### 9.5.21 May 3, 2024 { id="9.5.21" }
+
+- Fixed #7133: Ensure latest version of Mermaid.js is used
+- Fixed #7125: Added warning for dotfiles in info plugin
+
+### 9.5.20 April 29, 2024 { id="9.5.20" }
+
+- Fixed deprecation warning in privacy plugin (9.5.19 regression)
+- Fixed #7119: Tags plugin emits deprecation warning (9.5.19 regression)
+- Fixed #7118: Social plugin crashes if fonts are disabled (9.5.19 regression)
+- Fixed #7085: Social plugin crashes on Windows when downloading fonts
+
+### 9.5.19 April 25, 2024 { id="9.5.19" }
+
+- Updated MkDocs to 1.6 and limited version to < 2
+- Updated Docker image to latest Alpine Linux
+- Removed `setup.py`, now that GitHub fully understands `pyproject.toml`
+- Improved interop of social plugin with third-party MkDocs themes
+- Fixed #7099: Blog reading time not rendered correctly for Japanese
+- Fixed #7097: Improved resilience of tags plugin when no tags are given
+- Fixed #7090: Active tab indicator in nested content tabs rendering bug
+
+### 9.5.18 April 16, 2024 { id="9.5.18" }
+
+- Refactored tooltips implementation to fix positioning issues
+- Fixed #7044: Rendering glitch when hovering contributor avatar in Chrome
+- Fixed #7043: Highlighted lines in code blocks cutoff on mobile
+- Fixed #6910: Incorrect position of tooltip for page status in sidebar
+- Fixed #6760: Incorrect position and overly long tooltip in tables
+- Fixed #6488: Incorrect position and cutoff tooltip in content tabs
+
+### 9.5.17 April 2, 2024 { id="9.5.17" }
+
+- Updated Serbian translations
+- Fixed #7003: Confusing keyboard interaction for palette toggle
+- Fixed #7001: Blog posts now show time by default (9.5.16 regression)
+- Fixed edge case in backport of social plugin font loading logic
+
+### 9.5.16 March 31, 2024 { id="9.5.16" }
+
+- Updated Russian translations
+- Improved error handling and reporting in social plugin
+- Improved error handling and reporting in privacy plugin
+- Fixed blog plugin not allowing to use time in format strings
+- Fixed #6983: Social plugin crashes because of Google Fonts API change
+
+### 9.5.15 March 23, 2024 { id="9.5.15" }
+
+- Reverted fix for transparent iframes (9.5.14)
+- Fixed #6929: Interference of social plugin and auto dark mode
+- Fixed #6938: Giscus shows dark background in light mode (9.5.14 regression)
+
+### 9.5.14 March 18, 2024 { id="9.5.14" }
+
+- Added support for hiding versions from selector when using mike
+- Added init system to improve signal handling in Docker image
+- Fixed edge cases in exclusion logic of info plugin
+- Fixed inability to reset pipeline in search plugin
+- Fixed syntax error in Finnish translations
+- Fixed #6917: UTF-8 encoding problems in blog plugin on Windows
+- Fixed #6889: Transparent iframes get background color
+
+### 9.5.13 March 6, 2024 { id="9.5.13" }
+
+- Updated Slovak translations
+- Improved info plugin interop with projects plugin
+- Improved info plugin inclusion/exclusion logic
+- Fixed info plugin not gathering files recursively
+- Fixed #6750: Ensure info plugin packs up all necessary files
+
+### 9.5.12 February 29, 2024 { id="9.5.12" }
+
+- Fixed #6846: Some meta tags removed on instant navigation (9.4.2 regression)
+- Fixed #6823: KaTex not rendering on instant navigation (9.5.5 regression)
+- Fixed #6821: Privacy plugin doesn't handle URLs with encoded characters
+
+### 9.5.11 February 24, 2024 { id="9.5.11" }
+
+- Updated Finnish translation
+
+### 9.5.10 February 19, 2024 { id="9.5.10" }
+
+- Updated Bahasa Malaysia translations
+- Fixed #6783: Hide continue reading link for blog posts without separators
+- Fixed #6779: Incorrect positioning of integrated table of contents
+
+### 9.5.9 February 10, 2024 { id="9.5.9" }
+
+- Fixed navigation pruning with tabs and sections enabled
+
+### 9.5.8 February 7, 2024 { id="9.5.8" }
+
+- Added Tamil translations
+- Updated Esperanto translations
+- Fixed relative images not being resolved for instant navigation
+
+### 9.5.7 February 3, 2024 { id="9.5.7" }
+
+- Fixed #6731: Small images in figures are not centered
+- Fixed #6719: Instant navigation breaks table of contents (9.5.5 regression)
+
+### 9.5.6 January 28, 2024 { id="9.5.6" }
+
+- Fixed #6700: Missing styles for Mermaid.js labels with Markdown
+
+### 9.5.5 January 24, 2024 { id="9.5.5" }
+
+- Updated Tagalog translations
+- Updated Pillow to 10.2 to mitigate security vulnerabilities
+- Improved resilience of instant navigation
+- Fixed #6687: Updated Mermaid.js to version 10.7.0 (latest)
+- Fixed #6652: Keyboard events in custom elements captured
+- Fixed #6582: Instant navigation doesn't correctly handle alternate URLs
+- Fixed #6565: Instant navigation doesn't allow for `onclick` handlers
+- Fixed #6345: Instant navigation sometimes breaks browser back button
+- Fixed #6334: Instant navigation doesn't correctly position anchors (Safari)
+- Fixed #6275: Instant navigation doesn't correctly resolve after 404
+- Fixed #6102: Instant navigation reloads page on same link navigation
+
+### 9.5.4 January 15, 2024 { id="9.5.4" }
+
+- Fixed #6645: Local storage with invalid value can break site
+- Fixed #6635: Tags icons before default ignored if default is set
+
+### 9.5.3 December 23, 2023 { id="9.5.3" }
+
+- Limited version range of MkDocs to < 1.6
+- Updated Macedonian translations
+- Fixed #6520: Group plugin crashes when using mike
+- Fixed #6494: Hide author's email address if disabled in git-authors plugin
+
+### 9.5.2 December 11, 2023 { id="9.5.2" }
+
+- Fixed types for `slugify` settings in blog plugin config
+- Fixed #6469: Horizontal scrollbars on MathJax containers
+
+### 9.5.1 December 8, 2023 { id="9.5.1" }
+
+- Updated Greek translations
+- Fixed #6464: Privacy plugin cannot be enabled
+- Fixed #6461: Sorting blog posts ignores time component in date
+
+### 9.5.0 December 7, 2023 { id="9.5.0" }
+
+Merged Insiders features of 'Goat's Horn' funding goal
+
+- Added privacy plugin: automatic downloading of external assets
+- Added support for card grids and grid layouts
+- Added support for improved tooltips
+- Added support for content tabs anchor links (deep linking)
+- Added support for automatic dark/light mode
+- Added support for document contributors
+
+### 9.4.14 November 26, 2023 { id="9.4.14" }
+
+- Added support for linking authors in blog posts
+
+### 9.4.13 November 26, 2023 { id="9.4.13" }
+
+- Fixed #6365: Blog plugin pagination links to previous pages broken
+- Fixed #5758: Updated Mermaid.js to version 10.6.1 (latest)
+
+### 9.4.12 November 24, 2023 { id="9.4.12" }
+
+- Improved blog plugin to generate Unicode-aware slugs by default
+- Fixed non-deterministic order of categories in blog plugin
+
+### 9.4.11 November 23, 2023 { id="9.4.11" }
+
+- Fixed #6364: Search plugin crashing when enabling theme while serving
+- Fixed blog plugin crashing when disabling pagination
+
+### 9.4.10 November 19, 2023 { id="9.4.10" }
+
+- Fixed #6356: Version selector can't be disabled via mike's configuration
+- Fixed #6281: Navigation not rendering due to Safari bug (9.4.2 regression)
+- Fixed #6261: Navigation expansion animates on first load (9.4.2 regression)
+
+### 9.4.9 November 17, 2023 { id="9.4.9" }
+
+- Fixed #6344: Long entries cutoff in table of contents
+- Fixed #6336: Custom template for glob archive not working with pagination
+- Fixed #6328: Blog plugin crashes for locales with dashes, e.g. `pt-BR`
+- Fixed #6327: Copy-to-clipboard button doesn't trim trailing line feed
+- Fixed #6302: Version strings not matched when using mike, only aliases
+- Fixed instant navigation progress indicator for gzipped content in Chrome
+- Fixed rendering bug on details marker rotation in Firefox
+
+### 9.4.8 November 5, 2023 { id="9.4.8" }
+
+- Fixed invalid local address replacement when using instant loading
+- Fixed #6275: Crash after navigation caused 404 when using instant loading
+
+### 9.4.7 October 27, 2023 { id="9.4.7" }
+
+- Added Azerbaijani translations
+
### 9.4.6 October 14, 2023 { id="9.4.6" }
- Updated Danish and Norwegian (Nynorsk) translations
@@ -469,7 +768,7 @@ __Fixes__
### 8.5.11 November 30, 2022 { id="8.5.11" }
-- Let it snow, see https://twitter.com/squidfunk/status/1597939243090788352
+- Let it snow, see https://x.com/squidfunk/status/1597939243090788352
### 8.5.10 November 11, 2022 { id="8.5.10" }
@@ -839,7 +1138,7 @@ __Fixes__
- Removed deprecated prebuilt search index support
- Removed deprecated web app manifest – use customization
- Removed `extracopyright` variable – use new `copyright` partial
-- Removed Disqus integation – use customization
+- Removed Disqus integration – use customization
- Switched to `:is()` selectors for simple selector lists
- Switched autoprefixer from `last 4 years` to `last 2 years`
- Improved CSS overall to match modern standards
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 539d540cae7..fe84fd55b20 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -113,8 +113,8 @@ In this section, we guide your through our processes.
[report a bug]: reporting-a-bug.md
[report a docs issue]: reporting-a-docs-issue.md
[request a change]: requesting-a-change.md
- [add translations]: https://github.com/squidfunk/mkdocs-material/adding-translations
- [create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
+ [add translations]: adding-translations.md
+ [create a pull request]: making-a-pull-request.md
## Checklist
@@ -168,35 +168,102 @@ with our community.
## Rights and responsibilities
-As maintainers, we reserve the right and have the responsibility to close,
-remove, reject, or edit contributions, such as issues, discussions, comments,
-or commits, that do not align with our contribution guidelines and our
-[Code of Conduct].
+As maintainers, we are entrusted with the __responsibility__ to moderate
+communication within our community, including the authority to close, remove,
+reject, or edit issues, discussions, comments, commits, and to block users who
+__do not align__ with our contribution guidelines and our [Code of Conduct].
+This role requires us to be actively involved in maintaining the integrity and
+positive atmosphere of our community. Upholding these standards decisively
+ensures a respectful and inclusive environment for all members.
-### Incomplete issues
-
-We have invested significant time in reviewing our contribution process and
-carefully assessed the essential requirements when reviewing and responding to
-issues. Each field in our issue templates has been thoughtfully curated, helping
-us to understand your matter.
-
-__Therefore, it is mandatory to fill out every field as requested__ to the best
-of your knowledge. We need all of this information because it ensures that every
-user and maintainer, regardless of their experience, can understand the content
-and severity of your bug report or change request.
-
-__We reserve the right to close issues missing essential information__, such as
-but not limited to [minimal reproductions], or that do not comply with the
-quality standards and requirements stated in our issue templates. Issues
-can be reopened once the missing information has been provided.
-
- [minimal reproductions]: ../guides/creating-a-reproduction.md
### Code of Conduct
-As stated in our [Code of Conduct], we expect all members of our community to
-treat each other with respect, and use inclusive and welcoming language. We
-always strive to create a positive and supportive environment and do not accept
+Our [Code of Conduct] outlines the expectation for all community members to
+treat one another with respect, employing inclusive and welcoming language. Our
+commitment is to foster a positive and supportive environment, free of
inappropriate, offensive, or harmful behavior.
-We take violations seriously and will take appropriate action in response.
+We take any violations seriously and will take appropriate action in response to
+uphold these values.[^1]
+
+ [^1]:
+ __Warning and blocking policy:__
+ Given the increasing popularity of our project and our commitment to a
+ healthy community, we've defined clear guidelines on how we proceed with
+ violations:
+
+ 1.1. __First warning:__ Users displaying repeated inappropriate, offensive,
+ or harmful behavior will receive a first warning. This warning serves as a
+ formal notice that their behavior is not in alignment with our community
+ standards and Code of Conduct. The first warning is permanent.
+
+ 1.2. __Second warning and opportunity for resolution:__ If the behavior
+ persists, a second warning will be issued. Upon receiving the second
+ warning, the user will be given a 5-day period for reflection, during which
+ they are encouraged to publicly explain or apologize for their actions.
+ This period is designed to offer an opportunity for openly clearing out any
+ misunderstanding.
+
+ 1.3. __Blocking:__ Should there be no response or improvement in behavior
+ following the second warning, we reserve the right to block the user from
+ the community and repository. Blocking is considered a last resort, used
+ only when absolutely necessary to protect the community's integrity and
+ positive atmosphere.
+
+ Blocking has been an exceptionally rare necessity in our overwhelmingly
+ positive community, highlighting our preference for constructive dialogue
+ and mutual respect. It aims to protect our community members and team.
+
+### Incomplete issues and duplicates
+
+We have invested significant time and effort in the setup of our contribution
+process, ensuring that we assess the essential requirements for reviewing and
+responding to issues effectively. Each field in our issue templates is
+thoughtfully designed to help us fully understand your concerns and the nature
+of your matter. We encourage all members to utilize the search function before
+submitting new issues or starting discussions to help avoid duplicates. Your
+cooperation is crucial in keeping our community's discussions constructive and
+organized.
+
+ - __Mandatory completion of issue templates:__ We need all of the information
+ required in our issue templates because it ensures that every user and
+ maintainer, regardless of their experience, can understand the content and
+ severity of your bug report or change request.
+
+ - __Closing incomplete issues:__
+ We _reserve the right to close issues lacking essential information_, such as
+ but not limited to [minimal reproductions] or those not adhering to the
+ quality standards and requirements specified in our issue templates. Such
+ issues can be reopened once the missing information has been provided.
+
+ - __Handling duplicates:__ To maintain organized and efficient
+ communication within our [issue tracker] and [discussion board], we
+ _reserve the right to close any duplicated issues or lock duplicated
+ discussions_. Opening multiple channels to ask the same question or report the
+ same issue across different forums hinders our ability to manage and address
+ community concerns effectively. This approach is vital for efficient time
+ management, as duplicated questions can consume the time of multiple team
+ members simultaneously. Ensuring that each issue or discussion is unique and
+ progresses with new information helps us to maintain focus and support our
+ community.
+
+ We further _reserve the right to immediately close discussions or issues that
+ are reopened without providing new information_ or simply because users have
+ not yet received a response to their issue/question, as the issue is marked as
+ incomplete.
+
+ - __Limitations of automated tools:__ While we believe in the value and
+ efficiency that automated tools bring to identifying potential issues (such
+ as those identified by Lighthouse, Accessibility tools, and others), simply
+ submitting an issue generated by these tools does not constitute a complete
+ bug report. These tools sometimes produce verbose outputs and may include
+ false positives, which necessitate a critical evaluation. You are of course
+ welcome to attach generated reports to your issue. However, this does not
+ substitute the requirement for a minimal reproduction or a thorough discussion
+ of the findings. _We reserve the right to mark these issues as incomplete and
+ close them._ This practice ensures that we are addressing genuine concerns
+ with precision and clarity, rather than navigating through extensive automated
+ outputs.
+
+ [minimal reproductions]: ../guides/creating-a-reproduction.md
diff --git a/docs/contributing/making-a-pull-request.md b/docs/contributing/making-a-pull-request.md
new file mode 100644
index 00000000000..d1be831ddb6
--- /dev/null
+++ b/docs/contributing/making-a-pull-request.md
@@ -0,0 +1,423 @@
+# Pull Requests
+
+You can contribute to Material for MkDocs by making a [pull request] that
+will be reviewed by maintainers and integrated into the main repository when
+the changes made are approved. You can contribute bug fixes, changes to the
+documentation, or new functionality you have developed.
+
+[pull request]: https://docs.github.com/en/pull-requests
+
+!!! note "Considering a pull request"
+
+ Before deciding to spend effort on making changes and creating a pull
+ request, please discuss what you intend to do. If you are responding to
+ what you think might be a bug, please issue a [bug report] first. If you
+ intend to work on documentation, create a [documentation issue]. If you
+ want to work on a new feature, please create a [change request].
+
+ Keep in mind the guidance given and let people advise you. It might be that
+ there are easier solutions to the problem you perceive and want to address.
+ It might be that what you want to achieve can already be done by
+ configuration or [customization].
+
+[bug report]: reporting-a-bug.md
+[documentation issue]: reporting-a-docs-issue.md
+[change request]: requesting-a-change.md
+[customization]: ../customization.md
+
+## Learning about pull requests
+
+Pull requests are a concept layered on top of Git by services that provide Git
+hosting. Before you consider making a pull request, you should familiarize
+yourself with the documentation on GitHub, the service we are using. The
+following articles are of particular importance:
+
+1. [Forking a repository]
+2. [Creating a pull request from a fork]
+3. [Creating a pull request]
+
+Note that they provide tailored documentation for different operating systems
+and different ways of interacting with GitHub. We do our best in the
+documentation here to describe the process as it applies to Material for MkDocs
+but cannot cover all possible combinations of tools and ways of doing things.
+It is also important that you understand the concept of a pull-request in
+general before continuing.
+
+[Forking a repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+[Creating a pull request from a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork
+[Creating a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+## Pull request process
+
+In the following, we describe the general process for making pull requests. The
+aim here is to provide the 30k ft overview before describing details later on.
+
+### Preparing changes and draft PR
+
+The diagram below describes what typically happens to repositories in the
+process or preparing a pull request. We will be discussing the review-revise
+process below. It is important that you understand the overall process first
+before you worry about specific commands. This is why we cover this first before
+providing instructions below.
+
+``` mermaid
+sequenceDiagram
+ autonumber
+
+ participant mkdocs-material
+ participant PR
+ participant fork
+ participant local
+
+ mkdocs-material ->> fork: fork on GitHub
+ fork ->> local: clone to local
+ local ->> local: branch
+ loop prepare
+ loop push
+ loop edit
+ local ->> local: commit
+ end
+ local ->> fork: push
+ end
+ mkdocs-material ->> fork: merge in any changes
+ fork ->>+ PR: create draft PR
+ PR ->> PR: review your changes
+ end
+```
+
+1. The first step is that you create a fork of the Material for MkDocs
+ repository, either [mkdocs-material] or [mkdocs-material-insiders]
+ (only accessible to sponsors). This provides you with a repository that you
+ can push changes to. Note that it is not possible to have more than one fork
+ of a given repository at any point in time. So, the fork you create will be
+ *the* fork you have.
+
+2. Once it is made, clone it to your local machine so you can start working on
+ your changes.
+
+3. All contributions should be made through a 'topic branch' with a name that
+ describes the work being done. This allows you to have more than one piece
+ of work in progress and, if you are working with the public version, also
+ shows others clearly that the code contained is work in progress. The topic
+ branch will be relatively short-lived and will disappear at the end, when
+ your changes have been incorporated into the codebase.
+
+4. If you intend to make any code changes, as opposed to working on
+ documentation only, you will need to [set up a development
+ environment](#setting-up-a-development-environment).
+
+5. Next comes the iterative process of making edits, committing them to your
+ clone. Please commit in sensible chunks that constitute a piece of work
+ instead of committing everything in one go.
+
+ Remember that fine-grained, incremental commits are much easier to
+ review in than large changes all over the place and with many files involved.
+ Try to keep your changes as small and localized as possible and keep the
+ reviewer in mind when committing. In particular, make sure to write
+ meaningful commit messages.
+
+6. Push your work up to your fork regularly.
+
+7. You should also keep an eye on changes in the Material for MkDocs repository
+ you cloned. This is especially important if you work takes a while. Please
+ try and merge any concurrent changes into your fork and into your branch
+ regularly. You *must* do this at least once before creating a pull request,
+ so make your life easier and do it more often so as to minimize the risk of
+ conflicting changes.
+
+8. Once you are happy that your changes are in a state that you can describe
+ them in a *draft* pull request, you should create this. Make sure to
+ reference any previous discussions or issues that gave rise to your work.
+ Creating a draft is a good way to get *early* feedback on your work from the
+ maintainer or others. You can explicitly request reviews at points where you
+ think this would be important.
+
+9. Review your work as if you were the reviewer and fix any issues with your
+ work so far. Look critically at the diffs of the files that you have changed.
+ In particular, pay attention to whether the changes are as small as possible
+ and whether you have follow the general coding style used in the project.
+ If you received feedback, iterate over the process so far as necessary.
+
+ You should choose a number of projects to test your changes with. You should
+ definitely make sure that the changes do not break the building of the
+ documentation for Material for MkDocs, which you can find in the `docs`
+ folder. You may also want to make sure that relevant examples from the
+ [examples repository] still build fine.
+
+[mkdocs-material]: https://github.com/squidfunk/mkdocs-material
+[mkdocs-material-insiders]: https://github.com/squidfunk/mkdocs-material-insiders/
+[examples repository]: https://github.com/mkdocs-material/examples
+
+### Finalizing
+
+Once you are happy with your changes, you can move to the next step, finalizing
+your pull request and asking for a more formal and detailed review. The diagram
+below shows the process:
+
+``` mermaid
+sequenceDiagram
+ autonumber
+ participant mkdocs-material
+ participant PR
+ participant fork
+ participant local
+
+ activate PR
+ PR ->> PR : finalize PR
+ loop review
+ loop discuss
+ PR ->> PR: request review
+ PR ->> PR: discussion
+ local ->> fork: push further changes
+ end
+ PR ->> mkdocs-material: merge (and squash)
+ deactivate PR
+ fork ->> fork: delete branch
+ mkdocs-material ->> fork: pull
+ local ->> local: delete branch
+ fork ->> local: pull
+ end
+```
+
+1. When you are happy that the changes you made amount to a contribution that
+ the maintainer(s) could integrate into the codebase, finalize the pull
+ request. This signals to everyone that consider the work 'done' and that it
+ can be reviewed with a view to accepting and integrating it.
+
+2. Request a review from the maintainer, `@squidfunk`.
+
+3. The maintainer may make comments on your code, which you should discuss with
+ them. Bear in mind when doing this that the maintainer may have a different
+ point of view compared to yours. They will often take a more long-term
+ perspective of maintaining the project in the years to come while you may be
+ more focused on the specific issue or feature that you worked on. Please keep
+ the discussion respectful at all times.
+
+ It is important to note that not all pull requests get incorporated int the
+ codebase. The reasons can vary. The work may bring to light other issues that
+ block integration of the pull request. Sometimes it helps uncover better ways of
+ doing things or shows that a more general approach is needed. All of this is
+ fine and helps the project progress, even if specific changes are not,
+ ultimately, accepted.
+
+4. Make any requested changes by committing them to your local clone and
+ pushing them up to your fork. This will automatically update the pull request.
+ It may well take a few iterations to get your contributions to an acceptable
+ state. You can help the process along by carefully reading comments made and
+ making changes with care.
+
+5. Once the reviewer is fully satisfied with the changes, they can merge them
+ into the main branch (or 'master'). In the process, they may 'squash' your
+ commits together into a smaller number of commits and may edit the messages
+ that describe them. Congratulations, you have now contributed to this project
+ and should see the changes in the main branch under your name.
+
+6. You can now delete the fork and your local repository and start afresh again
+ next time around. Alternatively, you can keep the repository and local clone
+ around but it is important that you keep them in sync with the upstream
+ repository for any subsequent work. We recommend that you start by deleting
+ the branch you used on your fork.
+
+7. To make sure you have the changes you produced, pull them from the main
+ repository into the main branch of your fork.
+
+8. Similarly, delete the topic branch from your local clone and...
+
+9. pull the changes to its master branch.
+
+## Steps
+
+Now that the overall process is outlined, here are specific instructions and
+tips. There are many choices to be made when describing a process for
+contributing to a project via a pull request. In the following, we assume that
+you are working with the Git command-line tools. For most alternatives (such as
+using IDEs or using functionality provided through the GitHub web interface),
+the translation from the command-line instructions should be simple enough. We
+will add notes only where really necessary to keep the complexity of this to a
+reasonable level.
+
+### Forking the repository
+
+To make changes to Material for MkDocs, you would first fork one of its
+repositories on GitHub. This is so that you have a repository on GitHub that
+you can push changes to (only maintainers and collaborators have write access
+to the original repositories).
+
+Fork the [repository for the public version] if you want to make changes to
+code that is in the public version or if you want to make changes to the
+documentation. It is a good idea to change the name of the repository by
+appending `-fork` so that people who come across it know that they have found a
+temporary fork rather then the original or a permanent fork of the project.
+You may also want to add a description that clarifies what the repository is for.
+
+[repository for the public version]: https://github.com/squidfunk/mkdocs-material
+
+To make changes to functionality available only within the Insiders version,
+fork [the Insiders repository]. Note that the fork will be a private repository.
+Please respect the [terms of the Insiders program] and the spirit of the
+Sponsorware approach used to maintain and develop Material for MkDocs.
+
+[the Insiders repository]: https://github.com/squidfunk/mkdocs-material-insiders/
+[terms of the Insiders program]: http://localhost:8000/mkdocs-material/insiders/faq/sponsoring/#licensing
+
+### Setting up a development environment
+
+From this point onwards, please follow the [instructions for setting up the
+development environment]. They will take you through the process of setting up
+an environment in which you can make changes and review/test them.
+
+[instructions for setting up the development environment]: ../customization.md#environment-setup
+
+### Making changes
+
+When you make changes to the code or the documentation please follow the
+established style used in the project. Doing so increases readability and
+also helps with making diffs easier to read for those who will review the pull
+request. Avoid making any large-scale style changes such as asking your IDE
+to re-format all code.
+
+Study the code that you are modifying well to ensure that you fully understand
+how it works before you try to change it. This will not only help you solve the
+problem you are trying to address but also minimize the risks of creating
+unintended side effects.
+
+### Committing to a branch
+
+Development for pull requests is best done in a topic branch separate from the
+`master` branch. Create a new local branch with `git switch -c ` and
+commit your changes to this branch.
+
+When you want to push commits to your fork, you can do so with
+`git push -u origin `. The `-u` argument is the short version of
+`--set-upstream`, which makes the newly created branch 'track' the branch with
+the same `` in your fork. This means that then `pull` and `push` commands
+will work against that branch in your fork by default.
+
+### Merging concurrent changes
+
+If the work you do takes some time then the chances increase that changes will
+be made to the main repository while you work.It is probably a good idea to set
+up the original Material for MkDocs repository as an `upstream` repository for
+your local clone.
+
+This is what it might look like:
+
+```bash hl_lines="4"
+$ git remote -v
+origin git@github.com:/mkdocs-material-fork.git (fetch)
+origin git@github.com:/mkdocs-material-fork.git (push)
+$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
+$ git remote -v
+origin git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
+origin git@github.com:alexvoss/mkdocs-material-fork.git (push)
+upstream https://github.com/squidfunk/mkdocs-material.git (fetch)
+upstream https://github.com/squidfunk/mkdocs-material.git (push)
+```
+
+After you have done this, you can pull any concurrent changes from the upstream
+repository directly into your clone and do any necessary merges there, then push
+them up to your fork. You will need to be explicit about which remote repository
+you want to use when you are doing a `pull`:
+
+```bash
+# making and committing some local changes
+push pull upstream master
+```
+
+This fetches changes from the `master` branch into your topic branch and merges
+them.
+
+### Testing and reviewing changes
+
+Before you commit any changes, you should make sure that they work as expected
+and do not create any unintended side effects. You should test them on at least
+these three [smoke tests]:
+
+- The documentation of Material for MkDocs itself. If you set up and run the
+development environment as outlined in the [instructions for setting up the
+development environment], `mkdocs serve` should be running and continuously
+building the documentation. Check that there are no error messages and, ideally,
+no (new) warnings.
+
+- Test on a project that represents the problem or a test for a newly developed
+feature. You may already have this if you have filed a bug report and created
+a [minimal reproduction]. If you are working on a new feature then you may need
+to build a project to serve as a test suite. It can double as documentation that
+shows how your new feature is meant to work.
+
+- Test with relevant examples from the [Material for MkDocs Examples]
+ repository. Note that to build all examples in one go you need the projects
+ plugin from Insiders but you can always build the examples individually
+ using the public version.
+
+[smoke tests]: https://en.wikipedia.org/wiki/Smoke_testing_(software)
+[minimal reproduction]: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/
+[Material for MkDocs Examples]: https://github.com/mkdocs-material/examples
+
+- Ideally, also test the examples in the [examples repository]. If you are
+working on the Insiders edition of Material for MkDocs, you can simply start a
+build at the top level and the [projects plugin] will build all of the examples
+for you. If you are on the public version, you will need to build each
+sub-project individually. We appreciate that this is a growing collection of
+examples and you may want to prioritize those that are most relevant to the
+functionality you change.
+
+[examples repository]: https://github.com/mkdocs-material/examples
+[projects plugin]: https://squidfunk.github.io/mkdocs-material/plugins/projects/
+
+### Creating the pull request
+
+Initially, create the pull request **as a draft**. You do this [through the
+various interfaces that GitHub provides]. Which one you use is entirely up to
+you. We do not provide specific instructions for using the interfaces as GitHub
+provide all the information that should be necessary.
+
+[through the various interfaces that GitHub provides]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+### Commits, messages, mistakes and 'squash'
+
+### Deleting branches
+
+Once the pull request has been merged into the master branch of the Material
+for MkDocs repository, you should remove the branch both from the fork on
+GitHub and from the local clone on your computer. This avoids possible
+confusion about the state of development.
+
+First, switch back to the `master` branch with `git switch master` and then
+delete the branch used for the PR using `git branch -d `.
+
+### Subsequent Pull Requests
+
+It is important that subsequent pull requests are started from an up-to-date
+history of the `master` branch. One way to achieve this is to delete the fork
+and start with an entirely new one next time round.
+
+If you contribute to Material for MkDocs more often or just happen to be
+doing two or more pull requests in succession, you can also just make sure
+to sync your fork (using the GitHub UI) and pull from it into your local
+repository. So, just delete the topic branch you created (both locally and in
+your fork) and pull from the main repository's `master` branch into your
+`master` branch before starting work on a new pull request.
+
+## Dos and Don'ts
+
+1. **Don't** just create a pull request with changes that are not explained.
+
+2. **Do** discuss what you intend to do with people in the discussions so that the
+ rational for any changes is clear before you write or modify code.
+
+3. **Do** link to the discussion or any issues to provide the context for a pull
+ request.
+
+4. **Do** ask questions if you are uncertain about anything.
+
+5. **Do** ask yourself if what you are doing benefits the wider community and
+ makes Material for MkDocs a better product.
+
+6. **Do** ask yourself if the cost of making the changes stands in a good
+ relation to the benefits they will bring. Some otherwise sensible changes can
+ add complexity for comparatively little gain, might break existing behaviour
+ or might be brittle when other changes need to be made.
+
+7. **Do** merge in concurrent changes frequently to minimize the chance of
+ conflicting changes that may be difficult to resolve.
diff --git a/docs/contributing/reporting-a-bug.md b/docs/contributing/reporting-a-bug.md
index 5d40218b475..8c84f8a10db 100644
--- a/docs/contributing/reporting-a-bug.md
+++ b/docs/contributing/reporting-a-bug.md
@@ -66,7 +66,7 @@ problems.__
[hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
[extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
[extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
- [discussion board]: https://github.com/squidfunk/mkdocs-material/issues
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
[StackOverflow]: https://stackoverflow.com
[that our documentation explicitly mentions]: ?q="extends+base"
diff --git a/docs/conventions.md b/docs/conventions.md
index 07bb5e9dfeb..0363412ab0a 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -33,7 +33,7 @@ explicitly define them. The default value of the property is always included.
#### – Default value is computed { #default data-toc-label="is computed" }
-Some default values are not set to static values but computed form other values,
+Some default values are not set to static values but computed from other values,
like the site language, repository provider, or other settings.
#### – Default value is empty { #default data-toc-label="is empty" }
@@ -69,7 +69,7 @@ Several features are implemented through MkDocs excellent plugin architecture,
some of which are built-in and distributed with Material for MkDocs, so no
installation is required.
-### – Markdown extension { data-toc-label="Markdown extension" }
+### – Markdown extension { data-toc-label="Markdown extension" #extension }
This symbol denotes that the thing described is a Markdown extension, which can
be enabled in `mkdocs.yml` and adds additional functionality to the Markdown
diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index 0b1ada2a6fb..cd0378e778c 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -16,7 +16,7 @@ Alternatively, if you're running Material for MkDocs from within Docker, use:
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
```
-=== "Windows"
+=== "Windows (cmd)"
```
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
@@ -37,13 +37,22 @@ This will create the following structure:
### Minimal configuration
-Simply add the following lines to `mkdocs.yml` to enable the theme:
+Simply set the `site_name` and add the following lines to `mkdocs.yml` to enable the theme:
-``` yaml
+``` yaml hl_lines="2-5"
+site_name: My site
+site_url: https://mydomain.org/mysite
theme:
name: material
```
+The `site_url` setting is important for a number of reasons.
+By default, MkDocs will assume that your site is hosted at the root of
+your domain. This is not the case, for example, when [publishing to GitHub
+pages] - unless you use a custom domain. Another reason is that some of the
+plugins require the `site_url` to be set, so you should always do this.
+
+ [publishing to GitHub pages]: publishing-your-site.md#github-pages
[installation methods]: getting-started.md#installation
???+ tip "Recommended: [configuration validation and auto-complete]"
@@ -66,9 +75,11 @@ theme:
"yaml.customTags": [ // (1)!
"!ENV scalar",
"!ENV sequence",
+ "!relative scalar",
"tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
"tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
- "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+ "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
+ "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
]
}
```
@@ -92,7 +103,7 @@ theme:
If you already have a schema defined, or wish to self-host your schema to
reduce duplication, you can add it via [$ref].
- [configuration validation and auto-complete]: https://twitter.com/squidfunk/status/1487746003692400642
+ [configuration validation and auto-complete]: https://x.com/squidfunk/status/1487746003692400642
[schema.json]: schema.json
[vscode-yaml]: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
[settings.json]: https://code.visualstudio.com/docs/getstarted/settings
@@ -154,6 +165,30 @@ technical writing experience.
[Building an optimized site]: setup/building-an-optimized-site.md
[Markdown extensions]: setup/extensions/index.md
+## Templates
+
+If you want to jump start a new project, you can use one of our growing
+collection of templates:
+
+
+
+- :octicons-repo-template-24: __[Blog][blog-template]__
+
+ ---
+
+ Create a blog
+
+- :octicons-repo-template-24: __[Social cards][social-cards-template]__
+
+ ---
+
+ Create documentation with social cards
+
+
+
+[blog-template]: https://github.com/mkdocs-material/create-blog
+[social-cards-template]: https://github.com/mkdocs-material/create-social-cards
+
## Previewing as you write
MkDocs includes a live preview server, so you can preview your changes as you
diff --git a/docs/customization.md b/docs/customization.md
index 93097efa992..e7f7ac81b1c 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -84,7 +84,7 @@ extend the theme. MkDocs supports [theme extension], an easy way to override
parts of Material for MkDocs without forking from git. This ensures that you
can update to the latest version more easily.
- [theme extension]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
+ [theme extension]: https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir
### Setup and theme structure
diff --git a/docs/enterprise-support.md b/docs/enterprise-support.md
index af1f409848e..bd027ffe97a 100644
--- a/docs/enterprise-support.md
+++ b/docs/enterprise-support.md
@@ -1,5 +1,32 @@
---
-template: redirect.html
-location: https://calendly.com/squidfunk/enterprise
status: new
---
+
+# Enterprise Feedback
+
+We highly value the insights of our enterprise users, and we're eager to hear
+from you. Your feedback is immensely valuable to us. If you're utilizing
+Material for MkDocs in an enterprise context and would like to share your
+experiences with us, we'd love to connect and discuss:
+
+- What you are building with it
+- What aspects you like about it
+- What challenges you are facing
+- What could be improved
+
+## Let's Connect
+
+To schedule a convenient appointment, please reach out to us via email at
+contact@squidfunk.com and provide us with the following details:
+
+- Your company's name
+- How you are using Material for MkDocs
+- Any specific questions or topics you'd like to address
+
+Once we have this information, we'll promptly get in touch with you to arrange
+a 30-minute call. Please note that this call is exclusively intended for
+enterprise users and is not meant for technical support. Instead, it's an
+opportunity for us to engage in a casual conversation to better understand your
+unique needs.
+
+We look forward to our discussion!
diff --git a/docs/faq/sponsoring.md b/docs/faq/sponsoring.md
deleted file mode 100644
index 9f90139dd2b..00000000000
--- a/docs/faq/sponsoring.md
+++ /dev/null
@@ -1,481 +0,0 @@
-# Sponsoring FAQs
-
-Do you have questions about Material for MkDocs Insiders? We do our best to
-answer all of your questions on this page. If you can't find your question
-below, ask it on our [discussion board]!
-
- [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions/new/chooses
-
-## General
-
-[__Why is the Insiders edition offered as a subscription model?__](#insiders-subscription){ #insiders-subscription }
-
-Material for MkDocs always was and will be Open Source, available for free to
-individuals and organizations. As the project grew over time, we found that
-maintaining and managing the overhead that comes with growth became more
-challenging and time-consuming.
-
-In order to sustain the project and add new and useful features more frequently,
-we decided to create the [Insiders] edition, with early access to the latest and
-greatest features of Material for MkDocs. The subscription-based model of the
-Insiders edition allows us to dedicate more time and resources to the project,
-which benefits all
-users of Material for MkDocs. Once our funding goals based on monthly
-subscriptions are hit, the Insiders features of those^ funding goals are released
-to the community edition, letting everyone benefit from them.
-
-Maintaining both the community and Insiders editions is an ongoing process, and
-we rely on our sponsors to support us on a monthly basis, which makes this whole
-project possible.
-
-[__What features are included in the Insiders edition?__](#insiders-features){ #insiders-features }
-
-The Insiders edition includes more than 20 additional features. You can find an
-overview of these features on our [Insiders page], which is updated when new
-features are added and released.
-
- [Insiders]: ../insiders/index.md
- [Insiders page]: ../insiders/index.md#whats-in-it-for-me
-
-[__How often is the Insiders edition updated?__](#insiders-updates){ #insiders-updates }
-
-We try to keep our open issue count low, fixing known bugs quickly. Both our
-repositories, the community and Insiders edition, are constantly updated with
-bug fixes and new features.
-
-## Sponsorship
-
-[__Can I sponsor the project without a GitHub account?__](#sponsorship-account){ #sponsorship-account }
-
-Yes. You can support Material for MkDocs by sponsoring us on [Ko-fi], regardless
-of whether you have a GitHub account or not. However, please note that Insiders
-is provided as a private repository on GitHub. If after sponsoring, you'd like to
-gain access to the repository, you'll need to have a GitHub individual or bot
-account that can be added as a collaborator. If your organization doesn't use
-GitHub or/and host its repositories on other platforms, you can mirror the
-Insiders repository in your environment once you have access.
-
-[__Which sponsoring tier should I choose?__](#sponsorship-tier){ #sponsorship-tier }
-
-The sponsoring tiers are divided into non-commercial and commercial tiers. If
-you are an individual or organization using Material for MkDocs for private or
-__non-commercial__ Open Source projects, you have two tiers to choose from,
-depending on the number of sites you want to build. For companies using
-Material for MkDocs, we offer three different __commercial__ tiers, from which
-you can choose depending on your requirements.
-
-Also, please read what is considered [commercial use].
-
- [commercial use]: #commercial-use
-
-[__Why are one-time sponsorships not granted access to Insiders?__](#sponsorship-one-time){ #sponsorship-one-time }
-
-Primarily due to technical reasons, that we're working on lifting in the future.
-We use GitHub webhooks to determine our current active sponsors. When you create
-or cancel your monthly subscription, GitHub sends events that we use to
-automatically add and remove collaborators.
-
-Note that [$15] is the minimum amount to be granted access to Insiders.
-
- [$15]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
-
-[__How are sponsorship contributions used?__](#sponsorship-support){ #sponsorship-support }
-
-It's vital to recognize that the total sponsorship amount doesn't directly
-translate into the funds we have available for use. The way we allocate
-sponsorship amounts is detailed as follows:
-
-1. __Taxes__: Since we provide a service to our sponsors, we're of course
- legally obligated to pay sales tax. This requirement applies to all
- sponsorship contributions, aligning us with standard business practices
- as for the rest of the world.
-
-2. __Sponsorships__: A significant portion of our funding is redirected to
- upstream projects. This cultivates collaboration and supports the broader
- Open Source ecosystem. Those projects and their maintainers are essential
- for the ongoing development of Material for MkDocs.
-
- [Explore our sponsorships](https://github.com/squidfunk?tab=sponsoring).
-
-3. __Funds__: We are in the process of forming a team devoted to Material for
- MkDocs and are proactively compensating critical contributors. These
- funds cover various aspects of the project, like the creation of new
- features, bug resolution, support, and sponsor relations.
-
-[__Are there any limitations on the number of sponsors for a particular tier?__](#sponsorship-limitations){ #sponsorship-limitations }
-
-No, there are no limitations on the number of sponsors for any tier. You can
-sponsor the project at any tier regardless of how many other sponsors are
-already there.
-
-## Payment & billing
-
-[__Is there a trial period for the Insiders edition?__](#insiders-trial){ #insiders-trial }
-
-No, we do not offer a trial period for the Insiders edition. However, if you're
-a company and are considering sponsoring on the commercial tier, but want to
-first give the Insiders edition a try, you can sponsor on the [$15] tier with a
-personal account for non-commercial evaluation purposes.
-
-Additionally, our subscription model allows you to cancel your sponsorship
-anytime. If you decide to cancel, your sponsorship will remain active until
-the end of your billing cycle.
-
-[__What payment options do you accept?__](#insiders-payment){ #insiders-payment }
-
-We manage all our transactions and sponsorships through [GitHub Sponsors] and
-[Ko-fi]. To become a sponsor of Material for MkDocs on GitHub, visit
-[our sponsors' page]. On there, you can choose from five different sponsorship
-tiers and pay by credit card. Please note that as of the beginning of 2023,
-[GitHub no longer supports PayPal] payments. If you wish to pay with PayPal,
-you can find a selection of our sponsorship tiers on [Ko-fi]. Both platforms
-provide you with a payment receipt once your purchase is successful.
-
-If you're a company and need assistance choosing the right payment method,
-please don't hesitate to reach out to sponsors@squidfunk.com.
-
- [Ko-fi]: https://ko-fi.com/squidfunk
- [GitHub Sponsors]: https://github.com/sponsors
- [GitHub no longer supports PayPal]: https://github.blog/changelog/2023-01-23-github-sponsors-will-stop-supporting-paypal/
- [our sponsors' page]: https://github.com/sponsors/squidfunk/
-
-[__Are discounts available for the Insiders edition, such as student discounts?__](#insiders-discounts){ #insiders-discounts }
-
-Unfortunately, we are not able to offer any discounts for the Material for
-MkDocs Insiders program. To ensure that everyone can afford the Insiders program
-and keep the barrier as low as possible, we have set prices as low as [$15] a
-month for non-commercial use.
-
-[__Do you offer free access to Insiders for Open Source projects?__](#insiders-open-source){ #insiders-open-source }
-
-No, we do not offer free access to our Material for MkDocs Insiders edition.
-We understand that non-profit organizations may have limited budgets and may
-need to prioritize their spending on other projects or organizations. However,
-it's important to note that Material for MkDocs is maintained by a small team,
-investing a lot of time and resources into constantly improving this project.
-Material for MkDocs and its core features are free to the community through our
-Open Source model. Therefore, Material for MkDocs itself is already free.
-
-However, we do offer an affordable sponsorship tier starting at [$15] a month,
-which is meant for individuals and non-profit organizations using Material for
-MkDocs to build 1-2 sites for non-commercial purposes. This tier provides access
-to all new features, benefiting you from our ongoing development efforts.
-
-[__Is Insiders free for those who contribute to this project?__](#insiders-contributors){ #insiders-contributors }
-
-Great question! We can not offer free access to "drive-by" contributors that
-only fix minor issues like typos or add new languages. These contributions are
-always welcome, but as we need to review them, they result in a higher time
-investment from our side and don't compensate for this work. However, as this
-project keeps growing, we always seek for individuals to support us. In return,
-we offer financial compensation or/and Insiders access. If you are interested
-and have experience in the technologies and paradigms listed below, please get
-in touch with us at sponsors@squidfunk.com:
-
-- Deep knowledge of CSS, HTML, TypeScript
-- Experience with progressive enhancement and responsive design
-- Experience with reactive programming with RxJS
-- Solid understanding of Python, MkDocs + ecosystem
-- Solid technical writing skills
-
-Additionally, we're working on a contributor program that will reward
-contributors that engage in the community by answering questions and helping
-users with access to Insiders.
-
-[__How can I set my billing to monthly or yearly?__](#insiders-billing-cycle){ #insiders-billing-cycle }
-
-You can sponsor Material for MkDocs on a monthly or yearly basis. Depending on
-your billing cycle you automatically become a monthly or yearly sponsor. Your
-[billing cycle] is an account-level setting that you can easily change in your
-account. If, for some reason, you cannot make this change, you can create a
-dedicated bot account with a yearly billing cycle on GitHub, which you only use
-for sponsoring (some sponsors already do that). If you have any problems or
-further questions, please contact us at sponsors@squidfunk.com.
-
- [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
-
-[__Can I get an invoice for my sponsorship payment?__](#insiders-invoice){ #insiders-invoice}
-
-Right now, we can't provide you with an invoice for your sponsoring transaction,
-as [GitHub Sponsors] handles all transactions for us. However, both payment
-platforms, [GitHub] and [Ko-Fi], automatically send you a payment receipt
-via mail once the sponsorship is active.
-
-Furthermore, we are working on a solution to optimize access management and more
-features. If you are interested in this, please get in touch with us via mail at
-sponsors@squidfunk.com or turn on all notifications for MkDocs, and we will
-reach out as soon as we are live.
-
- [GitHub]: https://github.com/sponsors/squidfunk/
-
-[__Can I switch between different sponsoring tiers?__](#insiders-switch-tiers){ #insiders-switch-tiers }
-
-Yes, you can switch between different sponsoring tiers at any time. Simply go
-to the [GitHub Sponsors] page and change your sponsoring tier. Once you make
-that change, you will immediately change to the new tier.
-
-If you change to a higher tier, the amount will be prorated according to your
-billing cycle.
-
-[__Can I sponsor the project for a specific feature or development goal?__](#insiders-goals){ #insiders-goals }
-
-While sponsoring specific goals directly is not possible, our sponsoring goals
-are connected to specific features or development goals aligned with the
-project's roadmap. You can find an [overview of these sponsoring goals] and their
-associated features on our website. Insider users have early access to all
-already developed features, including those associated with higher funding goals
-that will be reached at a later stage. If you're interested in accessing these
-features, becoming a sponsor is the way to go. If you have a feature in mind
-that you would like to see on the list, we encourage you to
-[initiate a new discussion] to evaluate it with others.
-
- [overview of these sponsoring goals]: ../insiders/index.md#goals
- [initiate a new discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new/chooses
-
-[__What happens if I reach my sponsoring limit for my current tier?__](#insiders-limit){ #insiders-limit }
-
-If you extend the number of sites that are in your current sponsoring limit,
-please [upgrade your sponsorship] to a higher tier to continue using the
-Insiders version and build more sites. The change will be effective immediately.
-
- [upgrade your sponsorship]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship
-
-[__Do you offer refunds for sponsoring payments?__](#insiders-refunds){ #insiders-refunds }
-
-Unfortunately, we cannot offer any refund for sponsorship payments.
-[GitHub Sponsors] and [Ko-Fi] manage all sponsoring transactions. Because of
-that, we do not have any insights into the details of the funds and cannot access
-them. If you have any payment issues, please get in touch with the GitHub
-or Ko-Fi support team, as they can help you.
-
-## Access management
-
-[__How do I gain access to the private Insiders repository?__](#access-account){ #access-account }
-
-If you sponsored with your __individual account__, you should have received an
-email invitation to the private Material for MkDocs Insiders repository right
-after you initiated your sponsorship. Simply accept the invitation within seven
-days to gain access.
-
-If you sponsored using an __organization account__, please note we need
-an individual account that we can list as a collaborator of the private Insiders
-repository. After you initiate your sponsorship, please email us at
-sponsors@squidfunk.com with the name of the individual or bot account. Once you
-provide us with this information, we will add the account as a collaborator, and
-after you accept the invitation, you will gain access to the repository.
-
-If you have yet to receive the email or the invitation link has expired, please
-contact us, the maintainers, at sponsors@squidfunk.com. We're working on a
-solution that will allow you to manage collaborator status yourself.
-
-[__Why can't our whole organization get access to Insiders?__](#access-organization){ #access-organization }
-
-Currently, it is not possible to grant access to an organizational account, as
-GitHub only allows for adding individual user accounts. We are working on a
-solution ourselves to simplify access for organizations. For now, to ensure that
-access is not tied to a particular individual, we recommend creating a bot
-account, i.e., a GitHub account that does not belong to a specific individual
-but is listed as the owner of the organizational account and using this account
-for sponsorship.
-
-[__Do I need to fork the repository to use it?__](#access-fork){ #access-fork }
-
-It depends. If you are using the Insiders edition as an individual, you can work
-directly with the private repository, as you do not need to share the Insiders
-features with others. If you are working with a team, it is best to create a
-private fork using the individual account you listed as a collaborator of
-Material for MkDocs to grant access to all members of your organization to
-your fork.
-
-[__Can I share my Insiders access with others?__](#access-share){ #access-share }
-
-At the moment, it is not possible to directly share your collaborator status
-for the private Insiders repository with other accounts. However, if you are
-working with a team and would like them to access Insiders, you can share the
-Insiders repository by utilizing options such as [cloning], [forking], or
-[mirroring]. By doing so, you can start collaborating with your team members on
-the new repository you have shared. This way, you can collectively benefit
-from the Insiders features and work together on the project.
-
- [cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
- [forking]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
- [mirroring]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository
-
-
-## Runtime & cancellation
-
-[__How long is my sponsorship valid?__](#sponsorship-runtime){ #sponsorship-runtime }
-
-Your sponsorship is valid for as long as your monthly or yearly subscription
-is valid. If you choose to cancel your sponsorship, you will lose access to
-the Insiders edition once your cancelation is active and will be automatically
-removed by GitHub as a collaborator from the private repository.
-
-[__How do I cancel my sponsorship?__](#sponsorship-cancellation){ #sponsorship-cancellation }
-
-To cancel your sponsorship, follow the [step-by-step guide] provided by GitHub.
-If you sponsored using an organizational account, please ensure that you cancel
-your sponsorship using the same organizational account rather than your
-individual account.
-
- [step-by-step guide]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship
-
-[__What happens when I cancel my sponsorship?__](#sponsorship-cancellation-effective){ #sponsorship-cancellation-effective }
-
-If you choose to cancel your subscription to Insiders, you will be
-automatically removed by GitHub as a collaborator on the day your cancellation is
-effective. From that day on, you will no longer receive future updates. However,
-you are __welcome to continue using the latest version__ that was available to
-you at the time of your cancellation for as long as you like.
-
-Please note that [GitHub deletes private forks], so you may want to take steps to ensure
-that you have a backup of the software if necessary and use the locally installed version.
-
- [GitHub deletes private forks]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository#deleting-forks-of-private-repositories
-
-## Licensing
-
-[__What constitutes commercial use of the Insiders version?__](#commercial-use){ #commercial-use }
-
-Commercial use refers to any use of the software for a business or for-profit
-purpose. This includes any use by a corporation or other organization, whether
-or not they generate revenue directly from the software. We offer different
-pricing tiers for commercial use, each tailored to the needs of different
-businesses. It's important to note that internal use of the software within your
-organization is also considered commercial use, as with all commercial software.
-
-[__What constitutes non-commercial use of the Insiders version?__](#non-commercial-use){ #non-commercial-use }
-
-Non-commercial use of our Material for MkDocs refers to private use. This
-includes individuals using the Insiders edition for private or purely
-non-commercial Open Source projects. We offer two different tiers for
-non-commercial use, depending on the number of sites you want to build.
-
-[__What is your fair use policy?__](#fair-use-policy){ #fair-use-policy }
-
-Our fair use policy includes the following guidelines:
-
-- Please refrain from __distributing the source code__ of Insiders. While you
-may use the software for public, private, or commercial projects and may
-privately fork or mirror it, we ask that you keep the source code private. This
-is important to our sponsorware strategy, which helps us fund ongoing
-development and support of the software. If this guidelines is violated,
-everybody loses, as it will reduce the time of us maintainers we can set aside
-to push this project forward.
-
-- As our sponsoring tiers are based on the number of sites you want to build,
-please make sure to [upgrade your sponsorship] once your current sponsoring tier
-limit has been reached.
-
-[__Does the Insiders version have a different license?__](#insiders-license){ #insiders-license }
-
-No. Whether you're an individual or a company, you may use Material for
-MkDocs Insiders precisely under the same terms as Material for MkDocs, which are
-given by the [MIT license].
-
-[MIT license]: ../license.md
-
-[__Can outside collaborators build and run the documentation locally without access to Insiders?__](#insiders-outside-collaborators){ #insiders-outside-collaborators }
-
-Yes. Insiders is compatible with Material for MkDocs. Almost all new features
-and configuration options are either backward-compatible or implemented behind
-feature flags. When working with outside collaborators, changing the general
-appearance of your site should be optional. Most Insiders features enhance the
-overall experience, e.g., by adding icons to pages or providing a feedback
-widget. While these features add value for your site's users, they should be
-optional for previewing when making changes to content. Currently, the only
-content-related feature in Insiders that non-Insiders users can't properly
-preview are [Card grids].
-
-This means that outside collaborators can build the documentation locally with
-Material for MkDocs, and when they push their changes, your CI pipeline will
-build it with Insiders. When using built-in plugins exclusive to Insiders, it's
-recommended to split configuration into a base `mkdocs.yml` and one with plugin
-overrides via [configuration inheritance].
-
-See the [getting started guide] for more information.
-
- [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
- [getting started guide]: ../insiders/getting-started.md#caveats
- [Card grids]: ../reference/grids.md?h=grids#using-card-grids
-
-## Support
-
-[__How can I contact support if I have questions about becoming a sponsor?__ ](#support-contact){ #support-contact }
-
-If you have any questions and would like to contact us before starting your
-sponsorship, we are happy to answer all your non-technical questions about the
-Insiders program via email at sponsors@squidfunk.com.
-
-All technical questions should be asked openly on our [discussion board].
-
- [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
-
-[__Is additional support available for Material for MkDocs Insiders users?__](#support-additional){ #support-additional }
-
-Yes, we provide non-technical support related to sponsoring at
-sponsors@squidfunk.com. For technical questions, please submit an issue openly
-on our [issue tracker] or start a discussion on our [discussion board]. Issues
-and discussions from our organizational sponsors, sponsoring on
-__The Organization__ tier or higher will be prioritized.[^1]
-
- [^1]:
- Priority support means we will prioritize your issue, meaning we will look
- into it and do our best to solve your issue asap. However, the prioritized bug
- support does not mean that we can solve your issue before any others since
- some issues might take more time to solve.
-
- [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
-
-[__How can I display my logo on the list of premium sponsors?__](#sponsorship-logo-placement){ #sponsorship-logo-placement }
-
-If your sponsorship tier includes logo placement, and you would like us to
-display your logo in the [list of premium sponsors] and have it linked to your
-site, please contact us via mail. Simply send us a horizontal SVG or PNG version
-of your logo making sure it displays the name of your company and the logo to
-sponsors@squidfunk.com.
-
- [list of premium sponsors]: https://github.com/squidfunk/mkdocs-material#user-content-premium-sponsors
-
-[__Is logo placement optional?__](#sponsorship-logo-placement-optional){ #sponsorship-logo-placement-optional }
-
-Yes, all of our commercial benefits, such as logo placement and backlinks, are
-optional and can be opted in or out at any time. You can keep your sponsorship
-completely private.
-
-[__How can I report a bug in the Insiders version?__](#insiders-bugs){ #insiders-bugs }
-
-If you encounter a bug in the Insiders edition, we kindly request that you
-report it on our [issue tracker] in the public community repository. When
-submitting the bug report, please ensure that you do not include any private
-Insiders' source code, as we want to uphold our fair use policy.
-
-
-## Privacy
-
-[__Will you sign an NDA for sponsorships?__](#nda){ #nda }
-
-Unfortunately, we cannot sign any NDA or vendor agreement form. As a small team
-working on Material for MkDocs, we have limited resources and cannot review
-and sign agreements.
-
-[__Can I sponsor privately?__](#sponsorship-private){ #sponsorship-private }
-
-Yes, you can. GitHub gives you the option to set your sponsorship to [private]
-when you set up your sponsorship. Additionally, we have a recommended workflow
-for you: We suggest you create a new GitHub bot account. This bot account should
-not be tied to a particular individual and should be privately listed as an
-owner of your GitHub organization. This account can then be used to sponsor
-Material for MkDocs privately. As a bot account, it will automatically be listed
-as a collaborator of the private Insiders repository. You can clone, fork, or
-mirror using this account. All information will be kept confidential; only the
-bot account and us maintainers will have insights into his sponsorship.
-
- [private]: https://docs.github.com/en/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship#managing-the-privacy-setting-for-your-sponsorship
-
-[__Are there any geographical restrictions on becoming a sponsor?__](#sponsorship-geo){ #sponsorship-geo }
-
-No, there are no geographical restrictions for becoming a sponsor. We welcome
-sponsorships from individuals and organizations worldwide. As long as your
-credit card is valid and accepted by GitHub or Ko-Fi, you are eligible to become
-a sponsor and support the project, regardless of your location.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 0465b5b2084..9706e7eb744 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -68,17 +68,19 @@ install those packages separately.
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
__[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
-15m – Learn how to create and host a documentation site using Material for
+27m – Learn how to create and host a documentation site using Material for
MkDocs on GitHub Pages in a step-by-step guide.
- [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=Q-YA_dA8C20
+ [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=xlABhbnNrfI
---
-__Tip__: If you don't have prior experience with Python, we recommend reading
-[Using Python's pip to Manage Your Projects' Dependencies], which is a really
-good introduction on the mechanics of Python package management and helps you
-troubleshoot if you run into errors.
+!!! tip
+
+ If you don't have prior experience with Python, we recommend reading
+ [Using Python's pip to Manage Your Projects' Dependencies], which is a
+ really good introduction on the mechanics of Python package management and
+ helps you troubleshoot if you run into errors.
[Python package]: https://pypi.org/project/mkdocs-material/
[virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
diff --git a/docs/insiders/access-management.md b/docs/insiders/access-management.md
new file mode 100644
index 00000000000..cd8d99789e3
--- /dev/null
+++ b/docs/insiders/access-management.md
@@ -0,0 +1,204 @@
+# Access management
+
+The Material for MkDocs Insiders repository is a private repository hosted on
+GitHub and access is, therefore, managed through GitHub. This section covers
+everything you need to know in order to gain access to the private Material for
+MkDocs Insiders repository.
+
+## How to get access
+
+As the private Material for MkDocs Insiders repository is hosted on GitHub, you
+require a GitHub account to become a sponsor and to gain access. After
+sponsoring us on one of our [sponsoring tiers] starting at [$15 a month],
+you'll get access to the private Insiders repository.
+
+Please note that the process of gaining access is only partially automatable due
+to technical reasons. Depending on the type of account you've used to become a
+sponsor, we might need more information from you before we can grant access.
+
+ [$15 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+ [sponsoring tiers]: sponsoring-tiers.md
+
+### Individuals
+
+If you sponsor using a [personal account], you will receive an invitation link
+via email to the private Material for MkDocs Insiders repository immediately
+after initiating your sponsorship. This link is [valid for seven days]. Once you
+accept the invitation, you'll be ready to [get started].
+
+If the link expired, please contact us at sponsors@squidfunk.com and we'll
+send you a new one.
+
+ [personal account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts
+ [valid for seven days]: #expired-invitations
+ [get started]: getting-started.md
+
+### Organizations
+
+When sponsoring using an [organization account], GitHub will not send an
+automated invitation via email to access the private Material for MkDocs Insiders
+repository. Due to [GitHub limitations], granting access to a private repository
+for an entire organization is not possible.
+
+Therefore, please contact us at sponsors@squidfunk.com with the name of a
+[personal account] or the name of a [bot account] that is publicly or privately
+listed as an owner of your GitHub organization after you received a confirmation
+that your sponsorship was initiated.
+
+We will add this designated account as a collaborator, and once the invitation
+is [accepted within seven days], your organization will be all set to [get
+started].
+
+ [organization account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts
+ [GitHub limitations]: #collaborators
+ [bot account]: #bot-account
+ [accepted within seven days]: #expired-invitations
+
+### Enterprises
+
+If you would like to sponsor us using an [enterprise account], we recommend
+using a [personal account] or a [bot account] to initiate the sponsorship and
+access the private Material for MkDocs Insiders repository using this account.
+
+ [enterprise account]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#enterprise-accounts
+
+## Restrictions
+
+GitHub sets limitations beyond our control, which is why we require further
+information regarding [collaborators] of private repositories and [matching] of
+GitHub accounts.
+
+ [collaborators]: #collaborators
+ [matching]: #matching
+
+### Collaborators
+
+GitHub policy limits access to [private repositories] to [personal accounts]
+only, which is why it is currently not possible for us to add [organization
+accounts] to the Material for MkDocs Insiders repository – a private
+repository.
+
+As much as we would love to give each member of your organization access, it's
+simply not feasible for us to add each member account, which is why every
+[sponsoring tier] is limited to one seat. However, you can use a [bot account]
+to work around this limitation.
+
+ [private repositories]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository
+ [personal accounts]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts
+ [organization accounts]: https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts
+ [sponsoring tier]: sponsoring-tiers.md
+ [team management]: #team-management
+
+### Matching
+
+Due to privacy reasons, GitHub does not allow email addresses to be matched with
+GitHub accounts. When requesting access via email at sponsors@squidfunk.com,
+it's necessary to provide us with the name of a [personal account].
+
+## Bot account
+
+Given that only personal accounts can be listed as collaborators on
+[private repositories], ensuring access for an entire organization requires
+coordination through individuals. Changes within the team could lead to losing
+access to the entire organization.
+
+To avoid this, you have the option to create a bot account, which is
+[a new personal account] that does not belong to a specific individual but is
+publicly or privately listed as the owner of the GitHub organization
+
+Using a bot account for access management and initiating your [public] or
+[private] sponsorship through it also allows for better attribution of
+sponsorship costs, allowing you to manage access and payment for all
+sponsorships through a single account, and is thus recommended.
+
+ [a new personal account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
+ [public]: privacy.md/#public-sponsors
+ [private]: privacy.md/#private-sponsors
+
+## Expired invitations
+
+The invitation to the private Material for MkDocs is valid for seven days, a
+limitation imposed by GitHub. If invitations are not accepted within this
+period, you'll need to contact us via mail at sponsors@squidfunk.com, and we
+will re-issue the invitation immediately.
+
+## Team management
+
+If you are using Material for MkDocs Insiders as an [individual] and don't
+collaborate with other users, [forking] the private repository is not necessary.
+However, when working with a team, it is not possible to simply share your
+collaborator status with other accounts. Therefore, in order to work in a team,
+the account with access to Insiders can [fork], [clone], or [mirror] the private
+Material for MkDocs Insiders repository to an organization, providing a pathway
+for team collaboration.
+
+ [fork]: #forking
+ [clone]: #cloning
+ [mirror]: #mirroring
+ [individual]: #individuals
+
+### Outside collaborators
+
+When working with outside collaborators, you should know that the Insiders
+edition is compatible with the community edition. All new features and
+configuration options are backward-compatible or implemented behind feature
+flags. Most Insiders features enhance the overall experience, e.g., by creating
+better social cards or instant previews. While these features add value for your
+site's users, they are most certainly not necessary for previewing your site.
+
+This means that outside collaborators can build the documentation locally with
+the community edition, and when they push their changes, your CI pipeline will
+build it with Insiders. When using [built-in plugins] exclusive to Insiders, we
+recommend using the [group] plugin.
+
+See the [getting started guide] for more information.
+ [getting started guide]: getting-started.md
+ [built-in plugins]: ../plugins/index.md
+ [group]: ../plugins/group.md
+
+### Forking
+
+[Forking] a repository creates a copy of the repository that allows for
+independent development while maintaining a link to the original repository
+for updates.
+
+ [forking]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+
+### Cloning
+
+[Cloning] a repository copies the repository to your local machine or codespace,
+facilitating offline work and content management. You can, of course, also
+[clone a private fork].
+
+ [cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
+ [clone a private fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository
+
+### Mirroring
+
+[Mirroring] a repository creates an identical copy, ensuring you have the
+flexibility to host and work with the repository [in other environments] besides
+GitHub. This is a particularly useful strategy for organizations hosting their
+repositories in a private environment outside of GitHub.
+
+ [mirroring]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository
+ [in other environments]: #github-alternatives
+
+## GitHub alternatives
+
+Material for MkDocs Insiders is designed to be compatible with various
+repository hosting platforms, including GitLab. The key requirement is still a
+GitHub account, as we use GitHub Sponsors for transactions and GitHub to manage access to the private Insiders repository.
+
+Once you've become a sponsor and secured access to the private Insiders
+repository via an individual GitHub account, you can [mirror the repository in
+another location]. This mirroring process not only allows for easy integration
+into your existing workflow but also ensures that your projects stay up-to-date
+with the latest features and improvements of Insiders.
+
+Our discussion board is a valuable resource for any questions about integrating
+Material for MkDocs Insiders into your projects. It offers a space to connect
+with others who may have similar requirements and setups, as well as to
+exchange tips and explore solutions together.
+
+ [mirror the repository in another location]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository#mirroring-a-repository-in-another-location
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/docs/insiders/benefits.md b/docs/insiders/benefits.md
new file mode 100644
index 00000000000..f960160856d
--- /dev/null
+++ b/docs/insiders/benefits.md
@@ -0,0 +1,345 @@
+# What’s in it for you
+
+Material for MkDocs Insiders is packed with additional features that are
+exclusively available to our monthly sponsors – the moment you become a sponsor,
+you'll gain __immediate access__ to all the exclusive Insiders features, ready
+for you to __start using now__.
+
+## Features
+
+Our sponsors currently enjoy access to the following 26 additional features. New
+features are added regularly, so be sure to check back regularly to stay
+updated.
+
+
+
+## What's coming next
+
+> Too many ideas, too little time!
+
+Our backlog is filled with countless ideas that we came up with or that have
+been suggested by our community. We're also working to make our roadmap public.
+If you have something specific in mind, and wonder whether we've considered it,
+feel free to ask on our [discussion board].
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+
+## Frequent releases
+
+We’re committed to quickly addressing bugs, that come up and keeping our open
+issue count as low as possible. Both our community and Insiders editions are
+regularly updated, ensuring you have the latest features and fixes available at
+all times.
+
+## Additional benefits
+
+As a premium sponsors, you'll enjoy additional benefits that are not available
+to our individual sponsors. When sponsoring our work on one of our [commercial
+tiers] starting at [$125 a month], you'll get additional benefits that we offer
+for enterprises:
+
+- [Prioritized] bug reports to keep your projects running smoothly
+- Logo placement and backlink on our site for increased visibility
+- Private support via email for any questions to our maintainers
+
+ [commercial tiers]: sponsoring-tiers.md/#commercial-use
+ [$125 a month]: sponsoring-tiers.md/#the-organization
+ [list of premium sponsors]: https://github.com/squidfunk/mkdocs-material#user-content-premium-sponsors
+ [Prioritized]: ../support.md/#prioritized-support
+
+----
+
+Interested in supporting us? Together, let’s continue to make Material for
+MkDocs an even more powerful tool for everyone. We’re excited for what the
+future holds!
+
+[:octicons-heart-fill-24:{ .mdx-heart } Show your support ][sponsoring tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring tiers]: sponsoring-tiers.md#commercial-use
+
+
+
+## Funding
+
+### Goals
+
+The following section lists all funding goals. Each goal contains a list of
+features prefixed with a checkmark symbol, denoting whether a feature is
+:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or
+:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" }
+planned, but not yet implemented. This means that each funding goal unlocks new
+features for general availability in the community edition, after sponsors have
+used them for a while.
+
+#### $ 16,000 – Chipotle
+
+- [x] [Meta plugin]
+- [x] [Blog plugin: related links]
+- [x] [Blog plugin: custom index pages]
+- [x] [Tags plugin: configurable listings]
+- [x] [Tags plugin: allow list] + [custom sorting]
+- [x] [Navigation subtitles]
+
+ [Meta plugin]: ../plugins/meta.md
+ [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
+ [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
+ [Tags plugin: configurable listings]: ../setup/setting-up-tags.md#configurable-listings
+ [Tags plugin: allow list]: ../plugins/tags.md#config.tags_allowed
+ [custom sorting]: ../plugins/tags.md#config.tags_sort_by
+ [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
+
+#### $ 18,000 – Lemon Drop
+
+- [x] [Optimize plugin]
+- [x] [Navigation path] (Breadcrumbs)
+- [x] [Blog plugin: advanced settings]
+- [x] [Blog plugin: author profiles]
+- [x] [Blog plugin: pinned posts]
+- [x] [Instant prefetching]
+
+ [Optimize plugin]: ../plugins/optimize.md
+ [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
+ [Blog plugin: advanced settings]: ../setup/setting-up-a-blog.md#advanced-settings
+ [Blog plugin: author profiles]: ../setup/setting-up-a-blog.md#adding-author-profiles
+ [Blog plugin: pinned posts]: ../setup/setting-up-a-blog.md#pinning-a-post
+ [Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
+
+#### $ 20,000 – Jalapeño
+
+- [x] [Typeset plugin]
+- [x] [Footnote tooltips]
+- [x] [Privacy plugin: advanced settings]
+- [x] [Privacy plugin: external links]
+- [ ] to be announced
+- [ ] to be announced
+
+ [Typeset plugin]: ../plugins/typeset.md
+ [Footnote tooltips]: ../reference/footnotes.md#footnote-tooltips
+ [Privacy plugin: external links]: ../plugins/privacy.md#external-links
+ [Privacy plugin: advanced settings]: ../setup/ensuring-data-privacy.md#advanced-settings
+
+#### $ 22,000 – Habanero Orange
+
+- [x] [Instant previews]
+- [x] [Social plugin: custom layouts]
+- [x] [Social plugin: background images]
+- [x] [Code range selection]
+- [x] [Code annotations: custom selectors]
+- [x] [Stay on page when switching languages]
+
+ [Instant previews]: ../setup/setting-up-navigation.md#instant-previews
+ [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
+ [Social plugin: background images]: ../plugins/social.md#option.background_image
+ [Code range selection]: ../reference/code-blocks.md#code-selection-button
+ [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
+ [Stay on page when switching languages]: ../setup/changing-the-language.md#stay-on-page
+
+#### $ 24,000 – Blockpaprika
+
+- [x] [Projects plugin]
+- [x] [Tags plugin: nested tags]
+- [x] [Tags plugin: shadow tags]
+- [x] [Tags plugin: advanced settings]
+- [ ] to be announced
+- [ ] to be announced
+
+ [Projects plugin]: ../plugins/projects.md
+ [Tags plugin: nested tags]: ../setup/setting-up-tags.md#nested-tags
+ [Tags plugin: shadow tags]: ../setup/setting-up-tags.md#shadow-tags
+ [Tags plugin: advanced settings]: ../setup/setting-up-tags.md#advanced-settings
+
+### Goals completed
+
+This section celebrates the milestones we’ve achieved thanks to our incredible
+sponsors. Those features were once part of Material for MkDocs Insiders, and
+therefore only available to our sponsors, and are now generally available to
+be used by all users.
+
+#### $ 14,000 – Goat's Horn
+
+- [x] [Privacy plugin]
+- [x] [Card grids]
+- [x] [Tooltips]
+- [x] [Content tabs: anchor links]
+- [x] [Automatic light / dark mode]
+- [x] [Document contributors]
+
+ [Privacy plugin]: ../setup/ensuring-data-privacy.md#built-in-privacy-plugin
+ [Card grids]: ../reference/grids.md
+ [Tooltips]: ../reference/tooltips.md
+ [Content tabs: anchor links]: ../reference/content-tabs.md#anchor-links
+ [Automatic light / dark mode]: ../setup/changing-the-colors.md#automatic-light-dark-mode
+ [Document contributors]: ../setup/adding-a-git-repository.md#document-contributors
+
+#### $ 12,000 – Piri Piri
+
+- [x] [Blog plugin]
+- [x] [Chinese search support]
+- [x] [Annotations]
+- [x] [Navigation icons]
+- [x] [Navigation pruning]
+- [x] [Navigation status]
+
+ [Blog plugin]: ../setup/setting-up-a-blog.md
+ [Chinese search support]: ../blog/posts/chinese-search-support.md
+ [Annotations]: ../reference/annotations.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
+
+#### $ 10,000 – Carolina Reaper
+
+- [x] [Brand new search plugin]
+- [x] [Rich search previews]
+- [x] [Tokenizer with lookahead]
+- [x] [Advanced search highlighting]
+- [x] [Excluding content from search]
+- [x] [Offline plugin]
+
+ [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
+
+#### $ 8,000 – Scotch Bonnet
+
+- [x] [Social cards]
+- [x] Code annotations: anchor links
+- [x] [Code annotations: strip comments]
+- [x] [Tag icons]
+- [x] [Table of contents anchor following]
+- [x] Sidebars automatically scroll to active item
+
+ [Social cards]: ../setup/setting-up-social-cards.md
+ [Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
+ [Tag icons]: ../setup/setting-up-tags.md#tag-icons-and-identifiers
+ [Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following
+
+#### $ 7,000 – Royal Gold
+
+- [x] [Cookie consent]
+- [x] [Was this page helpful?]
+- [x] [Dismissable announcement bar]
+
+ [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
+
+#### $ 6,000 – Trinidad Scorpion
+
+- [x] [Boosting pages in search]
+- [x] [Custom admonition icons]
+- [x] [Linking content tabs]
+
+ [Boosting pages in search]: ../setup/setting-up-site-search.md#search-boosting
+ [Custom admonition icons]: ../reference/admonitions.md#admonition-icons
+ [Linking content tabs]: ../reference/content-tabs.md#linked-content-tabs
+
+#### $ 5,000 – Aji Panca
+
+- [x] [Mermaid.js integration]
+- [x] Stay on page when switching versions
+- [x] [Tags with search integration]
+
+ [Mermaid.js integration]: ../reference/diagrams.md
+ [Tags with search integration]: ../setup/setting-up-tags.md
+
+#### $ 4,000 – Ghost Pepper
+
+- [x] [Anchor tracking]
+- [x] [Code annotations]
+- [x] [Version warning]
+
+ [Anchor tracking]: ../setup/setting-up-navigation.md#anchor-tracking
+ [Code annotations]: ../reference/code-blocks.md#adding-annotations
+ [Version warning]: ../setup/setting-up-versioning.md#version-warning
+
+#### $ 3,000 – Caribbean Red
+
+- [x] [Sticky navigation tabs]
+- [x] [Section index pages]
+- [x] [Remove generator notice]
+
+ [Sticky navigation tabs]: ../setup/setting-up-navigation.md#sticky-navigation-tabs
+ [Section index pages]: ../setup/setting-up-navigation.md#section-index-pages
+ [Remove generator notice]: ../setup/setting-up-the-footer.md#generator-notice
+
+#### $ 2,500 – Biquinho Vermelho
+
+- [x] [Search suggestions]
+- [x] [Search highlighting]
+- [x] [Search sharing]
+
+ [Search suggestions]: ../setup/setting-up-site-search.md#search-suggestions
+ [Search highlighting]: ../setup/setting-up-site-search.md#search-highlighting
+ [Search sharing]: ../setup/setting-up-site-search.md#search-sharing
+
+#### $ 2,000 – Black Pearl
+
+- [x] Latest release tag
+- [x] [Color palette toggle]
+- [x] [Back-to-top button]
+
+ [Color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
+ [Back-to-top button]: ../setup/setting-up-navigation.md#back-to-top-button
+
+#### $ 1,500 – Bhut Jolokia
+
+- [x] [Admonition inline blocks]
+- [x] [Site language selection]
+- [x] [Versioning]
+
+ [Admonition inline blocks]: ../reference/admonitions.md#inline-blocks
+ [Site language selection]: ../setup/changing-the-language.md#site-language-selector
+ [Versioning]: ../setup/setting-up-versioning.md#versioning
+
+#### $ 1,000 – Prairie Fire
+
+- [x] [Navigation sections]
+- [x] [Navigation expansion]
+- [x] [Hiding the sidebars]
+- [x] [Table of contents in navigation]
+- [x] [Header hides on scroll]
+
+ [Navigation sections]: ../setup/setting-up-navigation.md#navigation-sections
+ [Navigation expansion]: ../setup/setting-up-navigation.md#navigation-expansion
+ [Hiding the sidebars]: ../setup/setting-up-navigation.md#hiding-the-sidebars
+ [Table of contents in navigation]: ../setup/setting-up-navigation.md#navigation-integration
+ [Header hides on scroll]: ../setup/setting-up-the-header.md#automatic-hiding
+
+#### $ 500 – Madame Jeanette
+
+- [x] Improved search result grouping
+- [x] Improved search result relevance and scoring
+- [x] Missing query terms in search results
diff --git a/docs/insiders/changelog/index.md b/docs/insiders/changelog/index.md
index c38f58b1cc8..0e3aca78003 100644
--- a/docs/insiders/changelog/index.md
+++ b/docs/insiders/changelog/index.md
@@ -2,6 +2,198 @@
## Material for MkDocs Insiders
+### 4.53.14 September 29, 2024 { id="4.53.14" }
+
+- Fixed #7567: Empty headlines when using typeset plugin with anchorlinks
+
+### 4.53.13 September 14, 2024 { id="4.53.13" }
+
+- Fixed #7520: Social plugin errors for generated files (MkDocs 1.6+)
+
+### 4.53.12 August 2, 2024 { id="4.53.12" }
+
+- Fixed #7410: Instant previews jump on content tabs with anchor links
+- Fixed #7408: Instant previews jump on content tabs
+
+### 4.53.11 May 27, 2024 { id="4.53.11" }
+
+- Fixed projects plugin crashing when serving before building subprojects
+
+### 4.53.10 May 20, 2024 { id="4.53.10" }
+
+- Fixed projects plugin crashing in serve mode when disabled
+- Fixed projects plugin crashing when building nested projects
+
+### 4.53.9 May 20, 2024 { id="4.53.9" }
+
+- Fixed #7191: Tags listings not rendering when `toc_depth` is changed
+
+### 4.53.8 April 26, 2024 { id="4.53.8" }
+
+- Fixed #7052: Preview extension automatically including all pages
+- Fixed #7051: Instant previews mounting on footnote references
+- Fixed #5165: Improved tooltips not mounting in sidebar for typeset plugin
+
+### 4.53.7 April 25, 2024 { id="4.53.7" }
+
+- Fixed #7060: Incorrect resolution of translation when using static-i18n
+
+### 4.53.6 April 5, 2024 { id="4.53.6" }
+
+- Ensure working directory is set for projects when using projects plugin
+- Fixed #6970: Incorrect relative paths in git submodules with projects plugin
+
+### 4.53.5 April 2, 2024 { id="4.53.5" }
+
+- Fixed social plugin crashing when no colors are specified in palettes
+
+### 4.53.4 March 31, 2024 { id="4.53.4" }
+
+- Fixed #6973: Escaping issue in tags extra files deprecation helper
+
+### 4.53.3 March 23, 2024 { id="4.53.3" }
+
+- Added support for font variants in social plugin
+- Improved resilience of font resolution in social plugin
+- Fixed tag listing sometimes not being auto-populated
+- Fixed tag listing scope not being correctly resolved
+- Fixed #6941: Meta plugin adding duplicate entries
+- Fixed #6928: Social plugin crashes for some fonts
+
+### 4.53.2 March 18, 2024 { id="4.53.2" }
+
+- Fixed abort on first non-matching configuration in preview extension
+- Fixed #6914: Meta files take precedence over front matter
+
+### 4.53.1 March 6, 2024 { id="4.53.1" }
+
+- Fixed #6877: Projects plugin computes incorrect path to assets
+- Fixed #6869: Blog plugin should emit warning on invalid related link
+
+### 4.53.0 February 24, 2024 { id="4.53.0" }
+
+- Added support for automatic instant previews
+- Added support for pinned blog posts
+
+### 4.52.3 February 21, 2024 { id="4.52.3" }
+
+- Fixed resolution of URLs in instant previews
+- Fixed instant previews not mounting for same-page links
+
+### 4.52.2 February 7, 2024 { id="4.52.2" }
+
+- Fixed #6735: Instant previews misplaced when below tabs
+
+### 4.52.1 January 30, 2024 { id="4.52.1" }
+
+- Fixed #6705: Navigation path not being hidden when specified
+- Fixed #6703: New tags plugin crashes on Windows (2nd attempt)
+
+### 4.52.0 January 28, 2024 { id="4.52.0" }
+
+- Added support for instant previews
+- Fixed footnote tooltips positioning edge cases
+- Fixed #6703: New tags plugin crashes on Windows
+
+### 4.51.0 January 24, 2024 { id="4.51.0" }
+
+- Added support for footnote tooltips
+
+### 4.50.0 January 19, 2024 { id="4.50.0" }
+
+- Added configurable logging capabilities to privacy plugin
+
+### 4.49.2 January 9, 2024 { id="4.49.2" }
+
+- Fixed missing attribute lists extension for tags plugin
+- Fixed #6627: New tags plugin crashes on Python 3.8
+
+### 4.49.1 January 7, 2024 { id="4.49.1" }
+
+- Improved interop of new tags plugin with other plugins
+- Fixed #6594: Tags plugin doesn't work with mkdocs-macros plugin
+- Fixed #6569: Social plugin crashes if in different file system location
+
+### 4.49.0 December 29, 2023 { id="4.49.0" }
+
+- Added support for exporting tags and mappings
+- Added support for disabling tags and/or listings or both
+- Fixed tag links from pages to listings on homepage
+
+### 4.48.0 December 23, 2023 { id="4.48.0" }
+
+- Rewrite of tags plugin, now much more powerful
+- Added support for nested tags (tag hierarchies, e.g. foo/bar)
+- Added support for shadow tags (by list, prefix or suffix)
+- Added support for custom tag layouts and templates
+- Added support for hiding tags in table of contents
+- Added support for configurable inline tag listings
+- Added support for automatically linking to closest tag listing
+- Added support for scoped listings (limit to subsection of site)
+- Added support for multiple instances of tags plugin
+- Added support for changing front matter property and template variable
+- Added support for tag slugification format strings
+- Fixed #6510: Projects plugin out of memory on Linux (4.47.1 regression)
+- Fixed projects plugin not notifying plugins about serve mode
+- Fixed projects plugin skipping projects on prefix match
+- Deprecated tags_file and tags_extra_files settings
+- Modernized tags plugin code base
+
+### 4.47.1 December 11, 2023 { id="4.47.1" }
+
+- Improved editing experience for projects plugin
+- Improved resilience of optimize and social plugin
+- Fixed race condition when writing manifest in optimize and social plugin
+- Fixed #6475: Logo not taking precedence over icon in social card
+- Fixed #6399: Projects plugin doesn't pick up added/removed projects
+- Fixed #6306: Projects plugin cache not correctly updated
+
+### 4.47.0 December 8, 2023 { id="4.47.0" }
+
+- Added support for staying on page when switching languages
+- Added configurable logging capabilities to projects plugin
+- Removed temporary warning on blog plugin authors file format change
+- Fixed projects plugin logging messages twice on Linux systems
+- Fixed projects plugin trying to hoist theme assets of divergent themes
+- Fixed compatibility of optimize plugin and projects plugin
+- Fixed compatibility of social plugin and projects plugin
+- Fixed #6448: Code line selection broken for code blocks with custom ids
+- Fixed #6437: Projects plugin crashing for certain site URL configurations
+- Fixed #6414: Projects plugin doesn't prefix messages coming from projects
+
+### 4.46.0 November 26, 2023 { id="4.46.0" }
+
+- Added support for author profiles in blog plugin
+- Fixed custom index pages yielding two navigation items (4.45.0 regression)
+
+### 4.45.0 November 24, 2023 { id="4.45.0" }
+
+- Added support for sorting blog categories by post count or custom function
+- Improved tags plugin to generate Unicode-aware slugs by default
+- Fixed non-deterministic order of multiple authors in blog plugin
+
+### 4.44.0 November 23, 2023 { id="4.44.0" }
+
+- Added pagination settings for archive pages in blog plugin
+- Added pagination settings for category pages in blog plugin
+
+### 4.43.1 November 19, 2023 { id="4.43.1" }
+
+- Added third-party theme support in projects plugin, improving editing
+- Fixed #6360: Projects plugin crashes when theme is not Material for MkDocs
+- Fixed #6306: Projects plugin not reloading nested project configuration
+
+### 4.43.0 November 5, 2023 { id="4.43.0" }
+
+- Added support for GitLab committers (document contributors)
+- Fixed #6264: Fixed compatibility with Python < 3.10
+- Fixed #6254: Meta plugin not applying meta files to blog posts
+
+### 4.42.3 October 27, 2023 { id="4.42.3" }
+
+- Fixed #6251: Cards in grids cut off on very small screens
+- Fixed #6241: Using social plugin + static-i18n plugin errors
+
### 4.42.2 October 14, 2023 { id="4.42.2" }
- Fixed #6186: Privacy plugin ignores hash fragments on images
diff --git a/docs/insiders/community-experts-program/index.md b/docs/insiders/community-experts-program/index.md
new file mode 100644
index 00000000000..54c6276960d
--- /dev/null
+++ b/docs/insiders/community-experts-program/index.md
@@ -0,0 +1,148 @@
+---
+title: Community Experts Program
+status: new
+---
+
+# Calling for Community Experts
+
+Interested in joining the Material for MkDocs team as a Community Expert?
+We're on the lookout for individuals who are passionate about supporting our
+awesome community. In return for your valuable contributions, time, and
+insights, __you'll gain free access to the Insiders edition__.
+
+## Why we need you
+
+As our project and community continue to grow, so do the questions and needs of
+our users on our discussion board. Our discussion board is a vital part of our
+project, serving as a hub for our community to connect and a valuable knowledge
+base to complement our documentation.
+
+We're eager to keeping it well-maintained, organized, easy to search and address
+all queries which is why we need extra hands to keep up with the demand.
+
+That's why we're building a team of Community Experts!
+
+## Your role
+
+As a Community Expert, your role primarily involves active participation on
+our [discussion board], where we'd expect you to be:
+
+- Answering discussions to help users with their questions
+- Providing guidance regarding implementations
+- Sharing insights into customizations and workarounds
+- Optimizing searchability by adjusting discussion titles with relevant keywords
+
+## Your benefits
+
+Here is a list of the benefits we offer to our Community Experts:
+
+- __Free access to Material for MkDocs Insiders__ – Exclusive Access to all of
+ our Material for MkDocs Insiders features for _non-commercial use_.[^1]
+
+- __Close communication with the team__ – Stay connected with us through various
+ channels, including calls and internal project management tools.
+
+- __GitHub profile boost__ – Enhance your GitHub profile's visibility and
+ credibility as your activity increases, earning you valuable badges that can
+ enhance your credibility.
+
+ [^1]:
+ Access to Insiders is granted to your primary account, i.e., the account
+ with which you're contributing to the project. It cannot be transferred to
+ another account. Additionally, it cannot be used for commercial purposes.
+
+## Your knowledge & skills
+
+To be a successful Community Expert, your skills should include the following:
+
+- __Material and MkDocs allrounder__ – You have an understanding of Material
+ for MkDocs and the MkDocs ecosystem, including many of its extensions and
+ plugins.
+
+- __Great communicator__ – You enjoy helping others in a productive,
+ constructive and friendly manner and use inclusive and welcoming language.
+
+- __Independent worker__ – You are self-motivated, stay up-to-date with
+ project developments, regularly check the discussion board, and respond to
+ notifications in reasonable time.
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [documentation]: https://squidfunk.github.io/mkdocs-material/
+ [contribution guides]: ../contributing/index.md
+
+## Your time commitment
+
+We don't require a fixed number of hours each week; instead, we ask for a
+minimum of __five answered discussions per month[^2]__, which amounts to
+slightly more than one per week. Your active interaction within the community is
+highly valued.
+
+To do this effectively, it's best to regularly check the discussion board to see
+where you can offer help. The time you invest may vary depending on the
+complexity of the topics and questions.
+
+Upon joining, you'll receive access to the Insiders' edition for as long as you
+continue to assist us. Access will be renewed every three months, allowing you
+the flexibility to continue your contributions or take a break as needed.
+
+ [^2]:
+ An answered discussion is a collaborative interaction where knowledge and
+ expertise are shared, resulting in resolutions or clarifications that benefit
+ the user and our entire community. In essence, it embodies the spirit of
+ cooperation and support within our community, highlighting the power of
+ collective wisdom and the willingness to assist and uplift one another.
+
+## Ready to get started?
+
+Since we have a limited number of seats for these roles[^3], we would like to
+get to know you before you become one of our Community Experts. Here's how to
+get started:
+
+ [^3]:
+ Please note that we're currently limiting the number of seats on the
+ Community Experts program to three. We will update this page when we'll
+ expand the team, which is when we'll be accepting new applications.
+
+### Step 1: Get in touch
+
+Send us an email introducing yourself, sharing a bit about your background, and
+include a link to your GitHub profile. Additionally, provide links to three
+previous discussions you've answered on the discussion board, where you've
+assisted another community member.
+
+Please use the following email template to reach out to us at
+community@squidfunk.com:
+
+```
+Subject: Community Expert
+
+Intro: Tell us a bit about yourself.
+ - Name:
+ - Background:
+ - Profession:
+ - GitHub profile:
+
+Answered discussions
+ - Link 1:
+ - Link 2:
+ - Link 3:
+```
+
+### Step 2: Evaluation
+
+After receiving and reviewing your application, we will get in touch with you
+to discuss everything you need to know to get started. If you get selected, we
+will set you up as a collaborator and provide you immediate access to the
+Insiders edition for three months.
+
+### Step 3: Dive in
+
+Let's get started! You can actively begin participating in five discussions per
+month. We trust you to take the lead, and we won't do strict monitoring. Simply
+ensure that you are consistently listed on the _Most Helpful_ list, located on
+the discussion board's left side, under the categories.
+---
+
+__Ready to join us?__
+
+Sounds good? Let's give it a try!
diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md
index cb6c1985119..f0c7862cfac 100644
--- a/docs/insiders/getting-started.md
+++ b/docs/insiders/getting-started.md
@@ -12,7 +12,7 @@ repository, you need to [become an eligible sponsor] of @squidfunk on GitHub.
[pip]: #with-pip
[docker]: #with-docker
[git]: #with-git
- [become an eligible sponsor]: index.md#how-to-become-a-sponsor
+ [become an eligible sponsor]: how-to-sponsor.md
## Requirements
@@ -42,13 +42,13 @@ your private repositories.
Material for MkDocs Insiders can be installed with `pip`. You will
normally want to install the latest release but can also install a
-specific older release or even the latest development version.
+specific older release or even the latest development version.
Make sure you have the `GH_TOKEN` variable set as instructed above.
=== "Specific release"
- Pick the corresponding tag from the [list of tags] for the Insiders
- repository. In the `pip` command below, replace the tag at the
+ Pick the corresponding tag from the [list of tags] for the Insiders
+ repository. In the `pip` command below, replace the tag at the
end of the URL with the one you want.
``` sh
@@ -180,12 +180,5 @@ Of course, you can also enable both groups with:
CI=1 INSIDERS=1 mkdocs build
```
- [^1]:
- Previously we recommended to use [configuration inheritance] to work around
- this limitations, but the brand new [built-in group plugin] is a much better
- approach, as it allows you to use a single configuration file for building
- your project with the community edition and Insiders version of Material
- for MkDocs.
-
[built-in group plugin]: ../plugins/group.md
[configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
diff --git a/docs/insiders/how-to-sponsor.md b/docs/insiders/how-to-sponsor.md
new file mode 100644
index 00000000000..be170d497b7
--- /dev/null
+++ b/docs/insiders/how-to-sponsor.md
@@ -0,0 +1,114 @@
+# How to sponsor
+
+Becoming a sponsor for Material for MkDocs is a straightforward process through
+@squidfunk's [GitHub Sponsors profile]. By supporting
+the project with a monthly contribution of __$15 a month__ or more, you can sponsor
+either via an [individual] or [organizational] GitHub account.
+
+ [GitHub Sponsors profile]: https://github.com/sponsors/squidfunk
+ [individual]: access-management.md/#individuals
+ [organizational]: access-management.md/#organizations
+
+## Walkthrough
+
+Want to become a sponsor? We will guide you through the sponsoring process below
+If you have additional questions, you can find detailed information about
+[payment and billing], [access management], [runtime and cancellation],
+[privacy], [license] and [support] on dedicated pages.
+
+ [payment and billing]: payment-and-billing.md
+ [access management]: access-management.md
+ [runtime and cancellation]: runtime-and-cancellation.md
+ [privacy]: privacy.md
+ [license]: license.md
+ [support]: ../support.md
+
+### Sponsoring tier
+
+First, it's a good idea to explore [our sponsoring tiers], as each sponsoring
+tier is designed to accommodate different levels of sponsors and includes
+dedicated benefits.
+
+After reviewing the sponsoring tiers, it's time to choose one. Consider what you
+want to achieve and keep your requirements in mind, e.g. the number of projects
+you want to build or how many accounts you need. [Switching tiers] is possible
+at any time.
+
+Choosing a tier will take you to GitHub's sponsorship confirmation page.
+
+ [our sponsoring tiers]: sponsoring-tiers.md
+ [Switching tiers]: sponsoring-tiers.md/#switching-tiers
+
+### Sponsorship summary
+
+#### Payment and billing
+
+Next, GitHub will ask you to provide your billing information, which is required
+to process your sponsorship payment. On this page, the _Sponsorship summary_
+section displays the (possibly prorated) amount due to initiate your sponsorship.
+This amount is determined by your account's [billing cycle], which can be set to
+a monthly or yearly interval.
+
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+
+Proceed to input your [payment information], specifically your credit card
+details. Please make sure that the used credit card is valid and will remain
+so for an extended period to help avoid any interruptions in your sponsorship.
+
+ [payment information]: payment-and-billing.md
+
+#### Privacy
+
+On this page, you can also set the visibility of your sponsorship. You have the
+option to keep your [sponsorship private or to make it public], which includes
+listing your name or organization on the list of [our sponsors] and, for
+organizations, the opportunity for [logo placement].
+
+ [sponsorship private or to make it public]: privacy.md
+ [our sponsors]: our-sponsors.md
+ [logo placement]: our-sponsors.md/#premium-sponsors
+
+#### News and updates
+
+Note that we rarely send out emails, and when we do, it's usually to inform you
+about significant updates or changes to the project, so it's best to keep this
+option enabled. To stay updated on the latest developments, you can check out
+our [changelog].
+
+ [changelog]: ../changelog/index.md
+
+#### Tax information
+
+If you're sponsoring as an organization, it's essential to provide your country,
+region and VAT number, so we can correctly attribute your sponsorship. This is
+due to the fact that VAT is handled differently for individuals than for
+organizations.
+
+#### Confirmation
+
+Before finalizing your sponsorship, take a moment to review all the details of
+your sponsorship, including the selected tier, billing information, and payment
+details.
+
+Then proceed to confirm your sponsorship by clicking the _Sponsor_ button.
+
+### Access management
+
+After completing the sponsorship process and your payment is successfully
+processed, you will be all set to [gain access] to the private Material for
+MkDocs Insiders repository.
+
+ [gain access]: access-management.md
+
+---
+
+__Ready to become a sponsor?__
+
+[ Choose a sponsoring tier ][sponsoring-tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring-tiers]: sponsoring-tiers.md
+
+If you still find yourself with more questions, feel free to [reach out to Kathi]
+via mail at sponsors@squidfunk.com for additional support.
+
+ [reach out to Kathi]: ../support.md/#sponsoring-support
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index 27ed3661286..ee6af1f346e 100644
--- a/docs/insiders/index.md
+++ b/docs/insiders/index.md
@@ -1,550 +1,229 @@
----
-title: Insiders
----
-
# Insiders
-Material for MkDocs follows the __sponsorware__ release strategy, which means
-that new features are first exclusively released to sponsors as part of
-[Insiders]. Read on to learn [what sponsorships achieve],
-[how to become a sponsor] to get access to Insiders, and [what's in it for you]!
-
-
-
- [Insiders]: #what-is-insiders
- [what sponsorships achieve]: #what-sponsorships-achieve
- [how to become a sponsor]: #how-to-become-a-sponsor
- [what's in it for you]: #whats-in-it-for-me
- [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
-
-## What is Insiders?
-
-Material for MkDocs Insiders is a private fork of Material for MkDocs, hosted as
-a private GitHub repository. Almost[^1] [all new features][what's in it for you]
-are developed as part of this fork, which means that they are immediately
-available to all eligible sponsors, as they are made collaborators of this
-repository.
-
- [^1]:
- In general, every new feature is first exclusively released to sponsors, but
- sometimes upstream dependencies like [Python Markdown Extensions] enhance
- existing features that must be supported by Material for MkDocs.
-
-Every feature is tied to a [funding goal] in monthly subscriptions. When a
-funding goal is hit, the features that are tied to it are merged back into
-Material for MkDocs and released for general availability, making them available
-to all users. Bugfixes are always released in tandem.
-
-Sponsorships start as low as [__$15 a month__][how to become a sponsor].[^2]
-
- [^2]:
- Note that $15 a month is the minimum amount to become eligible for
- Insiders. While GitHub Sponsors also allows to sponsor lower amounts or
- one-time amounts, those can't be granted access to Insiders due to
- technical reasons.
-
- [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
- [funding goal]: #funding
-
-## What sponsorships achieve
-
-Sponsorships make this project sustainable, as they buy the maintainers of this
-project time – a very scarce resource – which is spent on the development of new
-features, bug fixing, stability improvement, issue triage and general support.
-The biggest bottleneck in Open Source is time.[^3]
-
- [^3]:
- Making an Open Source project sustainable is exceptionally hard: maintainers
- burn out, projects are abandoned. That's not great and very unpredictable.
- The sponsorware model ensures that if you decide to use Material for MkDocs,
- you can be sure that bugs are fixed quickly and new features are added
- regularly.
-
-If you're unsure if you should sponsor this project, check out the list of
-[completed funding goals] to learn whether you're already using features that
-were developed with the help of sponsorships. You're most likely using at least
-a handful of them, [thanks to our awesome sponsors]!
-
- [completed funding goals]: #goals-completed
- [thanks to our awesome sponsors]: #how-to-become-a-sponsor
-
-
-
-## What's in it for me?
-
-The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 23 additional features__ that you can __start using now__, and
-which are currently exclusively available to sponsors:
-
-
-
-- [x] [Projects plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
-- [x] [Instant prefetching] :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
-- [x] [Social plugin: custom layouts] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
-- [x] [Social plugin: background images] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
-- [x] [Code range selection]
-- [x] [Code annotations: custom selectors]
-- [x] [Privacy plugin: optimization support]
-- [x] [Optimize plugin]
-- [x] [Navigation path] (Breadcrumbs)
-- [x] [Typeset plugin]
-- [x] [Privacy plugin: external links]
-- [x] [Navigation subtitles]
-- [x] [Tags plugin: allow list] + [custom sorting]
-- [x] [Blog plugin: custom index pages]
-- [x] [Blog plugin: related links]
-- [x] [Meta plugin]
-- [x] [Tags plugin: additional indexes]
-- [x] [Document contributors]
-- [x] [Automatic light / dark mode]
-- [x] [Content tabs: anchor links]
-- [x] [Tooltips]
-- [x] [Card grids]
-- [x] [Privacy plugin]
+Material for MkDocs Insiders offers an enhanced experience with early access to
+exclusive features that aren't available in the community edition. Become a
+sponsor and make use of these features directly!
-
+You’ve already seen the benefits of using Material for MkDocs;
+imagine what more you can achieve with Insiders. Your sponsorship helps us
+continue to innovate and improve, ensuring Material for MkDocs remains a
+cutting-edge tool. Discover how your contributions make a difference.
+
+[ Choose a sponsoring tier ][sponsoring-tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring-tiers]: sponsoring-tiers.md
+
+## Additional information
+
+Explore the following section to learn more about Material for MkDocs, why
+you should sponsor us, what's in it for you, and who is sponsoring us.
+
+
+
+- :fontawesome-solid-circle-question:
+ __Why sponsor us__
+
+ ---
+
+ Learn how to support our goal of becoming the leading tool in documentation
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Why sponsor us]
+
+- :material-gift:
+ __What's in it for you__
+
+ ---
+
+ Discover exclusive benefits and features available only to our monthly sponsors
+
+ ---
+
+ [:octicons-arrow-right-24: More infomation][What's in it for you]
+
+- :fontawesome-solid-people-group:
+ __Who is sponsoring__
+
+ ---
+
+ Get to know our awesome sponsors, financially backing Material for MkDocs
-New features are added every other week. Be sure to come back.
-
-## How to become a sponsor
-
-Thanks for your interest in sponsoring! In order to become an eligible sponsor
-with your GitHub account, visit [squidfunk's sponsor profile], and complete
-a sponsorship of __$15 a month or more__. You can use your individual or
-organization GitHub account for sponsoring.
-
-__Important__: If you're sponsoring @squidfunk through a GitHub organization,
-please send a short email to sponsors@squidfunk.com with the name of your
-organization and the GitHub account of the individual that should be added as a
-collaborator.[^4]
-
-You can cancel your sponsorship anytime.[^5]
-
- [^4]:
- It's currently not possible to grant access to each member of an
- organization, as GitHub only allows for adding users. Thus, after
- sponsoring, please send an email to sponsors@squidfunk.com, stating which
- account should become a collaborator of the Insiders repository. We're
- working on a solution which will make access to organizations much simpler.
- To ensure that access is not tied to a particular individual GitHub account,
- create a bot account (i.e. a GitHub account that is not tied to a specific
- individual), and use this account for the sponsoring. After being added to
- the list of collaborators, the bot account can create a private fork of the
- private Insiders GitHub repository, and grant access to all members of the
- organizations.
-
- [^5]:
- If you cancel your sponsorship, GitHub schedules a cancellation request
- which will become effective at the end of the billing cycle. This means
- that even though you cancel your sponsorship, you will keep your access to
- Insiders as long as your cancellation isn't effective. All charges are
- processed by GitHub through Stripe. As we don't receive any information
- regarding your payment, and GitHub doesn't offer refunds, sponsorships are
- non-refundable.
-
-[:octicons-heart-fill-24:{ .mdx-heart } Join our awesome sponsors][squidfunk's sponsor profile]{ .md-button .md-button--primary .mdx-sponsorship-button }
-
-
-
-
-
-
- If you sponsor publicly, you're automatically added here with a link to
- your profile and avatar to show your support for Material for MkDocs.
- Alternatively, if you wish to keep your sponsorship private, you'll be a
- silent +1. You can select visibility during checkout and change it
- afterwards.
-
+### Sponsoring guide
+
+Learn how to become a sponsor of Material for MkDocs Insiders and start your
+sponsorship journey by choosing the right tier for you:
+
+
+
+
+- :material-animation-outline:
+ __Sponsoring tiers__
+
+ ---
+
+ Find the perfect monthly sponsoring tier that fits your needs and
+ requirements
+
+ ---
+
+ [:octicons-arrow-right-24: More information][Sponsoring tiers]
+
+- :octicons-heart-fill-24:{ .mdx-heart }
+ __How to sponsor__
+
+ ---
+
+ Follow our step-by-step guide on how to become a sponsor to get you started
+
+ ---
+
+ [:octicons-arrow-right-24: More information][How to sponsor]
+
- [squidfunk's sponsor profile]: https://github.com/sponsors/squidfunk?metadata_origin=docs
-
-## Funding
-
-### Goals
-
-The following section lists all funding goals. Each goal contains a list of
-features prefixed with a checkmark symbol, denoting whether a feature is
-:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or
-:octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features
-are released for general availability.
-
-#### $ 14,000 – Goat's Horn
-
-- [x] [Privacy plugin]
-- [x] [Card grids]
-- [x] [Tooltips]
-- [x] [Content tabs: anchor links]
-- [x] [Automatic light / dark mode]
-- [x] [Document contributors]
-
- [Privacy plugin]: ../setup/ensuring-data-privacy.md
- [Card grids]: ../reference/grids.md
- [Tooltips]: ../reference/tooltips.md
- [Content tabs: anchor links]: ../reference/content-tabs.md#anchor-links
- [Automatic light / dark mode]: ../setup/changing-the-colors.md#automatic-light-dark-mode
- [Document contributors]: ../setup/adding-a-git-repository.md#document-contributors
-
-#### $ 16,000 – Chipotle
-
-- [x] [Meta plugin]
-- [x] [Blog plugin: related links]
-- [x] [Blog plugin: custom index pages]
-- [x] [Tags plugin: additional indexes]
-- [x] [Tags plugin: allow list] + [custom sorting]
-- [x] [Navigation subtitles]
-
- [Meta plugin]: ../plugins/meta.md
- [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
- [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
- [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
- [Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed
- [custom sorting]: ../setup/setting-up-tags.md#+tags.tags_compare
- [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
-
-#### $ 20,000 – Jalapeño
-
-- [x] [Optimize plugin]
-- [x] [Typeset plugin]
-- [x] [Navigation path] (Breadcrumbs)
-- [x] [Privacy plugin: optimization support]
-- [x] [Privacy plugin: external links]
-- [x] [Instant prefetching]
-
- [Optimize plugin]: ../plugins/optimize.md
- [Typeset plugin]: ../plugins/typeset.md
- [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
- [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
- [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
- [Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
-
-#### $ 24,000 – Blockpaprika
-
-- [x] [Projects plugin]
-- [x] [Social plugin: custom layouts]
-- [x] [Social plugin: background images]
-- [x] [Code range selection]
-- [x] [Code annotations: custom selectors]
-- [ ] Code line wrap button
-
- [Projects plugin]: ../plugins/projects.md
- [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
- [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
- [Code range selection]: ../reference/code-blocks.md#code-selection-button
- [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
-
-### Goals completed
-
-This section lists all funding goals that were previously completed, which means
-that those features were part of Insiders, but are now generally available and
-can be used by all users.
-
-#### $ 12,000 – Piri Piri
-
-- [x] [Blog plugin]
-- [x] [Chinese search support]
-- [x] [Annotations]
-- [x] [Navigation icons]
-- [x] [Navigation pruning]
-- [x] [Navigation status]
-
- [Blog plugin]: ../setup/setting-up-a-blog.md
- [Chinese search support]: ../blog/posts/chinese-search-support.md
- [Annotations]: ../reference/annotations.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
+### Additional information
-#### $ 10,000 – Carolina Reaper
+If you require additional and detailed information about payment, billing,
+access management, and more, here is everything you need to know:
-- [x] [Brand new search plugin]
-- [x] [Rich search previews]
-- [x] [Tokenizer with lookahead]
-- [x] [Advanced search highlighting]
-- [x] [Excluding content from search]
-- [x] [Offline plugin]
-
- [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
-
-#### $ 8,000 – Scotch Bonnet
-
-- [x] [Social cards]
-- [x] Code annotations: anchor links
-- [x] [Code annotations: strip comments]
-- [x] [Tag icons]
-- [x] [Table of contents anchor following]
-- [x] Sidebars automatically scroll to active item
-
- [Social cards]: ../setup/setting-up-social-cards.md
- [Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
- [Tag icons]: ../setup/setting-up-tags.md#tag-icons-and-identifiers
- [Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following
+
-#### $ 7,000 – Royal Gold
+- :material-hand-coin:
+ __Payment and billing__
-- [x] [Cookie consent]
-- [x] [Was this page helpful?]
-- [x] [Dismissable announcement bar]
+ ---
- [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
+ All the information you need about payment methods and billing cycles
-#### $ 6,000 – Trinidad Scorpion
+ ---
-- [x] [Boosting pages in search]
-- [x] [Custom admonition icons]
-- [x] [Linking content tabs]
+ [:octicons-arrow-right-24: More infomation][Payment and billing]
- [Boosting pages in search]: ../setup/setting-up-site-search.md#search-boosting
- [Custom admonition icons]: ../reference/admonitions.md#admonition-icons
- [Linking content tabs]: ../reference/content-tabs.md#linked-content-tabs
+- :material-key-variant:
+ __Access management__
-#### $ 5,000 – Aji Panca
+ ---
-- [x] [Mermaid.js integration]
-- [x] Stay on page when switching versions
-- [x] [Tags with search integration]
+ Learn about access management to Insiders – for individuals and
+ organizations
- [Mermaid.js integration]: ../reference/diagrams.md
- [Tags with search integration]: ../setup/setting-up-tags.md
+ ---
-#### $ 4,000 – Ghost Pepper
+ [:octicons-arrow-right-24: More infomation][Access management]
-- [x] [Anchor tracking]
-- [x] [Code annotations]
-- [x] [Version warning]
+- :material-clock-time-three:
+ __Runtime and cancellation__
- [Anchor tracking]: ../setup/setting-up-navigation.md#anchor-tracking
- [Code annotations]: ../reference/code-blocks.md#adding-annotations
- [Version warning]: ../setup/setting-up-versioning.md#version-warning
+ ---
-#### $ 3,000 – Caribbean Red
+ Receive information on the duration of your sponsorship and the cancellation
+ process
-- [x] [Sticky navigation tabs]
-- [x] [Section index pages]
-- [x] [Remove generator notice]
+ ---
- [Sticky navigation tabs]: ../setup/setting-up-navigation.md#sticky-navigation-tabs
- [Section index pages]: ../setup/setting-up-navigation.md#section-index-pages
- [Remove generator notice]: ../setup/setting-up-the-footer.md#generator-notice
+ [:octicons-arrow-right-24: More information][Runtime and cancellation]
-#### $ 2,500 – Biquinho Vermelho
+- :material-lock-open:
+ __Privacy__
-- [x] [Search suggestions]
-- [x] [Search highlighting]
-- [x] [Search sharing]
+ ---
- [Search suggestions]: ../setup/setting-up-site-search.md#search-suggestions
- [Search highlighting]: ../setup/setting-up-site-search.md#search-highlighting
- [Search sharing]: ../setup/setting-up-site-search.md#search-sharing
+ Our commitment to your privacy – learn assurances on valuing your privacy
-#### $ 2,000 – Black Pearl
+ ---
-- [x] Latest release tag
-- [x] [Color palette toggle]
-- [x] [Back-to-top button]
+ [:octicons-arrow-right-24: More infomation][Privacy]
- [Color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
- [Back-to-top button]: ../setup/setting-up-navigation.md#back-to-top-button
+- :material-briefcase:
+ __License__
-#### $ 1,500 – Bhut Jolokia
+ ---
-- [x] [Admonition inline blocks]
-- [x] [Site language selection]
-- [x] [Versioning]
+ Get details on the licensing of Material for MkDocs Insiders and its requirements
- [Admonition inline blocks]: ../reference/admonitions.md#inline-blocks
- [Site language selection]: ../setup/changing-the-language.md#site-language-selector
- [Versioning]: ../setup/setting-up-versioning.md#versioning
+ ---
-#### $ 1,000 – Prairie Fire
+ [:octicons-arrow-right-24: More infomation][License]
-- [x] [Navigation sections]
-- [x] [Navigation expansion]
-- [x] [Hiding the sidebars]
-- [x] [Table of contents in navigation]
-- [x] [Header hides on scroll]
+- :material-email:
+ __Support__
- [Navigation sections]: ../setup/setting-up-navigation.md#navigation-sections
- [Navigation expansion]: ../setup/setting-up-navigation.md#navigation-expansion
- [Hiding the sidebars]: ../setup/setting-up-navigation.md#hiding-the-sidebars
- [Table of contents in navigation]: ../setup/setting-up-navigation.md#navigation-integration
- [Header hides on scroll]: ../setup/setting-up-the-header.md#automatic-hiding
+ ---
-#### $ 500 – Madame Jeanette
+ Overview of our support options available, ensuring you get the information
+ you need
-- [x] Improved search result grouping
-- [x] Improved search result relevance and scoring
-- [x] Missing query terms in search results
+ ---
-## Frequently asked questions
+ [:octicons-arrow-right-24: More information][Support]
-### Compatibility
+
+
+### Using Insiders
+
+Once you have become a sponsor, you can start using Material for MkDocs Insiders,
+get all the information you need to get started:
-_We're building an open source project and want to allow outside collaborators
-to run and build our documentation locally without having access to Insiders.
-Is this still possible?_
+
-Yes. Insiders is compatible with Material for MkDocs. Almost all new features
-and configuration options are either backward-compatible or implemented behind
-feature flags. When working with outside collaborators, it should be rarely
-necessary to change the general appearance of your site. Most Insiders features
-enhance the overall experience, e.g. by adding icons to pages or providing a
-feedback widget. While these features add value for the user of your site, they
-shouldn't be necessary for previewing when making changes to content. Currently,
-the only content-related features in Insiders that can't be properly previewed
-by non-Insiders users are:
+- :material-download:
+ __Getting started__
-- [Annotations]
-- [Card grids]
+ ---
-This means that outside collaborators are able to build the documentation
-locally with Material for MkDocs and when they push their changes, your CI
-pipeline will build it with Insiders. When using built-in plugins that are
-exclusive to Insiders, it's recommended to split configuration into a base
-`mkdocs.yml` and one with plugin overrides via [configuration inheritance].
+ Step-by-step instructions on how to install Material for MkDocs Insiders
-See the [getting started guide] for more information.
+ ---
- [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
- [getting started guide]: getting-started.md#caveats
+ [:octicons-arrow-right-24: More information][Getting started]
-### Payment
+- :octicons-versions-16:
+ __Changelog__
-_We don't want to pay for sponsorship every month. Are there any other options?_
+ ---
-Yes. You can sponsor on a yearly basis by [switching your GitHub account to a
-yearly billing cycle][billing cycle]. If for some reason you cannot do that, you
-could also create a dedicated GitHub account with a yearly billing cycle, which
-you only use for sponsoring (some sponsors already do that).
+ Review the latest changes and additions to Material for MkDocs Insiders
-If you have any problems or further questions, please reach out to
-sponsors@squidfunk.com.
+ ---
- [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+ [:octicons-arrow-right-24: More infomation][Changelog]
-### Terms
+- :material-update:
+ __Upgrade__
-_Are we allowed to use Insiders under the same terms and conditions as
-Material for MkDocs?_
+ ---
-Yes. Whether you're an individual or a company, you may use _Material for MkDocs
-Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license]. However, we kindly ask you to respect our
-__fair use policy__:
+ Stay updated with the latest changes and improvements in the Insiders
+ edition
-- Please __don't distribute the source code__ of Insiders. You may freely use
- it for public, private or commercial projects, privately fork or mirror it,
- but please don't make the source code public, as it would counteract the
- sponsorware strategy.
+ ---
-- If you cancel your subscription, you're automatically removed as a
- collaborator and will miss out on all future updates of Insiders. However, you
- may __use the latest version__ that's available to you __as long as you like__.
- Just remember that [GitHub deletes private forks].
+ [:octicons-arrow-right-24: More infomation][Upgrade]
+
+
- [MIT license]: ../license.md
- [GitHub deletes private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+ [Why sponsor us]: why-sponsor-us.md
+ [What's in it for you]: benefits.md
+ [Who is sponsoring]: our-sponsors.md
+ [Sponsoring tiers]: sponsoring-tiers.md
+ [How to sponsor]: how-to-sponsor.md
+ [Payment and billing]: payment-and-billing.md
+ [Access management]: access-management.md
+ [Runtime and cancellation]: runtime-and-cancellation.md
+ [Privacy]: privacy.md
+ [License]: license.md
+ [Support]: ../support.md
+ [Getting started]: getting-started.md
+ [Changelog]: ../changelog/index.md
+ [Upgrade]: upgrade.md
+
+----
+
+__We're looking forward to welcoming you as a sponsor!__
diff --git a/docs/insiders/license.md b/docs/insiders/license.md
new file mode 100644
index 00000000000..268aa5ef7f9
--- /dev/null
+++ b/docs/insiders/license.md
@@ -0,0 +1,67 @@
+# License
+
+Material for MkDocs Insiders is licensed under the [MIT license], the exact
+same license used for the community edition. The MIT license is a permissive
+license that allows commercial use, redistribution, and everything else as
+long as the original authors are credited in source files.
+
+The MIT license is the [most popular license] among all Open Source projects.
+
+ [MIT license]: https://opensource.org/license/mit
+ [most popular license]: https://opensource.org/blog/the-most-popular-licenses-for-each-language-2023
+
+## MIT License
+
+The MIT License gives you the freedom to work with the code with minimal
+restrictions. When using Material for MkDocs Insiders or the community edition,
+make sure to __include the copyright notice__ and avoid future liability claims.
+Its appeal lies in its simplicity and clear terms, making it a go-to for
+projects of any scale. Its popularity stems from its simplicity, clarity,
+and development-friendly terms, making it suitable for all types of projects.
+The MIT License ensures that anyone – individual or organization – can use
+Material for MkDocs Insiders under the same conditions as the community edition.
+
+### Advantages of MIT
+
+The MIT License is favored for its balance between freedom and protection,
+appealing to those who find GNU/GPL licenses too restrictive or advocate for
+privatized software. Its broad wording supports both open community development
+and the use of components in proprietary software.
+
+### MIT in open source
+
+Material for MkDocs stands out for being open source, developed by a small,
+user-oriented team committed to delivering high-quality tools for the community.
+Here’s what this means for you:
+
+- __Independence from investors:__ Our focus is purely on developing the
+project and guiding it without external pressures. This freedom means we’re all
+about what’s best for the community and the project's future.
+- __Freedom from vendor lock-in:__ Thanks to Open Source principles, you can use
+Material for MkDocs without any strings attached. Customize or integrate it
+into your projects without worrying about restrictions. Your docs belong to you,
+and you are free to change the software at any time.
+- __Ecosystem Development:__ Material for MkDocs is more than a tool; it's a
+community-driven effort to build an ecosystem, which it already is. Through open
+collaboration, we’re constantly adding new extensions, plugins, and integrations
+to give you more tools at your disposal.
+
+## Fair use policy
+
+Our fair use policy is here to ensure the project continues to thrive, which is
+why we request that our sponsors respect the following:
+
+- __Source Code Distribution:__ Keeping our sponsorware model intact means we
+count on you not to distribute the Insiders source code. While you're encouraged
+to privately [fork], or [mirror] the private Insiders repository for your needs,
+__keeping the source private__ is key. If this guideline is violated,
+everybody loses, as it will reduce the time of us maintainers we could otherwise
+set aside to push this project forward.
+- __Sponsorship tiers:__ We base our sponsorship tiers on non-commercial or
+commercial use and ask our sponsors to respect these requirements when
+initiating a sponsorship. Additionally, we base our sponsoring tiers on the number
+of sites you intend to build. Please upgrade your sponsorship accordingly to
+support the project’s growth and ensure its continued development.
+
+ [fork]: access-management.md/#forking
+ [mirror]: access-management.md/#mirroring
diff --git a/docs/insiders/our-sponsors.md b/docs/insiders/our-sponsors.md
new file mode 100644
index 00000000000..d096dcedf5e
--- /dev/null
+++ b/docs/insiders/our-sponsors.md
@@ -0,0 +1,131 @@
+# Our sponsors
+
+Starting in 2020, we have managed to build a community of a few hundred sponsors
+that support us every month, for which we are immensely grateful. Without their
+financial support, Material for MkDocs wouldn't be anywhere near where it is
+today.
+
+
+
+
+ If you sponsor publicly, you're automatically added here with a link to
+ your profile and avatar to show your support for Material for MkDocs.
+ Alternatively, if you wish to keep your sponsorship private, you'll be a
+ silent +1. You can select visibility during checkout and change it
+ afterwards.
+
+
diff --git a/docs/insiders/payment-and-billing.md b/docs/insiders/payment-and-billing.md
new file mode 100644
index 00000000000..957551c860f
--- /dev/null
+++ b/docs/insiders/payment-and-billing.md
@@ -0,0 +1,94 @@
+# Payment and billing
+
+Since we host our repositories on GitHub, including both the Material for MkDocs
+community edition and the private Insiders edition, [GitHub Sponsors] is a
+natural fit for handling all financial transactions, as well as for access
+management to the Insiders repository.
+
+Therefore, to become a sponsor of Material for MkDocs, a [GitHub account] is mandatory.
+
+ [GitHub Sponsors]: https://github.com/sponsors
+ [GitHub account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
+
+## Payment
+
+GitHub Sponsors currently only accepts payments via credit card, as they
+[removed support for PayPal] at the beginning of 2023. When
+entering your credit card details, ensure that the card remains [valid over an
+extended period] to prevent any disruptions to your sponsorship.
+
+ [valid over an extended period]: runtime-and-cancellation.md#automatic-cancellation
+ [removed support for PayPal]: https://github.blog/changelog/2023-01-23-github-sponsors-will-stop-supporting-paypal/
+
+## Invoices
+
+GitHub Sponsors automatically issues and send a payment receipt via email after
+each billing cycle. These receipts serve as confirmation of payment rather than
+formal invoices. As all transactions are managed by [GitHub Sponsors], GitHub is
+your primary point of contact for payment and billing matters, not us.
+
+If you need an official invoice from us for your records, please get in touch
+with us at sponsors@squidfunk.com before initiating your sponsorship.
+
+## Refunds
+
+Our team does not have insights or access to details related to sponsorship
+transactions of our sponsors, as GitHub does not provide us with this
+information. For questions regarding payment issues or for more detailed
+information about your sponsorship, please get in touch with the [GitHub
+support] team.
+
+ [GitHub support]: https://support.github.com/
+
+## Discounts
+
+Unfortunately, we can't offer discounts. To ensure that everyone in our
+community can afford to become a sponsor, we keep the barrier low and set
+prices as low as possible, starting at [\$15 a month][15] for
+[non-commercial use] and at [\$125 a month][125] for [commercial use].
+
+ [15]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+ [125]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210643
+ [non-commercial use]: sponsoring-tiers.md/#non-commercial-use
+ [commercial use]: sponsoring-tiers.md/#commercial-use
+
+## Free access
+
+Free access to the Insiders edition is only granted exclusively to our [Community
+Experts] and to selected members of the MkDocs ecosystem. Our Community Experts
+program is designed to recognize and reward users who significantly contribute
+to the community by sharing their expertise on our [discussion board].
+
+Our discussion board facilitates the exchange of insights on workarounds, setups,
+and features and addresses queries from users at all levels of experience. All
+communication is public and visible for the entire community, benefitting
+everyone.
+
+Community experts not only enrich our project but also enable our team to focus
+on continuous improvement and the development of new features. Therefore, we are
+happy to provide them with free access to the private Insiders repository and
+encourage you to [join the team] as well!
+
+ [community experts]: community-experts-program/index.md
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [join the team]: community-experts-program/index.md/#ready-to-get-started
+
+## Billing cycle
+
+The [billing cycle] is an account-level setting on GitHub and is set to monthly
+or yearly. It can be changed at any time, so you might want to check the setting
+before sponsoring and change it either to monthly or yearly according to your
+own or your organization's preferences.
+
+If, for whatever reason, you cannot change your billing cycle, a practical
+solution is to create a dedicated [GitHub bot account] where you set the billing
+cycle accordingly and use it specifically for your sponsorship contributions.
+This is a strategy many of our organizational sponsors have successfully
+implemented.
+
+If you experience any difficulties or have further questions before sponsoring,
+please don't hesitate to contact us at sponsors@squidfunk.com for additional
+support.
+
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+ [GitHub bot account]: https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
diff --git a/docs/insiders/privacy.md b/docs/insiders/privacy.md
new file mode 100644
index 00000000000..f4b1f13a5ff
--- /dev/null
+++ b/docs/insiders/privacy.md
@@ -0,0 +1,79 @@
+# Privacy
+
+Transparency is at the heart of our sponsorware model, which includes our
+funding goals, the features we're working towards, and, importantly, the
+acknowledgment of our sponsors. As a sponsor, you can support our project
+either [publicly] or [privately], according to your preference.
+
+ [publicly]: #public-sponsors
+ [privately]: #private-sponsors
+
+## Public sponsors
+
+By default, GitHub lists all sponsorships publicly. To sponsor privately, you
+must explicitly select this option. When sponsoring publicly, your GitHub
+account will be listed as part of [our sponsors], @squidfunk's [sponsoring page],
+and within the "sponsoring" section of your GitHub account.
+
+ [our sponsors]: our-sponsors.md
+ [sponsoring page]: https://github.com/sponsors/squidfunk?metadata_origin=docs
+
+## Private sponsors
+
+For those preferring discretion, [setting your sponsorship to private] during
+the sponsorship initiation process ensures your sponsorship remains unlisted,
+keeping your affiliation with Material for MkDocs confidential.
+
+This setting can be adjusted at any time through your GitHub account's
+sponsorship settings.
+
+For companies concerned about being visible as sponsors of any project due to
+their privacy restrictions, creating a [bot account] on GitHub that is solely
+used for sponsoring is advised. This account, set to sponsor privately, won't be
+linked to any individual within your organization and provides an extra layer of anonymity.
+
+ [setting your sponsorship to private]: https://docs.github.com/en/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship#managing-the-privacy-setting-for-your-sponsorship
+ [bot account]: access-management.md/#bot-account
+
+## Administrative requests
+
+To focus on the development of our projects, we aim to reduce administrative
+tasks as much as possible for our small team, utilizing GitHub Sponsors for
+efficient sponsor management.
+
+### Vendor agreements
+
+Since GitHub Sponsors facilitates our sponsor transactions, they act as your
+vendor. For vendor agreements or related queries, especially for organizations
+with GitHub enterprise accounts, reaching out to [GitHub Support] is recommended.
+
+ [GitHub Support]: https://github.com/sponsors
+
+### Non-disclosure agreements
+
+Given our limited resources as a small team, we are unable to review and sign
+NDAs. We advise those requiring such agreements to consult [our promise] for
+reassurance. Additionally, please contact us if you have any questions at
+sponsors@squidfunk.com
+
+ [our promise]: #our-promise
+
+## Our promise
+
+We recognize the importance of privacy for our organizational sponsors,
+especially in the absence of formal agreements like [NDAs]. "Our Promise" is our
+assurance of commitment to your confidentiality and discretion.
+
+- __Confidential sponsorship:__ Your choice between public or private
+sponsorship is respected to the fullest. For private sponsors, we guarantee your
+relation with us remains confidential at all times, ensuring no public disclosure
+of your sponsorship.
+- __Logo usage and brand representation:__ Logo display and any form of public
+acknowledgment are completely under your control and will only proceed with your
+explicit consent. This ensures your brand is represented on your terms.
+- __Marketing and communication:__ We commit not to use the details of your
+sponsorship for marketing or promotional purposes without your approval.
+Your sponsorship details are guarded with the highest level of confidentiality,
+with no unauthorized use or disclosure.
+
+ [NDAs]: #non-disclosure-agreements
diff --git a/docs/insiders/runtime-and-cancellation.md b/docs/insiders/runtime-and-cancellation.md
new file mode 100644
index 00000000000..0b74f0c3212
--- /dev/null
+++ b/docs/insiders/runtime-and-cancellation.md
@@ -0,0 +1,58 @@
+# Runtime and cancellation
+
+The sponsorship model for Material for MkDocs is facilitated through GitHub
+Sponsors and, therefore, adheres to GitHub's policies. If you're curious about
+the duration of your sponsorship and the cancellation process, you will find
+everything you need to know below.
+
+## Runtime
+
+Sponsorships remain valid as long as monthly or yearly subscriptions are
+active and only expire when you cancel the sponsorship or when your [payment
+method expires].
+
+ [payment method expires]: #automatic-cancellation
+
+## Cancellation process
+
+Canceling your sponsorship initiates a cancellation request through GitHub,
+which is scheduled to take effect at the end of your current billing cycle. This
+means you'll retain access to Insiders until the cancellation officially becomes
+effective.
+
+All transactions are processed by GitHub and as we don't receive any information
+regarding your payment, we can't provide details about when your cancellation
+will be in place.
+
+### How to cancel
+
+To downgrade or cancel your sponsorship, please follow the [step-by-step guide
+from GitHub]. If you have sponsored using an organizational account, ensure that
+you cancel the sponsorship under that specific account, as the
+[collaborator and sponsor accounts may differ].
+
+ [step-by-step guide from GitHub]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship#canceling-a-sponsorship
+ [collaborator and sponsor accounts may differ]: access-management.md/#collaborators
+
+### Effects of cancellation
+
+Upon the effective date of your cancellation, GitHub will automatically remove
+you as a collaborator from the private Material for MkDocs Insiders repository.
+You will no longer receive updates. However, you are welcome to continue using
+the latest version available to you at the time of cancellation for as long as
+you like.
+
+!!! warning "GitHub deletes private forks"
+
+ Please note that once you lose your collaborator status, [GitHub will
+ automatically delete your private fork] of the Insiders repository, so you
+ may want to take steps to ensure that you have a local backup.
+
+ [GitHub will automatically delete your private fork]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository#deleting-forks-of-private-repositories
+
+### Automatic cancellation
+
+If your credit card expires, GitHub will automatically cancel your sponsorship
+and remove you as a collaborator. Regularly checking your payment method is
+recommended to avoid unintended cancellations. If it happens, you can
+reinstate your sponsorship with a new credit card.
diff --git a/docs/insiders/sponsoring-tiers.md b/docs/insiders/sponsoring-tiers.md
new file mode 100644
index 00000000000..742e352c716
--- /dev/null
+++ b/docs/insiders/sponsoring-tiers.md
@@ -0,0 +1,229 @@
+# Sponsoring tiers
+
+We offer a range of sponsoring tiers tailored to the diverse needs of our
+community. Whether you're an individual user, or rooted in academia, or work in
+an organization using our software commercially, there's a sponsoring tier
+that suits your needs.
+
+## Choosing a tier
+
+Choosing the right sponsoring tier depends on your needs and how you intend to
+use Material for MkDocs Insiders. Our tiers are categorized into [non-commercial]
+and [commercial] use:
+
+ - __Non-commercial tiers__: Intended for individuals, Open Source projects,
+ and academic use
+ - __Commercial tiers__: Designed for organizations and enterprises of any size
+
+Each [monthly sponsoring tier] offers a range of benefits tailored to your needs.
+Benefits include access to our private Material for MkDocs Insiders repository,
+priority handling of bug reports, and more, which vary by the number of
+projects[^1] that you intend to build with it and collaborators required.
+Remember, you can always [upgrade or downgrade] your
+sponsorship level at any time.
+
+ [^1]:
+ A project is defined as a folder with a `mkdocs.yml` configuration file
+ that is built with Material for MkDocs Insiders. This is the only limitation
+ to follow – the number of documentation pages or the size of your project
+ is up to you.
+
+ [monthly sponsoring tier]: #monthly-sponsoring
+ [non-commercial]: #non-commercial-use
+ [commercial]: #commercial-use
+ [upgrade or downgrade]: #switching-tiers
+
+## Monthly sponsoring
+
+Monthly sponsoring tiers provide you with access to our private Material for
+MkDocs Insiders repository. Your financial contribution supports the ongoing
+development of both the Insiders and the community edition.
+
+### Non-commercial use
+
+Non-commercial use essentially means "personal use". This includes individuals
+using the Insiders edition for personal or purely non-commercial Open Source
+projects. We offer two different tiers for non-commercial use.
+
+---
+
+#### The Individual
+
+You love Material for MkDocs and use it for your Open Source project or personal
+blog. You read about all the awesome features in Insiders, which are first
+exclusively released to sponsors, and don't want to miss out.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-charity: Non-commercial use for __1-2 projects__
+
+[ Sponsor with __$15 a month__ ][15 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [15 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+
+---
+
+#### The Dedicated Individual
+
+You use Material for MkDocs for several of your Open Source projects or personal
+sites, and just love that you can build beautiful documentation without having
+to worry about the constantly breaking JavaScript ecosystem – this is now
+[@squidfunk's] job.
+
+ [@squidfunk's]: https://github.com/squidfunk
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-charity: Non-commercial use for __3+ projects__
+
+[ Sponsor with __$35 a month__ ][35 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [35 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210641
+
+---
+
+### Commercial use
+
+Commercial use refers to any use of our software for a business or for-profit
+purpose. This includes any use by a corporation or other organization, whether
+or not they generate revenue directly from the software. We offer different
+pricing tiers for commercial use, each tailored to the needs of different
+businesses. It's important to note that internal use of the software within your
+organization is also considered commercial use, as with all commercial software.
+
+---
+
+#### The Organization :star:
+
+Your organization uses Material for MkDocs for its documentation or internal
+knowledge base and wants to make sure that it is well-maintained and safe to use
+for the years to come. You agree that $125 a month (less than 1 hour of a
+skilled developer) is a clever investment into a solution, solving tons of
+problems you don't want to fight yourself.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-currency-usd: Commercial use for __1-9 projects__
+ - :material-run-fast: Your bug reports are __prioritized__
+ - :material-star: Backlink + placement of __small logo__
+
+[ Sponsor with __$125 a month__ ][125 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [125 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210643
+
+---
+
+#### The Global Organization :star::star:
+
+Your organization runs many internal and public-facing sites that are built with
+Material for MkDocs, helping you to share and manage knowledge efficiently.
+You've evaluated several commercial alternatives which will cost you 3-4x more,
+some of which with a smaller feature set. You agree that $250 a month (less than
+2 hours of a skilled developer) is a very good deal for the value you're getting
+out of it.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-currency-usd: Commercial use for __10-49 projects__
+ - :material-run-fast: Your bug reports are __prioritized__
+ - :material-star: Backlink + placement of __logo__
+
+[ Sponsor with __$250 a month__ ][250 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [250 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=181282
+
+---
+
+#### The Holistic Organization :star::star::star:
+
+Your organization's day-to-day operations critically depend on Material for
+MkDocs, and you need to make sure that bugs are fixed quickly to keep your
+customers happy. You see your work as part of a larger ecosystem, realizing that
+giving back is essential to keeping everything you fight for alive.
+
+__Rewards:__
+
+ - :material-door-open: Access to Insiders
+ - :material-currency-usd: Commercial use for __50+ projects__
+ - :material-run-fast: Your bug reports are __prioritized__
+ - :material-star: Backlink + placement of __large logo__
+ - :material-face-agent: Private __email support__
+
+[ Sponsor with __$1,000 a month__ ][1000 a month]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [1000 a month]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=334388
+
+---
+
+## One-time sponsoring
+
+For those who wish to contribute one-time without an ongoing subscription and
+without receiving access to the exclusive Insiders features, we offer the
+following one-time sponsoring tiers.
+
+---
+
+### Just a Tip! :money_with_wings:
+
+You asked a question or needed some help on a problem, and we've helped you
+quickly. You want no perks, just good karma and a warm feeling of giving
+something back.
+
+[ Sponsor __$20 one-time__ ][20 one-time]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [20 one-time]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=222886
+
+---
+
+### The Mentoring
+
+A 1-hour video call with [@squidfunk], the creator and core maintainer of the
+project. He is happy to share his experiences with you and help you with
+anything related to his work.
+
+__Popular topics are:__
+
+ - How to tailor Material for MkDocs to your needs
+ - How to start earning a living in Open Source
+ - How to make your Open Source project sustainable
+
+ [@squidfunk]: https://github.com/squidfunk
+
+[ Sponsor __$350 one-time__ ][350 one-time]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [350 one-time]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210891
+
+---
+
+## Custom amount
+
+You're invited to contribute custom sponsorship amounts via GitHub Sponsors,
+enabling you to support Material for MkDocs according to your preferences.
+Please be aware that individuals need to pledge a minimum of $15 a month to
+access Insiders, whereas organizations are encouraged to sponsor $125 a month or
+more, based on their requirements.
+
+Contributions exceeding these thresholds are highly appreciated. Please note
+that one-time donations, regardless of their size, won't be granted access to
+Insiders due to technical constraints.
+
+## Switching tiers
+
+You can easily switch between different sponsorship tiers — [upgrade] or
+[downgrade] — at any time. Simply visit the @squidfunk's
+[GitHub Sponsors profile] and adjust your sponsorship tier selection. Once
+you've made the change, you'll immediately sponsor at the new tier.
+
+If you exceed the number of projects within your current sponsorship limit, we
+kindly request that you upgrade your sponsorship to a higher tier to retain
+access to Material for MkDocs Insiders. The change takes effect immediately,
+and the amount is prorated based on your [billing cycle].
+
+ [upgrade]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship
+ [downgrade]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship
+ [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+ [GitHub Sponsors profile]: https://github.com/sponsors/squidfunk
diff --git a/docs/insiders/upgrade.md b/docs/insiders/upgrade.md
index d576dd5014a..ec86ad9701a 100644
--- a/docs/insiders/upgrade.md
+++ b/docs/insiders/upgrade.md
@@ -34,7 +34,12 @@ need to run different commands:
latest development version, run:
```
- pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ pip install --upgrade --force-reinstall git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ ```
+
+ The `--force-reinstall` option serves to make sure `pip` does, in fact,
+ install the latest development version, instead of deciding that nothing
+ is to be done based on the version numbers.
```
=== "git upgrade"
diff --git a/docs/insiders/why-sponsor-us.md b/docs/insiders/why-sponsor-us.md
new file mode 100644
index 00000000000..5b153cc31fc
--- /dev/null
+++ b/docs/insiders/why-sponsor-us.md
@@ -0,0 +1,121 @@
+# Why sponsor us
+
+Material for MkDocs is an Open Source project that is developed and maintained
+by a small team of individuals who want to devote as much time as possible to
+make it better every day. We need to rely on the financial support of
+[our awesome sponsors], who buy us the time to work on it.
+
+ [become a monthly sponsor]: sponsoring-tier.md
+ [our awesome sponsors]: our-sponsors.md
+ [squidfunk's sponsor profile]: https://github.com/sponsors/squidfunk/
+
+## Who we are
+
+While [the project was started] by @squidfunk as a personal side project, the
+[Sponsorware] model that the project adopted in 2020 allowed him to build a
+small team of amazing individuals around him, [who are now helping him] to
+maintain the project, as well as the growing list of sponsors.
+
+ [the project was started]: #how-it-started
+ [sponsorware]: #sponsorware
+ [who are now helping him]: #where-we-are-today
+
+### How it started
+
+In 2015, albeit 10 years in the industry, @squidfunk was still quite new to
+Open Source. Having just finished his latest Open Source project, he realized
+that the project was too complex to be explained in a plain README on GitHub.
+He needed a good documentation tool for this project.
+
+After evaluating static site generators in general and Hugo, Sphinx and MkDocs
+in particular, he quickly decided that MkDocs seemed a good choice, as it was
+specifically aimed at technical project documentation and easy to use.
+Unfortunately, all of the available themes looked dated, and since @squidfunk
+is a very visual person, he just couldn't convince himself to call it a day.
+
+He needed to build a theme.
+
+Months later, in February 2016, [the first version] of Material for MkDocs was
+released. Over the next years, @squidfunk being the sole maintainer, countless
+feature requests were implemented and bugs were fixed, allowing the project to
+gain popularity and reach almost 3,000 stars on GitHub by the end of 2019. It
+is still his most popular project to date.
+
+As the project grew, @squidfunk started to implement feature requests that made
+sense from a general perspective, but not for his personal use. This was the
+point where the project started to shift from a personal project to a
+community-driven one, and began to feel like a secondary job. Having a primary
+job, many maintainers burn out when their side projects become successful, which
+is why @squidfunk decided to give the [Sponsorware] model a try and make
+Material for MkDocs his primary job. This turned out to be an incredible success.
+
+ [the first version]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+
+### Sponsorware
+
+The Sponsorware model is simple – as a sponsor, you get early access to the
+latest and greatest features of Material for MkDocs as part of [Insiders] before
+everyone else gets to enjoy them, as you are the one making them possible with
+your financial contributions.
+
+Every new feature that lands in [Insiders] is linked to a funding goal with a
+specific amount. Once this amount is reached, all of the features that are part
+of this funding goal are merged into the community edition, making them
+available to everyone. It is that simple.
+
+This brand-new and still experimental approach not only helps keep the project
+vibrant and cutting-edge but also ensures it can continue to meet and exceed
+your expectations.
+
+ [Insiders]: index.md
+
+### Where we are today
+
+Fast forward to today, Material for MkDocs is a thriving community-supported
+and well-funded project, with over 500 sponsors and a small but growing team,
+used by international companies and organizations. The project has outgrown
+its original purpose by far, as it has become so much more than just a theme –
+a powerful documentation framework built on top of MkDocs.
+
+Starting in 2020 with the advent of the [Sponsorware] model, the frequency of
+releases has more than doubled, with a new release seeing the light of day on
+average every 1-2 weeks. Moreover, our team responds to issues as fast as
+possible, keeping the number of open issues low.
+
+## Our pledge
+
+We're working hard to make Material for MkDocs one of the best documentation
+tools out there, ridiculously powerful, a pleasure to use and most importantly –
+free and Open Source. It is the financial contributions of our awesome sponsors,
+that allow us to do our best work.
+
+It's a simple equation: as long as this project is funded, we can continue to
+improve it, fix bugs, and add new features. We will continue to provide the
+best possible support to our users and make sure that Material for MkDocs
+remains a tool that you love to use.
+
+If you sponsor us, your contribution helps us to pay for:
+
+1. __Taxes__: Since we provide a service to our sponsors, we're of course
+ legally obligated and happy to pay sales tax. This requirement applies to
+ all sponsorship contributions, aligning us with standard business practices,
+ as for the rest of the world.
+
+2. __Sponsorships__: A significant portion of our funding is redirected to
+ upstream projects. This cultivates collaboration and supports the broader
+ Open Source ecosystem. We regard those projects and their maintainers as
+ essential for the persistence of Material for MkDocs.
+
+3. __Team__: Our team is growing! With more funds available, we can pay more
+ individuals to help us make Material for MkDocs even better. Note that this
+ covers various aspects of the project, like the creation of new features,
+ bug resolution, support, and sponsor relations.
+
+We are bootstrapped – no investors to please! If you decide to support us, you
+help us stay independent and free from outside influence. This means we can
+focus on building a solution that you love to use and keep ownership of your
+documentation project without vendor lock-in.
+
+[ Choose a sponsoring tier ][sponsoring-tiers]{ .md-button .md-button--primary .mdx-sponsorship-button }
+
+ [sponsoring-tiers]: sponsoring-tiers.md
diff --git a/docs/license.md b/docs/license.md
index 9ac1b94f890..83fba873993 100644
--- a/docs/license.md
+++ b/docs/license.md
@@ -2,7 +2,7 @@
**MIT License**
-Copyright (c) 2016-2023 Martin Donath
+Copyright (c) 2016-2024 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
diff --git a/docs/philosophy.md b/docs/philosophy.md
index cff6baaff7e..11b4d99bb40 100644
--- a/docs/philosophy.md
+++ b/docs/philosophy.md
@@ -5,7 +5,7 @@ philosophy behind the project, in order to make sure it aligns with your goals.
This page explains the design principles anchored in Material for MkDocs, and
discusses the [conventions] used in this documentation.
- [conventions]: #conventions
+ [conventions]: conventions.md
## Design principles
@@ -30,6 +30,6 @@ discusses the [conventions] used in this documentation.
documentation with touch devices, keyboard, and screen readers. Semantic
markup ensures that your documentation works for everyone.
-- __Open Source__: Trust 20,000+ users – choose a mature and well-funded
+- __Open Source__: Trust 45,000+ users – choose a mature and well-funded
solution built with state-of-the-art Open Source technologies. Keep ownership
of your content without fear of vendor lock-in. Licensed under MIT.
diff --git a/docs/plugins/blog.md b/docs/plugins/blog.md
index 6eac717d7b5..e1e41270cfe 100644
--- a/docs/plugins/blog.md
+++ b/docs/plugins/blog.md
@@ -153,6 +153,35 @@ installed.
[blog]: blog.md
[built-in plugins]: index.md
+### Navigation
+
+If you do not have site navigation configured in your `mkdocs.yml` then there is
+nothing more to do. The blog [archive] and [category] pages will automatically
+appear underneath the automatically generated navigation.
+
+If you do have a navigation structure defined then you will need to specify
+where the blog should appear in this. Create a [navigation section with an index
+page] for the blog:
+
+```yaml
+theme:
+ name: material
+ features:
+ - navigation.indexes
+nav:
+ - ...
+ - Blog:
+ - blog/index.md
+```
+
+The [archive] and [category] pages will appear within that section as
+subsections beneath pages in the blog section. In this case, they would appear
+after `index.md`. The path to the `index.md` file must match
+[blog_dir][config.blog_dir]. This means that you can name the blog navigation
+entry anything you like: 'Blog' or 'News' or perhaps 'Tips'.
+
+[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages
+
### General
The following settings are available:
@@ -213,9 +242,8 @@ The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
Use this setting to leverage the table of contents to display post titles in
-views. The value of this setting is inherited by [`archive_toc`]
-[config.archive_toc] and [`categories_toc`][config.categories_toc],
-unless they are explicitly set:
+views. This might be useful, if your post excerpts are rather long. If you want
+to enable it, use:
``` yaml
plugins:
@@ -265,7 +293,7 @@ Use this setting to change the date format of posts. This plugin uses [babel]
to render dates in the configured [site language]. You can use [babel]'s
[pattern syntax] or the following shortcodes:
-=== "Monday, January 31, 2023"
+=== "Monday, January 31, 2024"
``` yaml
plugins:
@@ -273,7 +301,7 @@ to render dates in the configured [site language]. You can use [babel]'s
post_date_format: full
```
-=== "January 31, 2023"
+=== "January 31, 2024"
``` yaml
plugins:
@@ -281,7 +309,7 @@ to render dates in the configured [site language]. You can use [babel]'s
post_date_format: long
```
-=== "Jan 31, 2023"
+=== "Jan 31, 2024"
``` yaml
plugins:
@@ -289,7 +317,7 @@ to render dates in the configured [site language]. You can use [babel]'s
post_date_format: medium
```
-=== "1/31/22"
+=== "1/31/24"
``` yaml
plugins:
@@ -315,7 +343,7 @@ Use this setting to change the date format used in post URLs. The format string
must adhere to [babel]'s [pattern syntax] and should not contain whitespace.
Some popular choices:
-=== ":material-link: blog/2023/01/31/:material-dots-horizontal:/"
+=== ":material-link: blog/2024/01/31/:material-dots-horizontal:/"
``` yaml
plugins:
@@ -323,7 +351,7 @@ Some popular choices:
post_url_date_format: yyyy/MM/dd
```
-=== ":material-link: blog/2023/01/:material-dots-horizontal:/"
+=== ":material-link: blog/2024/01/:material-dots-horizontal:/"
``` yaml
plugins:
@@ -331,7 +359,7 @@ Some popular choices:
post_url_date_format: yyyy/MM
```
-=== ":material-link: blog/2023/:material-dots-horizontal:/"
+=== ":material-link: blog/2024/:material-dots-horizontal:/"
``` yaml
plugins:
@@ -354,7 +382,7 @@ Use this setting to change the format string that is used when generating post
URLs. You can freely combine placeholders, and join them with slashes or other
characters:
-=== ":material-link: blog/2023/:material-dots-horizontal:/"
+=== ":material-link: blog/2024/:material-dots-horizontal:/"
``` yaml
plugins:
@@ -406,35 +434,24 @@ If more than one category is given, they are joined with `/` after slugifying.
####
-
-
-Use this setting to change the function to use for generating URL-compatible
-slugs from post titles. [Python Markdown Extensions] comes with a Unicode-aware
-[`slugify`][pymdownx.slugs.slugify] function:
-
-=== "Unicode"
-
- ``` yaml
- plugins:
- - blog:
- post_slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- ```
+
-=== "Unicode, case-sensitive"
+Use this setting to change the function for generating URL-compatible slugs
+from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
- ``` yaml
- plugins:
- - blog:
- post_slugify: !!python/object/apply:pymdownx.slugs.slugify
- ```
+``` yaml
+plugins:
+ - blog:
+ post_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
-When your project features non-European languages, it's advisable to use this
-configuration. Of course, you can also provide a custom slugification function
-for more granular control.
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
- [toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
[pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
@@ -462,9 +479,9 @@ plugins:
-By default, the plugin makes post excerpts optional. When a post doesn't define
-an excerpt, views include the entire post. This setting can be used to make
-post excerpts required:
+By default, the plugin makes [post excerpts](../setup/setting-up-a-blog.md#adding-an-excerpt)
+optional. When a post doesn't define an excerpt, views include the entire post.
+This setting can be used to make post excerpts required:
=== "Optional"
@@ -652,7 +669,7 @@ plugins:
Use this setting to change the date format used for archive page titles. The
format string must adhere to [babel]'s [pattern syntax]. Some popular choices:
-=== "2023"
+=== "2024"
``` yaml
plugins:
@@ -660,7 +677,7 @@ format string must adhere to [babel]'s [pattern syntax]. Some popular choices:
archive_date_format: yyyy
```
-=== "January 2023"
+=== "January 2024"
``` yaml
plugins:
@@ -682,7 +699,7 @@ Use this setting to change the date format used for archive page URLs. The
format string must adhere to [babel]'s [pattern syntax] and should not contain
whitespace. Some popular choices:
-=== ":material-link: blog/archive/2023/"
+=== ":material-link: blog/archive/2024/"
``` yaml
plugins:
@@ -690,7 +707,7 @@ whitespace. Some popular choices:
archive_url_date_format: yyyy
```
-=== ":material-link: blog/archive/2023/01/"
+=== ":material-link: blog/archive/2024/01/"
``` yaml
plugins:
@@ -709,7 +726,7 @@ Use this setting to change the format string that is used when generating
archive page URLs. You can freely combine placeholders, and join them with
slashes or other characters:
-=== ":material-link: blog/archive/2023/"
+=== ":material-link: blog/archive/2024/"
``` yaml
plugins:
@@ -717,7 +734,7 @@ slashes or other characters:
archive_url_format: "archive/{date}"
```
-=== ":material-link: blog/2023/"
+=== ":material-link: blog/2024/"
``` yaml
plugins:
@@ -731,6 +748,42 @@ The following placeholders are available:
---
+####
+
+
+
+
+
+Use this setting to enable or disable pagination for archive pages. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_pagination: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the number of posts rendered per archive page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_pagination_per_page: 5
+```
+
+---
+
####
@@ -738,7 +791,7 @@ The following placeholders are available:
Use this setting to leverage the table of contents to display post titles on all
archive pages. The value of this setting is inherited from [`blog_toc`]
-[config.blog_toc], unless its explicitly set:
+[config.blog_toc], unless it's explicitly set. To change it, use
``` yaml
plugins:
@@ -820,31 +873,23 @@ The following placeholders are available:
####
-
+
-Use this setting to change the function to use for generating URL-compatible
-slugs from categories. [Python Markdown Extensions] comes with a Unicode-aware
-[`slugify`][pymdownx.slugs.slugify] function:
+Use this setting to change the function for generating URL-compatible slugs
+from categories. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
-=== "Unicode"
-
- ``` yaml
- plugins:
- - blog:
- categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- ```
+``` yaml
+plugins:
+ - blog:
+ categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
-=== "Unicode, case-sensitive"
-
- ``` yaml
- plugins:
- - blog:
- categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
- ```
-When your project features non-European languages, it's advisable to use this
-configuration.
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
---
@@ -865,6 +910,46 @@ plugins:
---
+####
+
+
+
+
+
+Use this setting to specify a custom function for sorting categories. For
+example, if you want to sort categories by the number of posts they contain,
+use the following configuration:
+
+``` yaml
+plugins:
+ - blog:
+ categories_sort_by: !!python/name:material.plugins.blog.view_post_count
+```
+
+Don't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].
+You can define your own comparison function, which must return something
+that can be compared while sorting, i.e., a string or number.
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which categories are sorted. By
+default, categories are sorted in ascending order, but you can reverse ordering
+as follows:
+
+``` yaml
+plugins:
+ - blog:
+ categories_sort_reverse: true
+```
+
+---
+
####
@@ -888,6 +973,42 @@ this list. Posts can be assigned to categories by using the [`categories`]
---
+####
+
+
+
+
+
+Use this setting to enable or disable pagination for category pages. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_pagination: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the number of posts rendered per category page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_pagination_per_page: 5
+```
+
+---
+
####
@@ -895,7 +1016,7 @@ this list. Posts can be assigned to categories by using the [`categories`]
Use this setting to leverage the table of contents to display post titles on all
category pages. The value of this setting is inherited from [`blog_toc`]
-[config.blog_toc], unless its explicitly set:
+[config.blog_toc], unless it's explicitly set. To change it, use:
``` yaml
plugins:
@@ -903,6 +1024,195 @@ plugins:
categories_toc: true
```
+### Authors
+
+The following settings are available for authors:
+
+---
+
+####
+
+
+
+
+Use this setting to enable or disable post authors. If this setting is enabled,
+the plugin will look for a file named [`.authors.yml`][config.authors_file] and
+render authors in posts and views. Disable this behavior with:
+
+``` yaml
+plugins:
+ - blog:
+ authors: false
+```
+
+---
+
+####
+
+
+
+
+Use this setting to change the path of the file where the author information for
+your posts resides. It's normally not necessary to change this setting, but if
+you need to, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_file: "{blog}/.authors.yml"
+```
+
+The following placeholders are available:
+
+- `blog` – [`blog` directory][config.blog_dir]
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+!!! info "Format of author information"
+
+ The `.authors.yml` file must adhere to the following format:
+
+ ``` yaml title=".authors.yml"
+ authors:
+ :
+ name: string # Author name
+ description: string # Author description
+ avatar: url # Author avatar
+ slug: url # Author profile slug
+ url: url # Author website URL
+ ```
+
+ Note that `` must be set to an identifier for associating authors
+ with posts, e.g., a GitHub username like `squidfunk`. This identifier can
+ then be used in the [`authors`][meta.authors] metadata property of
+ a post. Multiple authors are supported. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable automatically generated author profiles.
+An author profile shows all posts by an author in reverse chronological order.
+You can enable author profiles with:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the title of the authors section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_name: Authors
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the format string that is used when generating
+author profile URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/author/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_profiles_url_format: "author/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_profiles_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]
+- `name` – Author name from [`authors_file`][config.authors_file]
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable pagination for author profiles. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_pagination: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the number of posts rendered per archive page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_pagination_per_page: 5
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to leverage the table of contents to display post titles on all
+author profiles. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_toc: true
+```
+
### Pagination
The following settings are available for pagination:
@@ -946,7 +1256,7 @@ plugins:
####
-
+
Use this setting to change the format string that is used when generating
paginated view URLs. You can freely combine placeholders, and join them with
@@ -1058,70 +1368,6 @@ plugins:
pagination_keep_content: true
```
-### Authors
-
-The following settings are available for authors:
-
----
-
-####
-
-
-
-
-Use this setting to enable or disable post authors. If this setting is enabled,
-the plugin will look for a file named [`.authors.yml`][config.authors_file] and
-render authors in posts and views. Disable this behavior with:
-
-``` yaml
-plugins:
- - blog:
- authors: false
-```
-
----
-
-####
-
-
-
-
-Use this setting to change the path of the file where the author information for
-your posts resides. It's normally not necessary to change this setting, but if
-you need to, use:
-
-``` yaml
-plugins:
- - blog:
- authors_file: "{blog}/.authors.yml"
-```
-
-The following placeholders are available:
-
-- `blog` – [`blog` directory][config.blog_dir]
-
-The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
-
-!!! info "Format of author information"
-
- The `.authors.yml` file must adhere to the following format:
-
- ``` yaml title=".authors.yml"
- authors:
- :
- name: string # Author name
- description: string # Author description
- avatar: url # Author avatar
- ```
-
- Note that `` must be set to an identifier for associating authors
- with posts, e.g., a GitHub username like `squidfunk`. This identifier can
- then be used in the [`authors`][meta.authors] metadata property of
- a post. Multiple authors are supported. As an example, see
- [the `.authors.yml` file][.authors.yml] we're using for our blog.
-
- [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
-
### Drafts
The following settings are available for drafts:
@@ -1270,7 +1516,7 @@ using a slightly different syntax:
``` yaml
---
- date: 2023-01-31
+ date: 2024-01-31
---
# Post title
@@ -1282,8 +1528,8 @@ using a slightly different syntax:
``` yaml
---
date:
- created: 2023-01-31 # (1)!
- updated: 2023-02-01
+ created: 2024-01-31 # (1)!
+ updated: 2024-02-01
---
# Post title
@@ -1297,8 +1543,8 @@ using a slightly different syntax:
``` yaml
---
date:
- created: 2023-01-31
- my_custom_date: 2023-02-01 # (1)!
+ created: 2024-01-31
+ my_custom_date: 2024-02-01 # (1)!
---
# Post title
@@ -1313,8 +1559,8 @@ using a slightly different syntax:
The following date formats are supported:
-- `2023-01-31`
-- `2023-01-31T12:00:00`
+- `2024-01-31`
+- `2024-01-31T12:00:00`
---
@@ -1339,6 +1585,29 @@ draft: true
---
+####
+
+
+
+
+
+
+
+Use this property to pin a post to the top of a view. In case multiple posts are
+pinned, the pinned posts are sorted by descending order and appear before all
+other posts. Pin a post with:
+
+``` yaml
+---
+pin: true
+---
+
+# Post title
+...
+```
+
+---
+
####
@@ -1386,7 +1655,7 @@ a post. The property follows the same syntax as [`nav`][mkdocs.nav] in
links:
- plugins/search.md # (1)!
- Insiders:
- - insiders/index.md#how-to-become-a-sponsor
+ - insiders/how-to-sponsor.md
- insiders/getting-started.md#requirements
---
diff --git a/docs/plugins/group.md b/docs/plugins/group.md
index 37b41e11d6c..6e17c4c4597 100644
--- a/docs/plugins/group.md
+++ b/docs/plugins/group.md
@@ -64,7 +64,7 @@ The following settings are available:
####
-
+
Use this setting to enable or disable the plugin when [building your project].
@@ -103,7 +103,7 @@ CI=true mkdocs build
####
-
+
Use this setting to list the plugins that are part of the group. The syntax is
diff --git a/docs/plugins/meta.md b/docs/plugins/meta.md
index 3c4f72669c0..5ab849602a7 100644
--- a/docs/plugins/meta.md
+++ b/docs/plugins/meta.md
@@ -10,6 +10,13 @@ pages in a folder, i.e., a subsection of your project, which is particularly
useful to ensure that a certain subset of pages features specific tags, uses a
custom template, or is attributed to an author.
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [our awesome sponsors]: ../insiders/index.md
+
## Objective
### How it works
diff --git a/docs/plugins/optimize.md b/docs/plugins/optimize.md
index a30f7fb3947..231c31eda87 100644
--- a/docs/plugins/optimize.md
+++ b/docs/plugins/optimize.md
@@ -10,7 +10,13 @@ The optimize plugin automatically identifies and optimizes all media files when
As a result, your site loads significantly faster and yields better rankings in
search engines.
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
[building your project]: ../creating-your-site.md#building-your-site
+ [our awesome sponsors]: ../insiders/index.md
## Objective
diff --git a/docs/plugins/privacy.md b/docs/plugins/privacy.md
index d4141ac25b5..47052a1325e 100644
--- a/docs/plugins/privacy.md
+++ b/docs/plugins/privacy.md
@@ -99,8 +99,7 @@ pipelines tailored to your project:
## Configuration
-
-
+
@@ -128,8 +127,7 @@ The following settings are available:
####
-
-
+
Use this setting to enable or disable the plugin when [building your project].
@@ -148,8 +146,7 @@ This configuration enables the plugin only during continuous integration (CI).
####
-
-
+
With more CPUs available, the plugin can do more work in parallel, and thus
@@ -179,8 +176,7 @@ The following settings are available for caching:
####
-
-
+
Use this setting to instruct the plugin to bypass the cache, in order to
@@ -198,8 +194,7 @@ plugins:
####
-
-
+
It is normally not necessary to specify this setting, except for when you want
@@ -218,6 +213,84 @@ with each other.
[multiple instances]: index.md#multiple-instances
+### Logging
+
+The following settings are available for logging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should display log messages when
+building your site. While not being recommended, you can disable logging with:
+
+``` yaml
+plugins:
+ - privacy:
+ log: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`error`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: error
+ ```
+
+ Only errors are reported.
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: warn
+ ```
+
+ Errors and warnings are reported, terminating the build in
+ [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot
+ be created due to a lack of permissions on Windows systems (#6550).
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: info
+ ```
+
+ Errors, warnings and informational messages are reported, including which
+ assets were successfully downloaded by the plugin.
+
+=== "`debug`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: debug
+ ```
+
+ All messages are reported, including debug messages, if and only if MkDocs
+ was started with the `--verbose` flag. Note that this will print a lot of
+ messages and is only useful for debugging.
+
### External assets
The following settings are available for external assets:
@@ -226,8 +299,7 @@ The following settings are available for external assets:
####
-
-
+
Use this setting to control whether the plugin should download external
@@ -246,8 +318,7 @@ plugins:
####
-
-
+
Use this setting to control whether the plugin should downloads or only report
@@ -265,8 +336,7 @@ plugins:
####
-
-
+
It is normally not necessary to specify this setting, except for when you want
@@ -317,7 +387,7 @@ external assets for different origins:
plugins:
- privacy:
assets_exclude: # (1)!
- - cdn.jsdelivr.net/npm/mathjax@3/*
+ - unpkg.com/mathjax@3/*
- giscus.app/*
```
@@ -401,16 +471,34 @@ plugins:
## Limitations
+### Dynamic URLs
+
Dynamically created URLs as part of scripts are not detected, and thus cannot be
downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
``` js
-const cdn = "https://polyfill.io"
-const url = `${cdn}/v3/polyfill.min.js`
+const host = "https://example.com"
+const path = `${host}/script.js`
```
Instead, always use fully qualified URLs:
``` js
-const url ="https://polyfill.io/v3/polyfill.min.js"
+const url ="https://example.com/script.js"
```
+
+### Embedded HTML
+
+By default, embedded HTML files (e.g. in iframes) are not scanned for external
+assets. This is a limitation of MkDocs, as it considers `.html` files to be
+templates, which must be explicitly listed under
+[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets
+of an embedded HTML file:
+
+``` yaml
+extra_templates:
+ - iframe.html
+```
+
+Note that the path to `iframe.html` is relative to the
+[`docs_dir`][mkdocs.docs_dir] directory.
diff --git a/docs/plugins/projects.md b/docs/plugins/projects.md
index e989e7d7d0b..c7327abc639 100644
--- a/docs/plugins/projects.md
+++ b/docs/plugins/projects.md
@@ -10,6 +10,13 @@ distinct projects, build them concurrently and preview them together as one.
This is particularly useful when creating a multi-language project, but can also
be used to split very large projects into smaller parts.
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [our awesome sponsors]: ../insiders/index.md
+
## Objective
### How it works
@@ -52,7 +59,7 @@ There are some [limitations], but we're working hard to remove them.
The plugin came into existence because we needed a convenient and scalable
method to build our [examples] repository, which features many self-contained
and runnable projects that users can download and use as a basis when
-boostrapping a new project or [creating a reproduction].
+bootstrapping a new project or [creating a reproduction].
When you want to create a multi-language project, or have a very large existing
project, you might consider using the plugin, as it makes managing, editing
@@ -176,6 +183,81 @@ plugins:
cache_dir: my/custom/dir
```
+### Logging
+
+The following settings are available for logging:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should display log messages from
+projects when building your site. While not being recommended, you can disable
+logging with:
+
+``` yaml
+plugins:
+ - projects:
+ log: false
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`error`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: error
+ ```
+
+ Only errors are reported.
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: warn
+ ```
+
+ Errors and warnings are reported, terminating the build in
+ [`strict`][mkdocs.strict] mode.
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: info
+ ```
+
+ Errors, warnings and informational messages are reported.
+
+=== "`debug`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: debug
+ ```
+
+ All messages are reported, including debug messages.
+
### Projects
The following settings are available for projects:
diff --git a/docs/plugins/requirements/image-processing.md b/docs/plugins/requirements/image-processing.md
index c53cbf6adb2..c3093152f59 100644
--- a/docs/plugins/requirements/image-processing.md
+++ b/docs/plugins/requirements/image-processing.md
@@ -52,9 +52,17 @@ Material for MkDocs makes use of for generating [social cards] and performing
=== ":fontawesome-brands-windows: Windows"
- As stated in the [installation guide], the easiest way to get up and running
- with the [Cairo Graphics] library on Windows is by installing [GTK+]. You
- can also download a precompiled [GTK runtime].
+ The easiest way to get up and running with the [Cairo Graphics] library is
+ by installing it via [MSYS2], which is a software distribution and building
+ platform for Windows. Run the following command inside of a MSYS2 shell:
+
+ ```
+ pacman -S mingw-w64-ucrt-x86_64-cairo
+ ```
+
+ MSYS2 provides the Cairo Graphics library in several different environments.
+ The above command uses the [UCRT64] environment, as recommended by the MSYS2
+ developers.
=== ":material-linux: Linux"
@@ -88,8 +96,8 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
[Cairo Graphics]: https://www.cairographics.org/
[Homebrew]: https://brew.sh/
[installation guide]: https://www.cairographics.org/download/
- [GTK+]: https://www.gtk.org/docs/installations/windows/
- [GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
+ [MSYS2]: https://www.msys2.org/
+ [UCRT64]: https://www.msys2.org/docs/environments/
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[GitHub Actions]: ../../publishing-your-site.md#with-github-actions
@@ -111,9 +119,13 @@ explains how to install [pngquant] system:
=== ":fontawesome-brands-windows: Windows"
- Installing [pngquant] on Windows is a little more involved. The
- [pngquant-winbuild] repository contains a guide on how to set up an
- environment for building [pngquant] on Windows.
+ The easiest way to get [pngquant] is by installing it via [MSYS2], which is
+ a software distribution and building platform for Windows. Run the following
+ command inside of a MSYS2 shell:
+
+ ```
+ pacman -S mingw-w64-ucrt-x86_64-pngquant
+ ```
=== ":material-linux: Linux"
@@ -134,3 +146,127 @@ The following environments come with a preinstalled version of [pngquant]:
[pngquant]: https://pngquant.org/
[built-in optimize plugin]: ../../plugins/optimize.md
[pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild
+
+## Troubleshooting
+
+### Cairo library was not found
+
+After following the installation guide above it may happen that you still get
+the following error:
+
+```bash
+no library called "cairo-2" was found
+no library called "cairo" was found
+no library called "libcairo-2" was found
+cannot load library 'libcairo.so.2': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
+cannot load library 'libcairo.2.dylib': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
+cannot load library 'libcairo-2.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
+```
+
+This means that the [`cairosvg`][PyPi CairoSVG] package was installed, but the
+underlying [`cairocffi`][PyPi CairoCFFI] dependency couldn't [find][cffi-dopen]
+the installed library. Depending on the operating system the library lookup
+process is different:
+
+!!! tip
+ Before proceeding remember to fully restart any open Terminal windows, and
+ their parent hosts like IDEs to reload any environmental variables, which
+ were altered during the installation process. This might be the quick fix.
+
+=== ":material-apple: macOS"
+
+ On macOS the library lookup checks inside paths defined in [dyld][osx-dyld].
+ Additionally each library `name` is checked in [three variants][find-library-macOS]
+ with the `libname.dylib`, `name.dylib` and `name.framework/name` format.
+
+ [Homebrew] should set every needed variable to point at the installed
+ library directory, but if that didn't happen, you can use the debug script
+ below to see what paths are looked up.
+
+ A [known workaround][cffi-issue] is to add the Homebrew lib path directly
+ before running MkDocs:
+
+ ```bash
+ export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
+ ```
+
+ View source code of [cairo-lookup-macos.py]
+
+ ```bash title="Python Debug macOS Script"
+ curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py" | python -
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ On Windows the library lookup checks inside the paths defined in the
+ environmental `PATH` variable. Additionally each library `name` is checked
+ in [two variants][find-library-Windows] with the `name` and `name.dll` format.
+
+ The default binary and shared library path for the [UCRT64] environment of
+ [MSYS2], in which the packages were installed using the above commands, is:
+
+ ```powershell
+ C:\msys64\ucrt64\bin
+ ```
+
+ Use the debug script below to check if the path is included. If it isn't then:
+
+ 1. Press ++windows+r++.
+ 2. Run the `SystemPropertiesAdvanced` applet.
+ 3. Select "Environmental Variables" at the bottom.
+ 4. Add the whole path to the above directory to your `Path` variable.
+ 5. Click OK on all open windows to apply changes.
+ 6. Fully restart any open Terminal windows and their parent hosts like IDEs.
+
+ ```powershell title="You can also list paths using PowerShell"
+ $env:Path -split ';'
+ ```
+
+ View source code of [cairo-lookup-windows.py]
+
+ ```powershell title="PowerShell - Python Debug Windows Script"
+ (Invoke-WebRequest "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py").Content | python -
+ ```
+
+=== ":material-linux: Linux"
+
+ On Linux the library lookup can [differ greatly][find-library-Linux] and is
+ dependent from the installed distribution. For tested Ubuntu and Manjaro
+ systems Python runs shell commands to check which libraries are available in
+ [`ldconfig`][ubuntu-ldconfig], in the [`gcc`][ubuntu-gcc]/`cc` compiler, and
+ in [`ld`][ubuntu-ld].
+
+ You can extend the `LD_LIBRARY_PATH` environmental variable with an absolute
+ path to a library directory containing `libcairo.so` etc. Run this directly
+ before MkDocs:
+
+ ```bash
+ export LD_LIBRARY_PATH=/absolute/path/to/lib:$LD_LIBRARY_PATH
+ ```
+
+ You can also modify the `/etc/ld.so.conf` file.
+
+ The Python script below shows, which function is being run to find installed
+ libraries. You can check the source to find out what specific commands are
+ executed on your system during library lookup.
+
+ View source code of [cairo-lookup-linux.py]
+
+ ```bash title="Python Debug Linux Script"
+ curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py" | python -
+ ```
+
+ [PyPi CairoSVG]: https://pypi.org/project/CairoSVG
+ [PyPi CairoCFFI]: https://pypi.org/project/CairoCFFI
+ [osx-dyld]: https://www.unix.com/man-page/osx/1/dyld/
+ [ubuntu-ldconfig]: https://manpages.ubuntu.com/manpages/focal/en/man8/ldconfig.8.html
+ [ubuntu-ld]: https://manpages.ubuntu.com/manpages/xenial/man1/ld.1.html
+ [ubuntu-gcc]: https://manpages.ubuntu.com/manpages/trusty/man1/gcc.1.html
+ [cffi-issue]: https://github.com/squidfunk/mkdocs-material/issues/5121
+ [cffi-dopen]: https://github.com/Kozea/cairocffi/blob/f1984d644bbc462ef0ec33b97782cf05733d7b53/cairocffi/__init__.py#L24-L49
+ [find-library-macOS]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L70-L81
+ [find-library-Windows]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L59-L67
+ [find-library-Linux]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L92
+ [cairo-lookup-macos.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py
+ [cairo-lookup-windows.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py
+ [cairo-lookup-linux.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py
diff --git a/docs/plugins/search.md b/docs/plugins/search.md
index 517b2b12818..603501cda54 100644
--- a/docs/plugins/search.md
+++ b/docs/plugins/search.md
@@ -94,7 +94,7 @@ The following settings are available:
####
-
+
Use this setting to enable or disable the plugin when [building your project].
diff --git a/docs/plugins/social.md b/docs/plugins/social.md
index c90423229ca..7ad60addff3 100644
--- a/docs/plugins/social.md
+++ b/docs/plugins/social.md
@@ -277,7 +277,6 @@ enabled. The following log levels are available:
Errors are only reported when using the `--verbose` flag.
-
### Social cards
The following settings are available for social card generation:
@@ -421,6 +420,7 @@ defining which parts of your layout can be parametrized. The [`default` layouts]
- [`background_image`][option.background_image]
- [`color`][option.color]
- [`font_family`][option.font_family]
+- [`font_variant`][option.font_variant]
- [`logo`][option.logo]
- [`title`][option.title]
- [`description`][option.description]
@@ -980,6 +980,29 @@ no further configuration needed.
---
+####
+
+
+
+
+
+Use this option to change the font variant used to generate the social card.
+If the downloaded font has variants like `Condensed` or `Expanded`, you can set
+them with:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ font_variant: Condensed
+```
+
+The variant is combined with the style as used in the custom layout, so the
+plugin is instructed to use combinations like `Condensed Regular` or
+`Expanded Bold`.
+
+---
+
####
diff --git a/docs/plugins/tags.md b/docs/plugins/tags.md
index 176918d7a78..87a26890c6f 100644
--- a/docs/plugins/tags.md
+++ b/docs/plugins/tags.md
@@ -109,13 +109,12 @@ The following settings are available for tags:
####
-
+
-Use this setting to enable or disable handling of tags. Currently, the plugin's
-sole purpose is to process tags, so it's equivalent to the [`enabled`]
-[config.enabled] setting, but in the future, other features might be added.
-If you want to disable handling of tags, use:
+Use this setting to enable or disable rendering of tags. The plugin still
+extracts tags from all pages, e.g., for [exporting tags] without rendering them.
+Rendering can be disabled with:
``` yaml
plugins:
@@ -123,6 +122,11 @@ plugins:
tags: false
```
+This setting is automatically disabled if [`export_only`][config.export_only]
+is enabled.
+
+ [exporting tags]: #export
+
---
####
@@ -130,6 +134,13 @@ plugins:
+!!! info "This setting is not needed in [Insiders]"
+
+ Insiders ships a __ground up rewrite of the tags plugin__ which is infinitely
+ more powerful than the current version in the community edition. It allows
+ for an arbitrary number of tags indexes (listings), [scoped listings],
+ [shadow tags], [nested tags], and much more.
+
Use this setting to specify the location of the tags index, which is the page
used to render a list of all tags and their associated pages. If this setting is
specified, tags become clickable, pointing to the corresponding section in the
@@ -147,110 +158,141 @@ if you want to have a tags index.
The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+ [Insiders]: ../insiders/index.md
+ [scoped listings]: ../setup/setting-up-tags.md#scoped-listings
+ [shadow tags]: ../setup/setting-up-tags.md#shadow-tags
+ [nested tags]: ../setup/setting-up-tags.md#nested-tags
+
---
-####
+####
-
-
+
+
-Use this setting to specify the locations of additional tags indexes, which are
-pages that render a subset of the tags index, in order to provide scoped tags
-indexes for specific sections:
+Use this setting to change the function for generating URL-compatible slugs
+from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
``` yaml
plugins:
- tags:
- tags_extra_files:
- extra-1.md: [tag-id-1, tag-id-2, ...]
- extra-2.md: [tag-id-3, tag-id-4, ...]
- ...
+ tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
```
-The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+ [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
---
-####
+####
-
+
-Use this setting to change the function to use for generating URL-compatible
-slugs from tags. [Python Markdown Extensions] comes with a Unicode-aware
-[`slugify`][pymdownx.slugs.slugify] function:
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`tags_slugify`][config.tags_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
-=== "Unicode"
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_separator: _
+```
- ``` yaml
- plugins:
- - tags:
- tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- ```
+---
-=== "Unicode, case-sensitive"
+####
- ``` yaml
- plugins:
- - tags:
- tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
- ```
+
+
+
-When your project features non-European languages, it's advisable to use this
-configuration. Of course, you can also provide a custom slugification function
-for more granular control.
+Use this setting to change the format string that is used when generating tag
+slugs. It is a good idea to prefix tag slugs with a string that makes them
+unique, the default being:
- [toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
- [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
- [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_format: "tag:{slug}"
+```
+
+The following placeholders are available:
+
+- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]
---
-####
+####
-
-
+
+
+
-Use this setting to change the separator that is passed to the slugification
-function set as part of [`tags_slugify`][config.tags_slugify]. While the default
-is a hyphen, it can be set to any string, e.g., `_`:
+Use this setting to enable support for tag hierarchies (nested tags, e.g.,
+`foo/bar`). If you intend to create hierarchical listings of tags, you can
+enable this setting in `mkdocs.yml` with:
``` yaml
plugins:
- tags:
- tags_slugify_separator: _
+ tags_hierarchy: true
```
---
-####
+####
+
+
+
+
+
+
+Use this setting to change the separator that is used when creating tag
+hierarchies. By default, tags are separated by a forward slash `/`, but you
+can change this to any string, e.g., `.`:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy_separator: .
+```
+
+---
+
+####
-
+
Use this setting to specify a custom function for comparing tags. By default,
-tag comparison is case-sensitive, but you can use the `casefold` function
-for case-insensitive comparison:
+tag comparison is case-sensitive, but you can use `tag_name_casefold` for
+case-insensitive comparison:
``` yaml
plugins:
- tags:
- tags_compare: !!python/name:material.plugins.tags.casefold
+ tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
```
You can also define your own comparison function, which must return a string
-representing the tag, that is used for sorting, and reference it in
-[`tags_compare`][config.tags_compare].
+or number representing the tag, that is used for sorting, and reference it in
+[`tags_sort_by`][config.tags_sort_by].
---
-####
+####
@@ -263,83 +305,431 @@ ordering as follows:
``` yaml
plugins:
- tags:
- tags_compare_reverse: true
+ tags_sort_reverse: true
```
---
-####
+####
-
+
+
+
+Use this setting to change the name of the front matter property that is used by
+the plugin. It is normally not necessary to change this setting, but if you want
+to change it, you can use:
+
+``` yaml
+plugins:
+ - tags:
+ tags_name_property: tags
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the name of the template variable that is used by
+the plugin. It is normally not necessary to change this setting, but if you want
+to change it, you can use:
+
+``` yaml
+plugins:
+ - tags:
+ tags_name_variable: tags
+```
+
+---
+
+####
+
+
+
+
+
+The plugin allows to check tags against a predefined list, in order to catch
+typos or make sure that tags are not arbitrarily added. Specify the tags you
+want to allow with:
+
+``` yaml
+plugins:
+ - tags:
+ tags_allowed:
+ - HTML5
+ - JavaScript
+ - CSS
+```
+
+The plugin stops the build if a page references a tag that is not part of
+this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
+metadata property.
+
+### Listings
+
+The following settings are available for listings:
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable listings. It is normally not necessary to
+change this setting, as listings are created entirely by inline comments, but
+you can disable them if necessary with:
+
+``` yaml
+plugins:
+ - tags:
+ listings: false
+```
+
+This setting is automatically disabled if [`export_only`][config.export_only]
+is enabled.
+
+ [exporting tags]: #export
+
+---
+
+####
+
+
+
-Use this setting to specify a custom function for comparing pages. By default,
-pages occur in order of appearance, but you can sort them by using the following
-configuration:
+Use this define listing configurations that you can then reference in listings
+with a custom identifier. Sharing configurations is a good idea, especially
+when you have many tag listings:
-=== "Sort by page title"
+``` yaml
+plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ scope: true
+ exclude: Internal
+```
+
+Then, just reference the listing identifier:
+
+``` html
+
+```
+
+See the [listings section] for a list of all available settings.
+
+ [listings section]: #listing-configuration
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a custom function for comparing listing items. By
+default, items are ordered by their titles, but you can change the sorting
+criterion with the following configuration:
+
+=== "Sort by item title"
``` yaml
plugins:
- tags:
- tags_pages_compare: !!python/name:material.plugins.tags.page_title
+ listings_sort_by: !!python/name:material.plugins.tags.item_title
```
-=== "Sort by page URL"
+=== "Sort by item URL"
``` yaml
plugins:
- tags:
- tags_pages_compare: !!python/name:material.plugins.tags.page_url
+ listings_sort_by: !!python/name:material.plugins.tags.item_url
```
You can also define your own comparison function, which must return a string
-representing the page, that is used for sorting, and reference it in
-[`tags_pages_compare`][config.tags_pages_compare].
+or number representing the item, that is used for sorting, and reference it in
+[`listings_sort_by`][config.listings_sort_by].
---
-####
+####
-Use this setting to reverse the order in which pages are sorted when comparing
-them. By default, pages are sorted in ascending order, but you can reverse
+Use this setting to reverse the order in which items are sorted when comparing
+them. By default, items are sorted in ascending order, but you can reverse
ordering as follows:
``` yaml
plugins:
- tags:
- tags_pages_compare_reverse: true
+ listings_sort_reverse: true
```
---
-####
+####
-
+
+
+
+Use this setting to specify a custom function for comparing tags in listings. By
+default, tag comparison is case-sensitive, but you can use `tag_name_casefold`
+for case-insensitivity:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
+```
+
+You can also define your own comparison function, which must return a string
+or number representing the tag, that is used for sorting, and reference it in
+[`tags_sort_by`][config.tags_sort_by].
+
+---
+
+####
+
+
+
+
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_reverse: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the name of the directive the plugin will look for
+when processing pages. If you want to use a shorter directive than
+`material/tags`, you could use:
+
+``` yaml
+plugins:
+ - tags:
+ listings_directive: $tags
+```
+
+Using this setting, listings must now be referenced as such:
+
+``` html
+
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to enable or disable tags showing up in the table of contents.
+If you don't want tags to show up in the table of contents, you can disable this
+behavior with:
+
+``` yaml
+plugins:
+ - tags:
+ listings_toc: false
+```
+
+### Shadow tags
+
+The following settings are available for shadow tags:
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify whether the plugin should include shadow tags on
+pages and in listings when [building your project], which might be useful for
+deploy previews:
+
+=== "Show shadow tags"
+
+ ``` yaml
+ plugins:
+ - tags:
+ shadow: true
+ ```
+
+=== "Hide shadow tags"
+
+ ``` yaml
+ plugins:
+ - tags:
+ shadow: false
+ ```
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin should include shadow tags on
+pages and in listings when [previewing your site]. If you don't wish to include
+them when previewing, use:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_on_serve: false
+```
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+---
+
+####
+
+
+
-The plugin allows to check tags against a predefined list, in order to catch
-typos or make sure that tags are not arbitrarily added. Specify the tags you
-want to allow with:
+The plugin allows to specify a predefined list of shadow tags which can be
+included and excluded from builds by using the [`shadow`][config.shadow]
+setting. Shadow tags must be specified as a list:
``` yaml
plugins:
- tags:
- tags_allowed:
- - HTML5
- - JavaScript
- - CSS
+ shadow_tags:
+ - Draft
+ - Internal
```
-The plugin stops the build if a page references a tag that is not part of
-this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
-metadata property.
+---
+
+####
+
+
+
+
+
+Use this setting to specify a string that is checked as a prefix for each tag.
+If the tag starts with this string, the tag is marked as a shadow tag. A common
+practice is to use `_` as a prefix:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags_prefix: _
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify a string that is checked as a suffix for each tag.
+If the tag ends with this string, the tag is marked as a shadow tag. One option
+can be to use `Internal` as a suffix:
+
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags_suffix: Internal
+```
+
+### Export
+
+The following settings are available for exporting:
+
+---
+
+####
+
+
+
+
+
+Use this setting to control whether the plugin creates a `tags.json` file
+inside your [`site` directory][mkdocs.site_dir], which can then be consumed by
+other plugins and projects:
+
+``` yaml
+plugins:
+ - tags:
+ export: true
+```
+
+---
+
+####
+
+
+
+
+
+Use this setting to change the path of the file where the exported tags are
+stored. It's normally not necessary to change this setting, but if you need to,
+use:
+
+``` yaml
+plugins:
+ - tags:
+ export_file: tags.json
+```
+
+The provided path is resolved from the [`site` directory][mkdocs.site_dir].
+
+---
+
+####
+
+
+
+
+
+This setting is solely provided for convenience to disable the rendering of tags
+and listings with a single setting (e.g. by using an environment variable),
+while keeping the export functionality:
+
+``` yaml
+plugins:
+ - tags:
+ export_only: true
+```
+
+This will automatically disable the [`tags`][config.tags] and
+[`listings`][config.listings] settings.
## Usage
@@ -374,3 +764,189 @@ tags:
If you want to prevent accidental typos when assigning tags to pages, you can
set a predefined list of allowed tags in `mkdocs.yml` by using the
[`tags_allowed`][config.tags_allowed] setting.
+
+### Listing configuration
+
+The listings configuration controls which tags are included in or excluded from
+a listing and whether a listing only includes pages in the current scope.
+Furthermore, listings can override some values from the global configuration.
+
+The following settings are available:
+
+---
+
+####
+
+
+
+
+
+This setting specifies whether the listing should only consider pages that are
+within the current subsection of the documentation of the page the listing is
+embedded in:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ scope: false
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+---
+
+####
+
+
+
+
+
+This setting specifies whether the listing should include shadow tags, which
+allows to override the global [`shadow`][config.shadow] setting on a per-listing
+basis:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ shadow: true
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+---
+
+####
+
+
+
+
+
+This setting specifies whether the listing should render tags inside the table
+of contents, allowing to override the global [`listings_toc`][config.listings_toc]
+setting on a per-listing basis:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ toc: true
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify which tags should be included in the listing. Each
+page that features a tag that is part of this setting, is listed under the
+respective tag:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ include:
+ - foo
+ - bar
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+If this setting is left empty, all tags and pages are included.
+
+---
+
+####
+
+
+
+
+
+Use this setting to specify which tags should be excluded from the listing. Each
+page that features a tag that is part of this setting, is excluded from the
+listing entirely:
+
+=== "Inline usage"
+
+ ``` html
+
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ exclude:
+ - foo
+ - bar
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+
+ ```
+
+If this setting is left empty, no tags or pages are excluded.
diff --git a/docs/plugins/typeset.md b/docs/plugins/typeset.md
index 16528d10d0d..3216ca6690a 100644
--- a/docs/plugins/typeset.md
+++ b/docs/plugins/typeset.md
@@ -10,6 +10,13 @@ headlines within the navigation and table of contents. This means that code
blocks, icons, emojis and any other inline formatting can be rendered exactly
as defined in the page's content.
+---
+
+ __Sponsors only__ – this plugin is currently reserved to
+[our awesome sponsors].
+
+ [our awesome sponsors]: ../insiders/index.md
+
## Objective
### How it works
diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md
index a33ac968576..4019a3f80ad 100644
--- a/docs/publishing-your-site.md
+++ b/docs/publishing-your-site.md
@@ -35,11 +35,15 @@ contents:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- - uses: actions/setup-python@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v5
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
- - uses: actions/cache@v3
+ - uses: actions/cache@v4
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
@@ -90,11 +94,15 @@ contents:
if: github.event.repository.fork == false
steps:
- uses: actions/checkout@v4
- - uses: actions/setup-python@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v5
with:
python-version: 3.x
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- - uses: actions/cache@v3
+ - uses: actions/cache@v4
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
@@ -110,7 +118,7 @@ contents:
1. This step is only necessary if you want to use the
[built-in optimize plugin] to automatically compress images.
- 2. Remember to set the `GH_TOKEN` environment variable to the value of your
+ 2. Remember to set the `GH_TOKEN` repository secret to the value of your
[personal access token] when deploying [Insiders], which can be done
using [GitHub secrets].
@@ -142,6 +150,14 @@ the following command from the directory containing the `mkdocs.yml` file:
mkdocs gh-deploy --force
```
+This will build your documentation and deploy it to a branch
+`gh-pages` in your repository. See [this overview in the MkDocs
+documentation] for more information. For a description of the
+arguments, see [the documentation for the command].
+
+ [this overview in the MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#project-pages
+ [the documentation for the command]: https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
+
## GitLab Pages
If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
@@ -181,7 +197,7 @@ contents:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```
- 1. Remember to set the `GH_TOKEN` environment variable to the value of your
+ 1. Remember to set the `GH_TOKEN` repository secret to the value of your
[personal access token] when deploying [Insiders], which can be done
using [masked custom variables].
@@ -199,11 +215,14 @@ other providers:
@@ -212,7 +231,11 @@ other providers:
[masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
[default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html
[Azure]: https://bawmedical.co.uk/t/publishing-a-material-for-mkdocs-site-to-azure-with-automatic-branch-pr-preview-deployments/763
- [Cloudflare Pages]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-cloudflare/
- [DigitalOcean]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-digitalocean-app-platform/
- [Netlify]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-netlify/
- [Vercel]: https://www.starfallprojects.co.uk/projects/deploy-host-docs/deploy-mkdocs-material-vercel/
+ [Cloudflare Pages]: https://deborahwrites.com/guides/deploy-mkdocs-material-cloudflare/
+ [DigitalOcean]: https://deborahwrites.com/guides/deploy-mkdocs-material-digitalocean-app-platform/
+ [Flyio]: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/
+ [Netlify]: https://deborahwrites.com/projects/deploy-host-docs/deploy-mkdocs-material-netlify/
+ [Vercel]: https://deborahwrites.com/guides/deploy-mkdocs-material-vercel/
+ [Codeberg Pages]: https://andre601.ch/blog/2023/11-05-using-codeberg-pages/
+ [Scaleway]: https://www.scaleway.com/en/docs/tutorials/using-bucket-website-with-mkdocs/
+
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index 0bcf9e86346..02f9fe2c27a 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -285,7 +285,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
[^1]:
Previously, some of the supported types defined more than one qualifier.
For example, authors could use `summary` or `tldr` as alternative qualifiers
- to render an [`abstract`](#type:abstract) admonition. As this increased the
+ to render an [`abstract`](#+type:abstract) admonition. As this increased the
size of the CSS that is shipped with Material for MkDocs, the additional
type qualifiers are now all deprecated and will be removed in the next major
version. This will also be mentioned in the upgrade guide.
diff --git a/docs/reference/buttons.md b/docs/reference/buttons.md
index 963c70e1b58..03dcb6dc9a0 100644
--- a/docs/reference/buttons.md
+++ b/docs/reference/buttons.md
@@ -44,7 +44,7 @@ In order to render a link as a button, suffix it with curly braces and add the
[primary color]: ../setup/changing-the-colors.md#primary-color
- [accent color]: ../setup/changing-the-colors.md#accent-color
+ [accent color]: ../setup/changing-the-colors.md#accent-color
[Demo]: javascript:alert$.next("Demo")
### Adding primary buttons
diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md
index 4ac278ad848..414057a2597 100644
--- a/docs/reference/code-blocks.md
+++ b/docs/reference/code-blocks.md
@@ -71,9 +71,9 @@ theme:
```
````
- Note that the language shortcode which has to come first must now also be
- prefixed by a `.`. Similarly, the copy button can also be disabled for a
- specific code block:
+ Note that there must be a language shortcode, which has to come first and
+ must also be prefixed by a `.`. Similarly, the copy button can also be
+ disabled for a specific code block:
```` { .yaml .no-copy }
``` { .yaml .no-copy }
@@ -81,6 +81,9 @@ theme:
```
````
+ To enable or disable the copy button without syntax highlighting, you can
+ use the `.text` language shortcode, which doesn't highlight anything.
+
### Code selection button
diff --git a/docs/reference/content-tabs.md b/docs/reference/content-tabs.md
index 5d08715ee26..ded76bea170 100644
--- a/docs/reference/content-tabs.md
+++ b/docs/reference/content-tabs.md
@@ -32,13 +32,12 @@ See additional configuration options:
### Anchor links
-
-
+
-In order to link to content tabs and share them more easily, [Insiders] adds
-an anchor link to each content tab automatically, which you can copy via right
-click or open in a new tab:
+In order to link to content tabs and share them more easily, an anchor link is
+automatically added to each content tab, which you can copy via right click or
+open in a new tab:
=== "Open me in a new tab ..."
@@ -66,8 +65,8 @@ or to the [publishing guide for Insiders][tab_2].
Fore more information, please [see the extension guide][slugification].
- [tab_1]: #-or-even-me
- [tab_2]: ../publishing-your-site.md#insiders
+ [tab_1]: #anchor-links--or-even-me
+ [tab_2]: ../publishing-your-site.md#with-github-actions-insiders
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
[slugification]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.tabbed.slugify
diff --git a/docs/reference/diagrams.md b/docs/reference/diagrams.md
index a336391d8c1..9125af3f7fb 100644
--- a/docs/reference/diagrams.md
+++ b/docs/reference/diagrams.md
@@ -9,7 +9,7 @@ different technical components, and are a great addition to project
documentation. Material for MkDocs integrates with [Mermaid.js], a very
popular and flexible solution for drawing diagrams.
- [Mermaid.js]: https://mermaid-js.github.io/mermaid/
+ [Mermaid.js]: https://mermaid.js.org/
## Configuration
@@ -78,7 +78,7 @@ graph LR
- [Flowcharts]: https://mermaid-js.github.io/mermaid/#/flowchart
+ [Flowcharts]: https://mermaid.js.org/syntax/flowchart.html
### Using sequence diagrams
@@ -118,7 +118,7 @@ sequenceDiagram
- [Sequence diagrams]: https://mermaid-js.github.io/mermaid/#/sequenceDiagram
+ [Sequence diagrams]: https://mermaid.js.org/syntax/sequenceDiagram.html
### Using state diagrams
@@ -160,11 +160,11 @@ stateDiagram-v2
- [State diagrams]: https://mermaid-js.github.io/mermaid/#/stateDiagram
+ [State diagrams]: https://mermaid.js.org/syntax/stateDiagram.html
### Using class diagrams
-[Class diagrams] are central to object oriented programing, describing the
+[Class diagrams] are central to object oriented programming, describing the
structure of a system by modelling entities as classes and relationships between
them:
@@ -232,7 +232,7 @@ classDiagram
- [Class diagrams]: https://mermaid-js.github.io/mermaid/#/classDiagram
+ [Class diagrams]: https://mermaid.js.org/syntax/classDiagram.html
### Using entity-relationship diagrams
@@ -268,7 +268,7 @@ erDiagram
- [entity-relationship diagram]: https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram
+ [entity-relationship diagram]: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
### Other diagram types
@@ -278,8 +278,8 @@ Besides the diagram types listed above, [Mermaid.js] provides support for
for MkDocs. Those diagrams should still work as advertised by [Mermaid.js], but
we don't consider them a good choice, mostly as they don't work well on mobile.
- [pie charts]: https://mermaid-js.github.io/mermaid/#/pie
- [gantt charts]: https://mermaid-js.github.io/mermaid/#/gantt
- [user journeys]: https://mermaid-js.github.io/mermaid/#/user-journey
- [git graphs]: https://mermaid-js.github.io/mermaid/#/gitgraph
- [requirement diagrams]: https://mermaid-js.github.io/mermaid/#/requirementDiagram
+ [pie charts]: https://mermaid.js.org/syntax/pie.html
+ [gantt charts]: https://mermaid.js.org/syntax/gantt.html
+ [user journeys]: https://mermaid.js.org/syntax/userJourney.html
+ [git graphs]: https://mermaid.js.org/syntax/gitgraph.html
+ [requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html
diff --git a/docs/reference/footnotes.md b/docs/reference/footnotes.md
index 16380c2cb2b..1a2ec5ca386 100644
--- a/docs/reference/footnotes.md
+++ b/docs/reference/footnotes.md
@@ -26,6 +26,28 @@ See additional configuration options:
[Footnotes]: ../setup/extensions/python-markdown.md#footnotes
+### Footnote tooltips :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2024" }
+
+
+
+
+
+[Insiders] allows to render footnotes as inline tooltips, so the user can read
+the footnote without leaving the context of the document. Footnote tooltips can
+be enabled in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ features:
+ - content.footnote.tooltips
+```
+
+__Footnote tooltips are enabled on our documentation__, so to try it out, you
+can just hover or focus any footnote on this page or any other page of our
+documentation.
+
+ [Insiders]: ../insiders/index.md
+
## Usage
### Adding footnote references
diff --git a/docs/reference/formatting.md b/docs/reference/formatting.md
index d1e0c9a23ab..e8148ce2a06 100644
--- a/docs/reference/formatting.md
+++ b/docs/reference/formatting.md
@@ -4,8 +4,8 @@ icon: material/format-font
# Formatting
-Material for MkDocs provides support for several HTML elements that can be used
-to highlight sections of a document or apply specific formatting. Additionally,
+Material for MkDocs provides support for several HTML elements that can be used
+to highlight sections of a document or apply specific formatting. Additionally,
[Critic Markup] is supported, adding the ability to display suggested changes
for a document.
@@ -14,7 +14,7 @@ for a document.
## Configuration
This configuration enables support for keyboard keys, tracking changes in
-documents, defining sub- and superscript and highlighting text. Add the
+documents, defining sub- and superscript and highlighting text. Add the
following lines to `mkdocs.yml`:
``` yaml
@@ -40,7 +40,7 @@ See additional configuration options:
### Highlighting changes
-When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to
+When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to
highlight suggested changes, as well as add inline comments to a document:
``` title="Text with suggested changes"
@@ -78,21 +78,21 @@ Text can be deleted and replacement text
### Highlighting text
-When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
+When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
syntax, which is more convenient that directly using the corresponding
[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags:
``` title="Text with highlighting"
-- ==This was marked==
-- ^^This was inserted^^
-- ~~This was deleted~~
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
```
-- ==This was marked==
-- ^^This was inserted^^
-- ~~This was deleted~~
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
@@ -102,7 +102,7 @@ syntax, which is more convenient that directly using the corresponding
### Sub- and superscripts
-When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
+When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
superscripted with a simple syntax, which is more convenient than directly
using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
diff --git a/docs/reference/grids.md b/docs/reference/grids.md
index 46b9f0e1b44..10af8d55b36 100644
--- a/docs/reference/grids.md
+++ b/docs/reference/grids.md
@@ -45,8 +45,7 @@ elements in a rectangular shape.
### Using card grids
-
-
+
Card grids wrap each grid item with a beautiful hover card that levitates on
@@ -226,8 +225,7 @@ to the grid.
### Using generic grids
-
-
+
Generic grids allow for arranging arbitrary block elements in a grid, including
diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md
index bff42037efe..e9f5d6c3086 100644
--- a/docs/reference/icons-emojis.md
+++ b/docs/reference/icons-emojis.md
@@ -21,6 +21,14 @@ can be added] and used in `mkdocs.yml`, documents and templates.
data-mdx-component="iconsearch-query"
/>
+
@@ -83,8 +91,7 @@ the shortcodes at [Emojipedia]:
:smile:
-
- [Twemoji]: https://twemoji.twitter.com/
+ [Twemoji]: https://github.com/twitter/twemoji
[Emojipedia]: https://emojipedia.org/twitter/
### Using icons
@@ -113,16 +120,16 @@ styles], it's always recommended to add an [additional style sheet] and move
declarations into dedicated CSS classes:
=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
``` css
- .twitter {
- color: #1DA1F2;
+ .youtube {
+ color: #EE0F0F;
}
```
@@ -136,12 +143,12 @@ declarations into dedicated CSS classes:
After applying the customization, add the CSS class to the icon shortcode:
``` markdown title="Icon with color"
-:fontawesome-brands-twitter:{ .twitter }
+:fontawesome-brands-youtube:{ .youtube }
```
@@ -211,7 +218,7 @@ reference any icon that's [bundled with the theme][icon search] with Jinja's
``` html
- {% include ".icons/fontawesome/brands/twitter.svg" %}
+ {% include ".icons/fontawesome/brands/youtube.svg" %}
```
@@ -219,7 +226,7 @@ reference any icon that's [bundled with the theme][icon search] with Jinja's
click on the shortcode to copy it to your clipboard:
-
+
diff --git a/docs/reference/images.md b/docs/reference/images.md
index a9009258d36..336bd4c8a57 100644
--- a/docs/reference/images.md
+++ b/docs/reference/images.md
@@ -19,15 +19,18 @@ following lines to `mkdocs.yml`:
markdown_extensions:
- attr_list
- md_in_html
+ - pymdownx.blocks.caption
```
See additional configuration options:
- [Attribute Lists]
- [Markdown in HTML]
+- [Caption]
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
[Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+ [Caption]: ../setup/extensions/python-markdown-extensions.md#caption
### Lightbox
@@ -122,7 +125,7 @@ but it's always possible to use the [Markdown in HTML] extension with literal
`figure` and `figcaption` tags:
``` html title="Image with caption"
-
+However, [Caption] provides an alternative syntax to add captions
+to any Markdown block element, including images:
+
+``` markdown title="Image with caption"
+![Image title](https://dummyimage.com/600x400/){ width="300" }
+/// caption
+Image caption
+///
+```
+
### Image lazy-loading
Modern browsers provide [native support for lazy-loading images][lazy-loading]
diff --git a/docs/reference/lists.md b/docs/reference/lists.md
index 5883002a7be..1de7e7bb366 100644
--- a/docs/reference/lists.md
+++ b/docs/reference/lists.md
@@ -62,7 +62,7 @@ of lists can be nested inside each other:
### Using ordered lists
-Ordered lists must start with a number immediately followed by a dot. The
+Ordered lists must start with a number immediately followed by a dot. The
numbers do not need to be consecutive and can be all set to `1.`, as they will
be re-numbered when rendered:
diff --git a/docs/reference/math.md b/docs/reference/math.md
index 92744158ea3..83cc8df3731 100644
--- a/docs/reference/math.md
+++ b/docs/reference/math.md
@@ -4,10 +4,10 @@ icon: material/alphabet-greek
# Math
-[MathJax] and [KaTeX] are two popular libraries for displaying
-mathematical content in browsers. Although both libraries offer similar
-functionality, they use different syntaxes and have different configuration
-options. This documentation site provides information on how to integrate them
+[MathJax] and [KaTeX] are two popular libraries for displaying
+mathematical content in browsers. Although both libraries offer similar
+functionality, they use different syntaxes and have different configuration
+options. This documentation site provides information on how to integrate them
with Material for MkDocs easily.
[MathJax]: https://www.mathjax.org/
@@ -19,14 +19,14 @@ with Material for MkDocs easily.
## Configuration
-The following configuration enables support for rendering block and
+The following configuration enables support for rendering block and
inline block equations using [MathJax] and [KaTeX].
### MathJax
-[MathJax] is a powerful and flexible library that supports multiple input formats,
-such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
-HTML, SVG, MathML. To use MathJax within your project, add the following lines
+[MathJax] is a powerful and flexible library that supports multiple input formats,
+such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
+HTML, SVG, MathML. To use MathJax within your project, add the following lines
to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
@@ -46,6 +46,9 @@ to your `mkdocs.yml`.
};
document$.subscribe(() => { // (1)!
+ MathJax.startup.output.clearCache()
+ MathJax.typesetClear()
+ MathJax.texReset()
MathJax.typesetPromise()
})
```
@@ -61,8 +64,7 @@ to your `mkdocs.yml`.
extra_javascript:
- javascripts/mathjax.js
- - https://polyfill.io/v3/polyfill.min.js?features=es6
- - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+ - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
```
See additional configuration options:
@@ -72,11 +74,26 @@ See additional configuration options:
[Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
[instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+
### KaTeX
-[KaTeX] is a lightweight library that focuses on speed and simplicity. It
-supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
+[KaTeX] is a lightweight library that focuses on speed and simplicity. It
+supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
[KaTeX] within your project, add the following lines to your `mkdocs.yml`.
=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
@@ -99,36 +116,19 @@ supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
+ markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+
extra_javascript:
- - javascripts/katex.js
- - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js # (1)!
- - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
-
+ - javascripts/katex.js
+ - https://unpkg.com/katex@0/dist/katex.min.js
+ - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
+
extra_css:
- - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
+ - https://unpkg.com/katex@0/dist/katex.min.css
```
- 1. Alternatively, you can add these JavaScript and CSS files via `script` tags by overriding HTML files.
-
-
-
-
-
-
-
## Usage
### Using block syntax
@@ -138,14 +138,14 @@ lines:
``` latex title="block syntax"
$$
-\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
+\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
$$
```
@@ -155,44 +155,44 @@ $$
Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
``` latex title="inline syntax"
-The homomorphism $f$ is injective if and only if its kernel is only the
-singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
```
-The homomorphism $f$ is injective if and only if its kernel is only the
-singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
that $f(a)=f(b)$.
-- :material-brush-variant: __[Colors]__ Change colors with an existing color palette or customize with CSS
+- :material-brush-variant: __[Colors]__ – Change colors with an existing color palette or customize with CSS
- :material-format-font: __[Fonts]__ – Choose among 1,000 Google Fonts or load self-hosted fonts
- :material-google-downasaur: __[Logo & Icons]__ – Change the logo, use any of the 8,000+ icons, or add new ones
- :material-cards-variant: __[Social Cards]__ – Automatically create social media previews when sharing links
diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md
index e01593a8771..35dd9d66552 100644
--- a/docs/setup/setting-up-a-blog.md
+++ b/docs/setup/setting-up-a-blog.md
@@ -32,16 +32,57 @@ plugins:
- blog
```
+If you do not have a navigation (`nav`) definition in your `mkdocs.yml` then
+there is nothing else to do there as the blog plugin will add navigation
+automatically. If you do have a navigation defined then you need to add *the
+blog index page only* to it. You need not and should not add the individual
+blog posts. For example:
+
+```yaml
+nav:
+ - index.md
+ - Blog:
+ - blog/index.md
+```
+
For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/blog.md
+#### Advanced settings
+
+
+
+
+The following advanced settings are currently reserved to our [sponsors]
+[Insiders]. They are entirely optional, and don't affect the functionality of
+the blog, but can be helpful for customizations:
+
+- [`archive_pagination`][config.archive_pagination]
+- [`archive_pagination_per_page`][config.archive_pagination_per_page]
+- [`categories_sort_by`][config.categories_sort_by]
+- [`categories_sort_reverse`][config.categories_sort_reverse]
+- [`categories_pagination`][config.categories_pagination]
+- [`categories_pagination_per_page`][config.categories_pagination_per_page]
+- [`authors_profiles_pagination`][config.authors_profiles_pagination]
+- [`authors_profiles_pagination_per_page`][config.authors_profiles_pagination_per_page]
+
+We'll add more settings here, as we discover new use cases.
+
[Insiders]: ../insiders/index.md
[built-in blog plugin]: ../plugins/blog.md
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
- [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
[start writing your first post]: #writing-your-first-post
+ [config.archive_pagination]: ../plugins/blog.md#config.archive_pagination
+ [config.archive_pagination_per_page]: ../plugins/blog.md#config.archive_pagination_per_page
+ [config.categories_sort_by]: ../plugins/blog.md#config.categories_sort_by
+ [config.categories_sort_reverse]: ../plugins/blog.md#config.categories_sort_reverse
+ [config.categories_pagination]: ../plugins/blog.md#config.categories_pagination
+ [config.categories_pagination_per_page]: ../plugins/blog.md#config.categories_pagination_per_page
+ [config.authors_profiles_pagination]: ../plugins/blog.md#config.authors_profiles_pagination
+ [config.authors_profiles_pagination_per_page]: ../plugins/blog.md#config.authors_profiles_pagination_per_page
+
### RSS
@@ -80,7 +121,7 @@ The following configuration options are supported:
: This option specifies whether
the plugin is enabled when building your project. If you want to speed up
- local builds, you can use an [environment variable]:
+ local builds, you can use an [environment variable][mkdocs.env]:
``` yaml
plugins:
@@ -140,9 +181,11 @@ The following configuration options are supported:
```
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].
+which will make the RSS feed discoverable by browsers and feed readers.
+
+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.
[rss]: https://guts.github.io/mkdocs-rss-plugin/
[categories]: ../plugins/blog.md#categories
@@ -150,7 +193,37 @@ For further information, see the [documentation].
[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/
+
+### Blog only
+
+You might need to build a pure blog without any documentation.
+In this case, you can create a folder tree like this:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ ├─ posts/ # (1)!
+│ ├─ .authors.yml
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. Notice that the `posts` directory is in the root of `docs` without
+ intermediate `blog` directory.
+
+And add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog:
+ blog_dir: . # (1)!
+```
+
+1. Please see the [plugin documentation] for more information about the
+ [`blog_dir`][blog_dir] setting.
+
+With this configuration, the url of the blog post will be `/`
+instead of `/blog/`.
## Usage
@@ -181,7 +254,7 @@ Create a new file called `hello-world.md` and add the following lines:
``` yaml
---
draft: true # (1)!
-date: 2023-01-31 # (2)!
+date: 2024-01-31 # (2)!
categories:
- Hello
- World
@@ -260,25 +333,8 @@ authors:
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:
-
-
-
-:
- 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.
-
-
-
-:
- 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.
-
-
-
-:
- 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.
+Different attributes can be configured. For a list of all possible attributes,
+please consult the [`authors_file`][authors_file] documentation.
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`
@@ -287,7 +343,7 @@ each post, as well as in post excerpts on index pages:
``` yaml
---
-date: 2023-01-31
+date: 2024-01-31
authors:
- squidfunk
...
@@ -300,6 +356,30 @@ authors:
[authors]: ../plugins/blog.md#authors
[authors_file]: ../plugins/blog.md#config.authors_file
+#### Adding author profiles
+
+
+
+
+
+If you wish to add a dedicated page for each author, you can enable author
+profiles by setting the [`authors_profiles`][authors_profiles] configuration
+option to `true`. Just add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles: true
+```
+
+If you combine this with [custom index pages], you can create a dedicated page
+for each author with a short description, social media links, etc. – basically
+anything you can write in Markdown. The list of posts is then appended after
+the content of the page.
+
+ [authors_profiles]: ../plugins/blog.md#config.authors_profiles
+ [custom index pages]: #custom-index-pages
+
#### Adding categories
Categories are an excellent way for grouping your posts thematically on
@@ -309,7 +389,7 @@ add them to the front matter `categories` property:
``` yaml
---
-date: 2023-01-31
+date: 2024-01-31
categories:
- Hello
- World
@@ -335,7 +415,7 @@ part of a post, the post is linked from the [tags index]:
``` yaml
---
-date: 2023-01-31
+date: 2024-01-31
tags:
- Foo
- Bar
@@ -378,26 +458,26 @@ to add related links to a post:
``` yaml
---
-date: 2023-01-31
+date: 2024-01-31
links:
- plugins/search.md
- - insiders/index.md#how-to-become-a-sponsor
+ - insiders/how-to-sponsor.md
---
# Hello world!
...
```
-You can use the exact same syntax as for the [`nav`][nav] section in
+You can use the exact same syntax as for the [`nav`][mkdocs.nav] section in
`mkdocs.yml`, which means you can set explicit titles for links, add external
links and even use nesting:
``` yaml
---
-date: 2023-01-31
+date: 2024-01-31
links:
- plugins/search.md
- - insiders/index.md#how-to-become-a-sponsor
+ - insiders/how-to-sponsor.md
- Nested section:
- External link: https://example.com
- setup/setting-up-site-search.md
@@ -408,14 +488,13 @@ links:
```
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 possibilities 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.
+a specific section of a document, extending the possibilities of the
+[`nav`][mkdocs.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.
+Note that all links must be relative to [`docs_dir`][mkdocs.docs_dir], as is
+also the case for the [`nav`][mkdocs.nav] setting.
- [nav]: https://www.mkdocs.org/user-guide/configuration/#nav
[subtitle]: ../reference/index.md#setting-the-page-subtitle
#### Linking from and to posts
@@ -440,6 +519,29 @@ 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.
+#### Pinning a post :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" }
+
+
+
+
+
+If you want to pin a post to the top of the index page, as well as the archive
+and category indexes it is part of, you can use the front matter `pin` property:
+
+``` yaml
+---
+date: 2024-01-31
+pin: true
+---
+
+# Hello world!
+...
+```
+
+If multiple posts are pinned, they are sorted by their creation date, with the
+most recent pinned post being shown first, followed by the other pinned posts in
+descending order.
+
#### Setting the reading time
When [enabled], the [readtime] package is used to compute the expected reading
@@ -454,7 +556,7 @@ post:
``` yaml
---
-date: 2023-01-31
+date: 2024-01-31
readtime: 15
---
@@ -469,6 +571,11 @@ This will disable automatic reading time computation.
#### 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
@@ -515,9 +622,9 @@ values defined for a post, which means you can define common properties in
### 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`:
+the pages in the [`nav`][mkdocs.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:
@@ -553,13 +660,13 @@ the [built-in blog plugin] would create it:
1. The easiest way is to first [add the category] to the blog post, then take
the URL generated by the [built-in blog plugin] and create the file at the
- corresponding location in the [`blog_dir`][this is configurable] folder.
+ corresponding location in the [`blog_dir`][blog_dir] folder.
Note that the shown directory listing is based on the default configuration.
If you specify different values for the following options, be sure to adjust
the path accordingly:
- - [`blog_dir`][this is configurable]
+ - [`blog_dir`][blog_dir]
- [`categories_url_format`][categories_url_format]
- [`categories_slugify`][categories_slugify]
@@ -581,6 +688,7 @@ All post excerpts belonging to the category are automatically appended.
[page description]: ../reference/index.md#setting-the-page-description
[categories_url_format]: ../plugins/blog.md#config.categories_url_format
[categories_slugify]: ../plugins/blog.md#config.categories_slugify
+ [blog_dir]: ../plugins/blog.md#config.blog_dir
### Overriding templates
@@ -595,5 +703,5 @@ The following templates are added by the [built-in blog plugin]:
[theme extension]: ../customization.md#extending-the-theme
- [blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog.html
- [blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog-post.htmlhtml
+ [blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog.html
+ [blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog-post.html
diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md
index a6b64f35091..3aa3b765ed1 100644
--- a/docs/setup/setting-up-navigation.md
+++ b/docs/setup/setting-up-navigation.md
@@ -9,6 +9,13 @@ of its flagship features: [instant loading].
[sections]: #navigation-sections
[instant loading]: #instant-loading
+Additional navigation can be configured [in the footer] as well as with the
+[tags plugin]. The [blog plugin] also sets up additional navigation.
+
+[in the footer]: setting-up-the-footer.md#navigation
+[tags plugin]: ../plugins/tags.md
+[blog plugin]: ../plugins/blog.md
+
## Configuration
### Instant loading
@@ -31,9 +38,19 @@ 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.
+!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
+
+ Note that you must set [`site_url`][mkdocs.site_url] when using instant
+ navigation, as instant navigation relies on the generated `sitemap.xml`
+ which will be empty if this setting is omitted. Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
[XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
-#### Instant prefetching :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
+#### Instant prefetching
@@ -74,6 +91,111 @@ The progress indicator will only show if the page hasn't finished loading after
400ms, so that fast connections will never show it for a better instant
experience.
+### Instant previews :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2024" }
+
+
+
+
+
+
+Instant previews are a brand new feature that allow the user to preview another
+site of your documentation without navigating to it. They can be very helpful to
+keep the user in context. Instant previews can be enabled on any header link
+with the `data-preview` attribute:
+
+```` markdown title="Link with instant preview"
+``` markdown
+[Attribute Lists](#){ data-preview }
+```
+````
+
+
+
+!!! info "Limitations"
+
+ Instant previews are still an experimental feature and currently limited to
+ headerlinks. This means, you can use them on any internal link that points
+ to a header on another page, but not other elements with `id` attributes.
+ After we have gathered enough feedback, we will consider extending this
+ feature to other, and possibly arbitrary elements.
+
+#### Automatic previews
+
+
+
+
+
+
+The recommended way to work with instant previews is to use the Markdown
+extension that is included with Material for MkDocs, as it allows you to enable
+instant previews on a per-page or per-section level for your documentation:
+
+``` yaml
+markdown_extensions:
+ - material.extensions.preview:
+ targets:
+ include:
+ - changelog/index.md
+ - customization.md
+ - insiders/changelog/*
+ - setup/extensions/*
+```
+
+The above configuration is what we use for our documentation. We've enabled
+instant previews for our changelogs, customization guide, and Insiders sections,
+as well as for all Markdown extensions that we support.
+
+!!! info "Full configuration example"
+
+ ``` yaml
+ markdown_extensions:
+ - material.extensions.preview:
+ sources: # (1)!
+ include:
+ - ...
+ exclude:
+ - ...
+ targets: # (2)!
+ include:
+ - ...
+ exclude:
+ - ...
+ ```
+
+ 1. Sources specify the pages _on_ which instant previews should be enabled.
+ If this setting is omitted, instant previews will be enabled on all
+ pages. You can use patterns to include or exclude pages. Exclusion is
+ evaluated on top of inclusion, so if a page is matched by both, it will
+ be excluded.
+
+ 2. Targets specify the pages _to_ which instant previews should be enabled.
+ This is the recommended way to enable instant previews.
+---
+
+Instant previews can also be enabled globally by adding the following lines to
+`mkdocs.yml`, which will enable instant previews for all header links,
+alleviating the need to add data attributes:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant.preview
+```
+
+!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
+
+ Note that you must set [`site_url`][mkdocs.site_url] when using instant
+ previews, as instant previews rely on the generated `sitemap.xml`
+ which will be empty if this setting is omitted. Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
### Anchor tracking
diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md
index 0f5a1da37fe..d1dc0865658 100644
--- a/docs/setup/setting-up-site-analytics.md
+++ b/docs/setup/setting-up-site-analytics.md
@@ -274,18 +274,39 @@ generated by users interacting with the feedback widget with the help of some
``` js
var feedback = document.forms.feedback
+ feedback.hidden = false // (1)!
+
feedback.addEventListener("submit", function(ev) {
ev.preventDefault()
- /* Retrieve page and feedback value */
- var page = document.location.pathname
+ var page = document.location.pathname // (2)!
var data = ev.submitter.getAttribute("data-md-value")
- /* Send feedback value */
- console.log(page, data)
+ console.log(page, data) // (3)!
+
+ feedback.firstElementChild.disabled = true // (4)!
+
+ var note = feedback.querySelector(
+ ".md-feedback__note [data-md-value='" + data + "']"
+ )
+ if (note)
+ note.hidden = false // (5)!
})
```
+ 1. The feedback widget is hidden by default so that it does not appear when
+ people have JavaScript turned off. So, it needs to be turned on here.
+
+ 2. Retrieve page and feedback value.
+
+ 3. Replace this with the code that sends the data off to your analytics
+ provider.
+
+ 4. Disable the form after submission.
+
+ 5. Show the configured notes. Which one is shown depends on the user
+ feedback.
+
=== ":octicons-file-code-16: `mkdocs.yml`"
``` yaml
diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md
index 646af5f2ce8..0603cb08cad 100644
--- a/docs/setup/setting-up-social-cards.md
+++ b/docs/setup/setting-up-social-cards.md
@@ -1,7 +1,3 @@
----
-status: new
----
-
# Setting up social cards
Material for MkDocs can automatically create beautiful social cards for your
@@ -53,13 +49,13 @@ plugins:
For a list of all settings, please consult the [plugin documentation].
- [plugin documentation]: ../plugins/blog.md
+ [plugin documentation]: ../plugins/social.md
!!! info "The [`site_url`][site_url] setting must be set"
Note that you must set [`site_url`][site_url] when using the social plugin,
or the generated cards will not be correctly linked. Social media services
- like Twitter and Facebook demand that social previews point to an absolute
+ like X and Facebook demand that social previews point to an absolute
URL, which the plugin can only compute when [`site_url`][site_url] is set.
Example:
@@ -307,7 +303,7 @@ layers:
```
If the `size` is omitted, it defaults to the size of the layout. If the `offset`
-is omitted, it defaults to the top left corner, which is the defaut `origin`.
+is omitted, it defaults to the top left corner, which is the default `origin`.
Saving the layout and reloading renders:
![Layer size]
@@ -598,7 +594,7 @@ This will add two circles to the background:
### Tags
The new [built-in social plugin] gives full flexibility of the meta tags that
-are added to your site, which are necessary to instruct services like Twitter
+are added to your site, which are necessary to instruct services like X
or Discord how to display your social card. All default layouts use the following
set of tags, which you can copy to your layout and adapt:
@@ -632,7 +628,7 @@ tags:
twitter:image: "{{ image.url }}"
```
-Note that this examples makes use of [YAML anchors] to minify repetition. The
+Note that this example makes use of [YAML anchors] to minify repetition. The
`definitions` property is solely intended for the definition on aliases that
can then be referenced with anchors.
diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md
index 8ceaf1273b0..644ea45e667 100644
--- a/docs/setup/setting-up-tags.md
+++ b/docs/setup/setting-up-tags.md
@@ -27,6 +27,25 @@ For a list of all settings, please consult the [plugin documentation].
[plugin documentation]: ../plugins/tags.md
+#### Advanced settings
+
+
+
+
+
+The following advanced settings are currently reserved to our [sponsors]
+[Insiders]. They are entirely optional, and only add additional capabilities to
+the tags plugin:
+
+
+- [`listings_toc`][config.listings_toc]
+
+We'll add more settings here in the near future.
+
+ [Insiders]: ../insiders/index.md
+ [config.listings_layout]: ../plugins/tags.md#config.listings_layout
+ [config.listings_toc]: ../plugins/tags.md#config.listings_toc
+
### Tag icons and identifiers
@@ -159,19 +178,31 @@ search preview, which now allows to __find pages by tags__.
-The [built-in tags plugin] allows to define a file to render a [tags index]
-[tags.tags_file], which can be any page that is part of the `nav` section. To
-add a tags index, create a page, e.g. `tags.md`:
+The [built-in tags plugin] allows to define a file to render a tags index,
+which can be any page that is part of the `nav` section. To add a tags index,
+create a page, e.g. `tags.md`:
``` markdown
# Tags
Following is a list of relevant tags:
-[TAGS]
+
```
-The `[TAGS]` marker specifies the position of the tags index, i.e. it is
+Then in your `mkdocs.yml` file, add the following.
+
+``` yaml
+plugins:
+ - tags:
+ tags_file: tags.md # (1)!
+```
+
+1. This setting is not necessary when using [Insiders].
+
+Note that the path to `tags.md` is relative to the `docs/` directory.
+
+The tags marker specifies the position of the tags index, i.e. it is
replaced with the actual tags index when the page is rendered. You can include
arbitrary content before and after the marker:
@@ -180,6 +211,134 @@ arbitrary content before and after the marker:
[tags.tags_file]: #tags-file
[tags index enabled]: ../assets/screenshots/tags-index.png
+### Advanced features
+
+[Insiders] ships a __ground up rewrite of the tags plugin__ which is infinitely
+more powerful than the current version in the community edition. It allows
+for an arbitrary number of tags indexes (listings), [scoped listings],
+[shadow tags], [nested tags], and much more.
+
+ [scoped listings]: #scoped-listings
+ [shadow tags]: #shadow-tags
+ [nested tags]: #nested-tags
+
+#### Configurable listings
+
+
+
+
+
+Listings can be configured in `mkdocs.yml` or directly at the location of the
+marker that you position in a Markdown document. Some examples:
+
+- __Use [scoped listings]__: limit the tags index to pages that are on the same
+ level of the subsection of the documentation the page is in:
+
+ ``` html
+
+ ```
+
+- __List only specific tags__: limit the tags index to a single or multiple
+ selected tags, e.g., `Foo` and `Bar`, excluding all other tags:
+
+ ``` html
+
+ ```
+
+- __Exclude pages with specific tags__: don't include pages that are tagged
+ with specific tags, e.g. `Internal`. This can be any tag, including a shadow
+ tag:
+
+ ``` html
+
+ ```
+
+- __Enable or disable tags inside the table of contents__: specify whether the
+ table of contents lists all tags under the nearest headline:
+
+ ``` html
+
+ ```
+
+See the [listing configuration] for all options.
+
+ [listing configuration]: ../plugins/tags.md#listing-configuration
+
+#### Scoped listings
+
+
+
+
+
+If your documentation is large, you might want to consider using scoped listings
+which will only include pages that are on the same level or below the page
+containing the listing. Just use:
+
+``` html
+
+```
+
+If you plan to use multiple scoped indexes, it's a good idea to define a
+listing configuration in `mkdocs.yml`, which you can then reference by its id:
+
+``` yaml
+plugins:
+ - tags:
+ listings_map:
+ scoped:
+ scope: true
+```
+
+You can now use:
+
+``` html
+
+```
+
+#### Shadow tags
+
+
+
+
+
+Shadow tags are tags that are solely meant to organization, which can be
+included or excluded for rendering with a simple flag. They can be enumerated
+in the [`shadow_tags`][config.shadow_tags] setting:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags:
+ - Draft
+ - Internal
+```
+
+If a document is tagged with `Draft`, the tag will only be rendered if
+[`shadow`][config.shadow] setting is enabled, and excluded when it is disabled.
+This is an excellent opportunity for using tags for structuring.
+
+ [config.shadow]: ../plugins/tags.md#config.shadow
+ [config.shadow_tags]: ../plugins/tags.md#config.shadow_tags
+
+#### Nested tags
+
+
+
+
+
+[Insiders] ships support for nested tags. The
+[`tags_hierarchy_separator`][config.tags_hierarchy_separator] allows to create
+hierarchies of tags, e.g., `Foo/Bar`. Nested tags will be rendered as children
+of the parent tag:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy: true
+```
+
+ [config.tags_hierarchy_separator]: ../plugins/tags.md#config.tags_hierarchy_separator
+
### Hiding tags on a page
While the tags are rendered above the main headline, sometimes, it might be
diff --git a/docs/setup/setting-up-the-footer.md b/docs/setup/setting-up-the-footer.md
index ae816e19ffa..35194f27ba4 100644
--- a/docs/setup/setting-up-the-footer.md
+++ b/docs/setup/setting-up-the-footer.md
@@ -57,18 +57,18 @@ The following properties are available for each link:
This property must contain a valid path to any icon bundled with the theme,
or the build will not succeed. Some popular choices:
+ * :fontawesome-brands-github: – `fontawesome/brands/github`
+ * :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
+ * :fontawesome-brands-x-twitter: – `fontawesome/brands/x-twitter`
* :fontawesome-brands-mastodon: – `fontawesome/brands/mastodon`
automatically adds [`rel=me`][rel=me]
- * :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
- * :fontawesome-brands-github: – `fontawesome/brands/github`
* :fontawesome-brands-docker: – `fontawesome/brands/docker`
* :fontawesome-brands-facebook: – `fontawesome/brands/facebook`
- * :fontawesome-brands-medium: – `fontawesome/brands/medium`
* :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
* :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
- * :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
* :fontawesome-brands-slack: – `fontawesome/brands/slack`
* :fontawesome-brands-discord: – `fontawesome/brands/discord`
+ * :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md
index b7e83c02dcd..cc90634fa47 100644
--- a/docs/setup/setting-up-versioning.md
+++ b/docs/setup/setting-up-versioning.md
@@ -33,7 +33,7 @@ This renders a version selector in the header:
Check out the versioning example to see it in action –
-[squidfunk.github.io/mkdocs-material-example-versioning][version example]
+[mkdocs-material.github.io/example-versioning][version example]
@@ -52,7 +52,7 @@ Check out the versioning example to see it in action –
whatever version of the documentation you want to direct people to.
[Version selector preview]: ../assets/screenshots/versioning.png
- [version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
+ [version example]: https://mkdocs-material.github.io/example-versioning/
[Why use mike?]: https://github.com/jimporter/mike#why-use-mike
### Stay on the same page when switching versions
@@ -61,14 +61,12 @@ When the user chooses a version in the version selector, they usually want to go
to the page corresponding to the page they were previously viewing. Material for
MkDocs implements this behavior by default, but there are a few caveats:
-- the [`site_url`] must be set correctly in `mkdocs.yml`. See the ["Publishing a
- new version"](#publishing-a-new-version) section for an example.
-- you must be viewing the site at that URL (and not locally, for example).
+- the [`site_url`][mkdocs.site_url] must be set correctly in `mkdocs.yml`.
+ See the ["Publishing a new version"](#publishing-a-new-version) section for
+ an example.
- the redirect happens via JavaScript and there is no way to know which page you
will be redirected to ahead of time.
-[`site_url`]: https://www.mkdocs.org/user-guide/configuration/#site_url
-
### Version warning
@@ -131,6 +129,21 @@ redirected to.
[Version warning preview]: ../assets/screenshots/version-warning.png
[default version]: #setting-a-default-version
+### Version alias
+
+
+
+
+If you're using aliases for versioning, and want to show the version alias
+besides the version number, you can enable this feature by setting the `alias`
+option to `true`:
+
+``` yaml
+extra:
+ version:
+ alias: true
+```
+
## Usage
While this section outlines the basic workflow for publishing new versions,
diff --git a/docs/support.md b/docs/support.md
new file mode 100644
index 00000000000..e33e2d2633e
--- /dev/null
+++ b/docs/support.md
@@ -0,0 +1,67 @@
+# Support
+
+At the heart of Material for MkDocs is an open and supportive community dedicated
+to freely sharing knowledge and insights. We strive to offer support to this
+community, balancing our development efforts with the need to address community
+questions effectively.
+
+In order to streamline communication and direct you to the most appropriate
+support channel, we've outlined our support structure below.
+
+## Sponsoring support
+
+If you have questions about Insiders or are considering becoming a sponsor,
+@katharinalisalin is here to help. She handles all non-technical
+sponsorship-related inquiries and is happy to provide the guidance you need.
+Feel free to contact her at sponsors@squidfunk.com.
+
+## Technical support
+
+We are committed to providing technical support, ensuring all interactions
+remain transparent and accessible. Our primary channels for technical inquiries,
+therefore, are [our discussion board] and [our issue tracker] which are open to
+the entire community.
+
+ [our discussion board]: #discussion-board
+ [our issue tracker]: #issue-tracker
+
+
+### Discussion board
+
+Our [discussion board] serves as the primary point of contact for technical
+discussions, supported by both our community and our [Community Experts]. We
+encourage searching the board for existing answers before posting new questions.
+
+Direct support, particularly for core feature-related queries, is actively
+provided here, whereas customization tips are often sourced from and shared by
+our amazing community.
+
+ [Community Experts]: insiders/community-experts-program/index.md
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+
+### Issue Tracker
+
+For [reporting bugs] or submitting [change requests], our [issue tracker] offers
+a transparent platform for community contributions. We encourage reporting bugs
+found in the Insiders edition and in the community edition with the help of [our
+contributing guides] through the public [issue tracker], mindful of not
+disclosing the private Insiders' source code in line with our [fair use
+policy].
+
+This transparent approach ensures that solutions can benefit the entire
+community and feature requests can get upvoted by the community which will
+affect the speed of its development.
+
+ [reporting bugs]: contributing/reporting-a-bug.md
+ [change requests]: contributing/requesting-a-change.md
+ [our contributing guides]: ./contributing/index.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [public issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [fair use policy]: ./insiders/license.md/#fair-use-policy
+
+### Prioritized support
+
+Organizational sponsors at "The Organization" tier or higher are entitled to
+prioritized bug support. While we cannot guarantee immediate resolution, as
+some problems are harder to fix than others, it ensures that your issues are
+addressed with urgency.
diff --git a/docs/tutorials/blogs/basic.md b/docs/tutorials/blogs/basic.md
new file mode 100644
index 00000000000..5d193aba65e
--- /dev/null
+++ b/docs/tutorials/blogs/basic.md
@@ -0,0 +1,375 @@
+# Basic blogs
+
+Blogs are a great way to engage with your audience. Software developers can use
+a blog to announce new features, demonstrate their usage and provide background
+information. You can demonstrate competence by commenting on the state of the
+art or document your own work as best practice. Posts on current topics can help
+draw in visitors for your main website and can keep your audience engaged. Of
+course, you can blog about any topics close to your heart.
+
+The [blog plugin] makes running a blog alongside your other content easy but you
+can also configure it to run a stand-alone blog if posts are the only kind
+of content you need.
+
+After a brief overview of the basic concepts of a blog, this tutorial guides you
+through the process of configuring the [blog plugin], setting up your blog,
+creating posts, and defining post metadata.
+
+[blog plugin]: ../../plugins/blog.md
+
+__Time required:__ typically 20 minutes
+
+## Key concepts
+
+**Post, excerpt**: a blog consists of a number of self-contained _posts_ (often called
+articles) and an index page that shows the posts in reverse chronological order, with
+the most recent post at the top. The index page usually shows only a short _excerpt_ and a
+link that the user can click to navigate to the full post.
+
+**Metadata**: both the index page and the post itself list information such as
+when you published the post, when you updated it, who the author is, and what the
+expected reading time is.
+
+**Slug**: since the blog posts are primarily arranged by time and not into a hierarchy,
+their URLs do not reflect such a structure. Instead, each post's URL
+contains a shortened description, the _slug_, which is usually derived from
+the first heading in the post.
+
+**Navigation**: the main navigation structure is the timeline, which you can
+subdivide into _categories_. The main index page shows the more recent posts
+while an _archive_ section allows access to older ones, organized by year.
+In addition, posts can be _tagged_ and _tag index pages_ provide an additional
+navigation structure based on content.
+
+You can see all these elements on the [Material for MkDocs blog].
+
+[Material for MkDocs blog]: https://squidfunk.github.io/mkdocs-material/blog/
+
+## Setting up your blog
+
+The blog plugin is part of Material for MkDocs but you need to configure it
+in the `mkdocs.yml`.
+
+!!! example "Set up a blog"
+
+ If you have not done so already, create a project for your blog,
+ then edit the `mkdocs.yml` file to make sure if has the following content:
+
+ ```yaml
+ site_name: Blog Tutorial
+ site_description: an example blog set up following the tutorial
+ site_url: http://www.example.com
+
+ theme:
+ name: material
+
+ plugins:
+ - search
+ - blog
+ ```
+
+ The blog plugin will create a directory structure for your blog posts if it
+ does not exist, so simply run `mkdocs serve` to get:
+
+ ```
+ docs
+ ├── blog
+ │ ├── index.md
+ │ └── posts
+ └── index.md
+ ```
+
+Now create your first blog post in `docs/blog/posts`. You can use any
+naming convention and directory structure you like for your posts, as long as
+they are inside `docs/blog/posts`.
+
+Each post _must_ have a page header, which appears at the top of the Markdown
+code between lines with three dashes. Within this header, you need to have at
+least a `date` entry but you can add other data, as you will see below.
+Following the header comes the page content. Note that it is important
+to have a level one heading as the plugin uses it to produce the _slug_. Also,
+by adding `` to the page, you can define where the excerpt will end
+that the index page shows.
+
+!!! example "Write your first post"
+
+ Create a file `docs/blog/posts/myfirst.md` with the following contents:
+
+ ```
+ ---
+ date:
+ created: 2023-12-31
+ ---
+
+ # Happy new years eve!
+
+ We hope you are all having fun and wish you all the best for the new year!
+
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
+ ```
+
+ Then, run `mkdocs serve` and point your web browser at
+ `http://localhost:8000/blog`.
+
+ The blog plugin automatically creates navigation elements for
+ the blog. The index page shows only the extract. When you select the
+ "Continue reading" link, you will get to the full blog post. Note how it
+ has a URL generated from the first-level heading.
+
+!!! tip "Navigation"
+
+ We also have a [tutorial on navigation] that shows you how to change the
+ automatically created navigation and integrate the blog into your existing
+ navigation structure. It shows how to create secondary navigation, produce
+ author pages, and control pagination.
+
+[tutorial on navigation]: navigation.md
+
+## Post metadata
+
+In addition to the date, you can provide other metadata and give the plugin
+instructions, such as to treat a post as a draft or to pin it.
+
+### Drafts
+
+You may want to produce a draft of a blog post and work with it locally but
+exclude it from the build that you publish. Simply add a field to the page
+header to indicate that a post is still in draft form.
+
+!!! example "Create a draft"
+
+ Create a second blog post in `docs/blogs/posts/draft.md` with the following
+ contents:
+
+ ```hl_lines="3"
+ ---
+ date:
+ created: 2024-01-01
+ draft: true
+ ---
+
+ # Happy new year!
+
+ Happy 2024 to everyone. Wishing you all the best!
+
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
+ ```
+
+ Now, note how the draft appears on the index page but with a label that
+ indicates that it is a draft. When you run `mkdocs build`, the draft will
+ _not_ appear in the output:
+
+ ```
+ $ mkdocs build
+ $ ls site/blog
+ site/blog
+ ├── 2023
+ │ └── 12
+ │ └── 31
+ │ └── happy-new-years-eve
+ │ └── index.html
+ ...
+ ```
+
+ The first blog post for 2024 is not there yet because it is still in draft
+ stage. Remember to remove the `draft` setting in the header when it is time
+ to publish it.
+
+If you are using the [Insiders Edition], you can also create
+a folder to keep your drafts in and use the [Meta plugin] to add the
+`draft` header setting to all the posts in that folder. This has the advantage
+that it is easier to see which posts are still in draft form. We will cover the
+Meta plugin later on.
+
+[Meta plugin]: ../../plugins/meta.md
+
+### Edits
+
+Sometimes, bloggers need to update a post. This might happen when you make
+a mistake or when something changes that you need to reflect in the post. To
+indicate you have edited a post, you can include an `updated` date in the page
+header.
+
+!!! example "Editing a post"
+
+ Make a change to your first blog post, then add an edit date to the header:
+
+ ```hl_lines="3 4"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ ---
+ ```
+
+The Metadata section of the blog post itself will contain the edit date,
+though the index page omits this detail by default.
+
+### Reading time
+
+To give the reader some idea of how long it might take them to read a post,
+a read time is automatically calculated. If you want to override this, you can
+do so in the page header by specifying the number of minutes you estimate
+your readers will take the read the post.
+
+!!! example "Overriding the reading time"
+
+ Add a reading time override to your first blog post:
+
+ ```hl_lines="5"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ readtime: 15
+ ---
+ ```
+
+### Pinning
+
+Sometimes, blog authors want to 'pin' a specific post so that it will always
+appear at the top of the index page, no matter what else gets published. If you
+are using the [Insiders Edition], you can achieve this by adding the `pin`
+attribute in the page header:
+
+!!! example "Pin a post "
+
+ Add the `pin` attribute to your first blog post:
+
+ ```hl_lines="5"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ readtime: 15
+ pin: true
+ ---
+ ```
+
+ Observe how this makes the post appear on top of the index page even though
+ its publication date is prior to other posts. A small pin icon shows that the
+ post has been pinned.
+
+### Related links
+
+When your blog is part of a wider site such as technical documentation, you
+will want to provide links from blog posts into your other content. One way you
+can do this is to have a related links section. In the [Insiders Edition], the
+blog plugin can create one for you if you provide link targets in your page
+header:
+
+!!! example "Add a related links section "
+
+ Add the following to a blog post:
+
+ ``` hl_lines="5-7"
+ ---
+ date:
+ created: 2023-12-31
+ ...
+ links:
+ - index.md
+ - blog/index.md
+ ---
+ ```
+
+ The related links appear underneath the Metadata section.
+
+The nice thing here is that you do not need to provide a page title. The plugin
+will deduce the link text by applying the same logic that MkDocs uses for the
+main navigation. In fact, the syntax is the same as that of the `nav` section
+in the `mkdocs.yml`, so you can override the title if you want and even define
+subsections:
+
+!!! example "Override the page titles"
+
+ Change the link section to override the page titles:
+
+ ```hl_lines="6-9"
+ ---
+ date:
+ created: 2023-12-31
+ ...
+ links:
+ - Homepage: index.md
+ - Blog index: blog/index.md
+ - External links:
+ - Material documentation: https://squidfunk.github.io/mkdocs-material
+ ---
+ ```
+
+The plugin renders related links in the left sidebar on screens that are wide
+enough and at the bottom of the post on narrow screens. Change the size of your
+browser window to see this in action.
+
+## Meta plugin
+
+The Meta plugin is available in the [Insiders Edition].
+It helps simplify the management of metadata that is common to a group of
+files in the same subdirectory. Instead of having to repeat the
+same metadata in the page headers of a number of files, you can add a
+`.meta.yml` file in the directory and the Meta plugin will merge its contents
+into the headers of all the pages contained.
+Settings from the page header take precedence, so you can always override
+settings by adding them to a post's header.
+
+For example, you may want to manage drafts by keeping them in a directory
+together so that they are not only flagged as drafts but also easier to find.
+(Otherwise, you would need to inspect the page headers or trace back from the
+output to the files to figure out which posts are drafts.)
+
+!!! example "Drafts using the Meta plugin "
+
+ You first need to activate the plugin in your `mkdocs.yaml`:
+
+ ```yaml hl_lines="4"
+ plugins:
+ - search
+ - blog
+ - meta
+ ```
+
+ Now create the folder for the drafts:
+
+ === "MacOS/Linux"
+
+ ```bash
+ $ mkdir docs/blog/posts/drafts
+ ```
+
+ === "Windows"
+ TODO
+
+ Now, within this folder, crate a file `.meta.yml` that contains:
+
+ ```yaml
+ draft: true
+ ```
+
+ Add another blog post and store it in `docs/blog/posts/drafts`. When you
+ look at it locally, you will see the label that identifies it as a draft,
+ while in the version built for publication it does not appear. To move a
+ post from draft status to published, simply move it outside `drafts/`.
+
+[Insiders Edition]: ../../insiders/index.md
+
+## What's next?
+
+You should now have a working blog. However, as it accumulates content, you
+may want to make sure that people can find posts they are interested in, so
+you may want to add secondary navigation with tags and categories. You may
+have more than one author and want to attribute posts to them as well as
+generate author pages for them. We have a [tutorial on navigation, pagination,
+and authors] that covers these topics.
+
+[tutorial on navigation, pagination, and authors]: navigation.md
+
+You may want to increase engagement with your blog by allowing people to
+subscribe to an RSS feed or by setting up a comment system. The [engagement
+and dissemination tutorial] walks you through setting these up.
+
+[engagement and dissemination tutorial]: engage.md
diff --git a/docs/tutorials/blogs/engage.md b/docs/tutorials/blogs/engage.md
new file mode 100644
index 00000000000..31505a48dd8
--- /dev/null
+++ b/docs/tutorials/blogs/engage.md
@@ -0,0 +1,369 @@
+# Engagement and dissemination
+
+You can foster reader engagement and improve the dissemination of content
+on your blog by providing an RSS feed that people can subscribe to and by
+integrating a discussion system. To learn more about who is or is not reading
+your posts, you may want to integrate an analytics system. You may also want
+to post on social media when you public a new blog post. This tutorial gives
+you a leg up on all of these topics.
+
+__Time required:__ typically 30 minutes
+
+## RSS feeds
+
+An _RSS feed_ allows users to subscribe to a blog so that they get notified when
+you publish new posts. RSS Feed readers are often used to access blogs that a
+user follows. They usually support downloading the blog content for offline
+consumption.
+
+An easy way to create an RSS feed for your blog is to use the
+[MkDocs RSS Plugin], which is well integrated with Material for MkDocs.
+Since it is a third-party plugin, you need to install it before using it.
+
+[MkDocs RSS Plugin]: https://guts.github.io/mkdocs-rss-plugin
+
+
+!!! example "Add an RSS feed"
+
+ Install the RSS plugin into your project:
+
+ ```
+ $ pip install mkdocs-rss-plugin
+ ```
+
+ It is important that have the `site_name`, `site_description` and
+ `site_url` settings configured as [instructed in the basic blog tutorial].
+ The RSS plugin makes use of this information to construct the feed, so make
+ sure you have configured them.
+
+ [instructed in the basic blog tutorial]: basic.md#setting-up-your-blog
+
+ Now, configure the plugin in the `mkdocs.yml`. The options provided restrict
+ the pages that RSS entries are created for to the blog posts, which is
+ probably what you want. Also note the configuration of the date fields to
+ match the format that Material for MkDocs uses to accommodate both a
+ creation date and a date for updates.
+
+ ```yaml hl_lines="9"
+ plugins:
+ - ...
+ - rss:
+ match_path: "blog/posts/.*"
+ date_from_meta:
+ as_creation: date.created
+ as_update: date.updated
+ ```
+
+ Have a look at http://localhost:8000/feed_rss_created.xml to see the RSS
+ feed in all its XML glory. You can use a browser like Firefox or Chrome that
+ can display the raw RSS feed or use `curl` to get the feed and `xmllint` to
+ format it. (You may need to install these tools.)
+
+ ```
+ curl -s http://localhost:8000/feed_rss_created.xml | xmllint --format -
+ ```
+
+ You may also want to try your feed with a feed reader. There are various desktop
+ and mobile apps as well as online services. Of course, to use the latter you
+ will need to deploy your project somewhere that is accessible to them.
+
+This minimal configuration should work well if you have not made any changes
+to the default configuration of the blog plugin. For more information on adapting
+the feed to your needs, see [the RSS plugin's documentation].
+
+[the RSS plugin's documentation]: https://guts.github.io/mkdocs-rss-plugin/
+
+## Social media buttons
+
+Social media buttons can serve two purposes: to allow your readers to navigate
+to your social media profiles or to share content you have published via their
+own accounts.
+
+### Profile links
+
+Links to social media profiles a usually provided in the footer of pages and
+Material for MkDocs makes this easy. All you need to do is to provide the
+necessary links and define the icons to use.
+
+!!! example "Adding social media profile links"
+
+ Add an `extra` section to your `mkdocs.yml` and, within it, a `social`
+ section to contain a list of link definitions. These consist of the logo
+ to use and the link to the profile.
+
+ ```yaml
+ extra:
+ social:
+ - icon: fontawesome/brands/mastodon
+ name: squidfunk on Mastodon
+ link: https://fosstodon.org/@squidfunk
+ ```
+
+ For the `icon`, you can choose any valid path to an icon bundled with the
+ theme. The `name` will be used as the title attribute for the icon and
+ including this improves accessibility.
+ For popular social media systems, the link needs to be absolute and
+ needs to include the scheme, most likely `https://`.
+
+ You can also use other schemes. For example, to cerate an icon that allows
+ people to create an email, add this:
+
+ ```yaml
+ extra:
+ social:
+ - icon: /fontawesome/regular/envelope
+ name: send me an email
+ link: mailto:
+ ```
+
+ Finally, you can specify a URL within your site, such as to your contact
+ page. It is possible to specify only the path to the page:
+
+ ```yaml
+ extra:
+ social:
+ - icon: /material/mailbox
+ name: contact us
+ link: /contact
+ ```
+
+### Share and like buttons
+
+Adding buttons that let people share your content on social media is a bit
+more involved, which is why there are companies offering components for this.
+
+
+!!! tip "Data Protection"
+
+ "Share" and "Like" buttons that use integrations provided by social media
+ companies often leave copious data traces even when the user does not
+ interact with these buttons. If you choose to integate such feature on
+ your site please be aware of the data protection implications and your
+ duties as a provider to ensure that processing occurs only once the user
+ has granted consent.
+
+This implementation of share buttons deliberately does not use third party code.
+It supports sharing to Twitter/X and Facebook without causing a data flow to
+these companies whenever someone views the pages. Only when someone clicks a
+share button will there be interactions with those companies' servers.
+
+!!! example "Add share buttons"
+
+ In order to add the share buttons, you can add a hook that appends buttons
+ for sharing the current page.
+
+ Create a directory `hooks` in your project root and configure it
+ in your `mkdocs.yml`:
+
+ ```yaml
+ hooks:
+ - hooks/socialmedia.py
+ ```
+
+ Add the file `hooks/socialmedia.py` with the following Python code:
+
+ ```python
+ from textwrap import dedent
+ import urllib.parse
+ import re
+
+ x_intent = "https://x.com/intent/tweet"
+ fb_sharer = "https://www.facebook.com/sharer/sharer.php"
+ include = re.compile(r"blog/[1-9].*")
+
+ def on_page_markdown(markdown, **kwargs):
+ page = kwargs['page']
+ config = kwargs['config']
+ if not include.match(page.url):
+ return markdown
+
+ page_url = config.site_url+page.url
+ page_title = urllib.parse.quote(page.title+'\n')
+
+ return markdown + dedent(f"""
+ [Share on :simple-x:]({x_intent}?text={page_title}&url={page_url}){{ .md-button }}
+ [Share on :simple-facebook:]({fb_sharer}?u={page_url}){{ .md-button }}
+ """)
+ ```
+
+ The hook first checks if the current page is a blog post and then appends
+ Markdown code for the share buttons. The buttons use icons, so you also need
+ to configure the following markdown extensions:
+
+ ```yaml
+ markdown_extensions:
+ - attr_list
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ ```
+
+
+## Add a discussion system
+
+Allowing your readers to comment on your posts is a great way of receiving
+feedback, learning something, as well as giving readers the opportunity to
+discuss the content and the topic it is about.
+
+There are plenty of discussion system out there and you will need to consider
+your audience when choosing one appropriate for your blog. Likewise, you will
+also need to consider existing commitments to communication channels. If you
+are a heavy user Slack, for example, you may have a string preference for this
+system. Consider that when you add a communication channel, you will need to
+be prepared to use it regularly and to moderate discussions.
+
+### Giscus integration
+
+In this tutorial, we will be using [Giscus] because it is free, open source,
+and uses [GitHub Discussions] as a backend. Because a lot of users of Material
+for MkDocs use GitHub, this seems like an obvious choice.
+
+[Giscus]: https://giscus.app/
+[GitHub Discussions]: https://docs.github.com/en/discussions
+
+To add Giscuss to your blog you will need to go through a number of steps:
+
+1. Create a GitHub repository if there is not already one
+2. Turn on discussions and install the [Giscus app]
+3. Configure the code needed to embed Giscus into your blog
+4. Add the code to your MkDocs project
+
+[Giscus app]: https://github.com/apps/giscus
+
+You may want to create a test repository for this tutorial that you can
+scrap later on. The instructions below assume that you are user "example"
+and that you create a repository "giscus-test." The repository will need
+to be public for people to be able to use the discussions.
+
+In the instructions given below, you will need to replace at least the username
+but also the repository name if you chose another name such as when you
+want to work directly on an existing repository.
+
+!!! example "Turn on discussions and install the Giscus app"
+
+ Once the repository is set up, go to its settings page and find
+ `Features` in the `General` section. Tick the checkbox for `Discussions`.
+ You will see that `Discussions` appears in the top navigation for the
+ repository. If you are using a live repository then you may want to add some
+ minimal content to the dicussions section at this point and come back to the
+ tutorial.
+
+ Next, you need to install the [Giscus app] by following the link in this
+ sentence, and choosing `Install`, then following the instructions to choose
+ where the Giscus app is to be installed:
+
+ 1. Choose the account or organization for the repository you want to use.
+ 2. Choose to install only on select repositories and select the one you
+ want to use. Note that you can choose more than one repository here.
+ 3. Select `Install` at the end. You may need to authenticate to give
+ permission for this to happen.
+ 4. You will end up on the `Applications` page in your settings, where you
+ can control the Gicsus app and uninstall it if so desired.
+
+That is all the preparation you will need for the repository. Next, it is time
+to generate a piece of code that embeds Giscuss in your site. The resulting code
+snippet will look something like this:
+
+```html
+
+```
+
+!!! example "Configure the code needed to embed Giscus into your blog"
+
+ Go to the [Giscus homepage] and configure the embedding code. There are a
+ number of settings:
+
+ 1. Choose the language
+ 2. Enter the username / organization name and repository name
+ 3. Choose how the discussions are to be mapped to the page on your blog.
+ Because for a blog post the title is the basis of the URL, it makes
+ sense to use the `Discussion title contains page ` option.
+ 4. Under `Discussion Category` choose `Announcements` to limit the creation
+ of new discussions to Giscuss and people with maintainer or admin
+ permissions.
+ 5. Under `Features`, select the following:
+ 1. Enable reactions for the main post
+ 2. Emit discussion metadata
+ 3. Place the comment box above the comments
+ 6. Under `Theme`, select `Preferred color scheme` so that Giscus matches
+ the color scheme selected by the user for your site.
+
+[Giscus homepage]: https://giscus.app/
+
+With these settings in place, you now need to integrate the code into your
+site. There is a partial `partials/comments.html` that exists for this purpose
+and is empty be default. It is included by the `content.html` partial, so will
+be included for every page on your site. You may or may not want this. In this
+tutorial, you will limit the Giscus integration to only blog posts but it is
+easy enough to leave out the code that achieves this if you want to have Giscus
+discussions active for every page.
+
+!!! example "Add Giscus integration code"
+
+ First, you need to create an `overrides` directory that will contain the
+ templates and partials you want to override.
+
+ ```
+ mkdir -p overrides/partials
+ ```
+
+ You need to declare it in your `mkdocs.yaml`:
+
+ ```yaml hl_lines="3"
+ theme:
+ name: material
+ custom_dir: overrides
+ ```
+
+ Now add a file `overrides/partials/comments.html` and paste in the code
+ snippet you obtained from the Giscus homepage. Look at the result locally
+ and you will see that the integration is active on all pages of the site.
+ If you want to restrict it to your blog posts, you need to add a conditional
+ around the Giscus script that tests if comments should be included. A simple
+ way of doing this is to test for a metadata flag:
+
+ ```html
+ {% if page.meta.comments %}
+
+ {% endif %}
+ ```
+
+ The disadvantage is that you now need to manually turn on comments for each
+ blog post - unless you want to turn them off on some. To get the comments
+ section on all blog posts, use code like this:
+
+ ```html
+ {% if page.file.src_uri.startswith('blog/posts') %}
+
+ {% endif %}
+ ```
+
+ You should see now that the Giscus comments are added at the bottom of your
+ blog posts but not on other pages.
+
+## What's next?
+
+This is the end of the blog tutorial. We hope you have enjoyed it and manage to
+set up your blog the way you like it. There are numerous other features and
+options that we have not been able to cover here. The [blog plugin reference]
+provides comprehensive documentation for the plugin. You may also want to
+look at the [social plugin tutorial] to generate social cards for your blog
+posts that get displayed when you post links to social media systems.
+
+[blog plugin reference]: https://squidfunk.github.io/mkdocs-material/plugins/blog/
+[social plugin tutorial]: ../social/basic.md
diff --git a/docs/tutorials/blogs/navigation.md b/docs/tutorials/blogs/navigation.md
new file mode 100644
index 00000000000..f0b0c5c5230
--- /dev/null
+++ b/docs/tutorials/blogs/navigation.md
@@ -0,0 +1,525 @@
+# Navigation, authors, and pagination
+
+The Blog plugin provides blog-style navigation with a reverse-chronological
+index page and an archive organized by year by default. This tutorial shows
+how you can configure details of the default navigation, configure authors, and
+add more navigation options using categories and the [Tags plugin].
+
+[Tags plugin]: ../../plugins/tags.md
+
+__Time required:__ typically 30 minutes
+
+## Integrating navigation
+
+So far, you have let the Blog plugin and MkDocs worry about navigation. For some
+use cases, this might be enough and it is simply sufficient to not declare a
+`nav` section in the `mkdocs.yml`.
+
+However, you may want to integrate a blog with other content and a navigation
+structure that you have defined in the `nav` section of the configuration.
+In such cases, you need to provide a place where the Blog plugin should
+attach the blog navigation to the rest of the navigation structure.
+
+!!! example "Integrate with site navigation"
+
+ Add the following to your `mkdocs.yml` to see how the Blog plugin can
+ integrate the blog navigation with the overall navigation structure.
+ Note that the only thing you need to specify at this point is the
+ index page for the blog and its path must match the `blog_dir` setting,
+ which is `blog` by default:
+
+ ```yaml hl_lines="5 6"
+ nav:
+ - Home: index.md
+ - Install: install.md
+ - Usage: usage.md
+ - Blog:
+ - blog/index.md
+ ```
+
+ You will notice that "Blog" is duplicated in the navigation structure. To
+ avoid this, you can use the `navigation.indexes` feature to make the blog
+ index the section index page for the blog:
+
+ ```yaml hl_lines="3 4"
+ theme:
+ name: material
+ features:
+ - navigation.indexes
+ ```
+
+!!! tip "Stand-alone blog"
+
+ If what you need is a stand-alone blog instead of one that is integrated with
+ a larger site, this can be done by using the `blog_dir` configuration option.
+ To see how this is done, see [setting up a blog].
+ The rest of the tutorial assumes that you are integrating the blog with
+ a wider site.
+
+[Setting up a blog]: ../../setup/setting-up-a-blog.md#blog-only
+
+!!! tip "Adding pages"
+
+ You can add additional pages to the blog section by putting them into
+ `docs/blog` (and adding them to the navigation). The blog archive will be
+ added to the navigation after these pages.
+
+## Configuring the archive
+
+By default, the blog archive lists posts by year only. If you want to add
+listings by month, you can configure the date format for the archive.
+
+!!! example "Organize posts by month"
+
+ Add the following to your `mkdocs.yml` to get a listing with the month
+ name (in the language selected in the theme options):
+
+ ```yaml hl_lines="2"
+ - blog:
+ archive_date_format: MMMM yyyy
+ ```
+
+ If you do not want the full month name, you can make the the date
+ configuration `MM/yyyy`, for example.
+
+ If you want to add the day, you can add a placeholder for them.
+ For example, to get an American-style output, make it `MM/dd/yyyy`.
+ For the plugin to sort the blog posts by the full date, you will
+ also need to set the `archive_url_date_format` to include the month
+ and day, so make it `MM/dd/yyyy` as well.
+
+## Using categories
+
+Categories are a way to make blog posts accessible by topic while retaining
+the navigation structure based on chronology within each category listing.
+Use them when there is a limited set of non-overlapping categories that
+you can sort your posts into.
+
+Categories appear in the main navigation, so are directly accessible from there.
+This implies that there are relatively few categories as otherwise the
+`categories` section in your main navigation will become too crowded.
+
+
+!!! example "Add a category"
+
+ Add a category to your first blog post by adding it to the page header:
+
+ ``` hl_lines="4 5""
+ ---
+ date: 2023-12-31
+ updated: 2024-01-02
+ categories:
+ - Holidays
+ ---
+ ```
+
+ Now that the blog post has been categorised, `Holidays` appears under
+ `Categories` in the main navigation and the blog post appears in the
+ index page for this category.
+
+
+!!! tip "Single or multiple categories?"
+
+ While it is traditionally the case that a blog post would belong to only
+ one category, Material for MkDocs actually allows you to assign more
+ than one. While this gives you a degree of freedom, you should
+ probably not use this too much, not least because you can use tags to
+ deal with multiple classifications. We will cover them in the next step.
+
+Material allows you to control which categories blog authors can use. You
+declare them in the `mkdocs.yml`. This way you can make sure everyone sticks
+to agreed categories and that the plugin detects typos.
+
+!!! example "Control your categories"
+
+ Add a `categories_allowed` entry to the configuration of the Blog plugin
+ with the entries "Holidays" and "News":
+
+ ```yaml hl_lines="5-7"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ ```
+
+ Now, when you add a category to a blog post that does not match one of these
+ two, you should get a build error.
+
+## Using tags
+
+The [Tags plugin] provides another way to classify blog posts and to make
+them accessible independently of the main navigation structure. Tags are useful
+for making related content easily discoverable even if it is in different parts
+of the navigation hierarchy.
+
+[Tags plugin]: https://squidfunk.github.io/mkdocs-material/plugins/tags/
+
+You may have a tutorial like this one as well as a more comprehensive setup guide
+and reference documentation. Adding the same tag to all three shows that they
+are related. As you will see, it is possible to navigate from a tagged page to
+the tag index and, from there, to other pages that carry the same tag.
+
+!!! example "Enable the plugin and add tags"
+
+ First, you need to add the plugin to your `mkdocs.yml`:
+
+ ```yaml hl_lines="8"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ - tags
+ ```
+
+ Once this is done, you can add tags to posts in the page header:
+
+ ``` hl_lines="9-12""
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ authors:
+ - material
+ categories:
+ - Holidays
+ tags:
+ - new year
+ - hogmanay
+ - festive season
+ ---
+ ```
+
+You should see the tags that you defined at the top of the post. However, at the
+moment that is it. While the blog plugin automatically creates an index page for
+categories, the tags plugin does not do the same for tags. This is because the
+tags plugin is not specific for blogs. You can use it for any site content, so
+it is not obvious were the tag index should go.
+
+You can configure a basic tag index using the public version of Material for
+MkDocs. The Insider Edition supports this as well, of course, but also provides
+an alternative index mechanism that allows for an arbitrary number of tag
+indexes, scoped listings, shadow tags, nested tags, and much more.
+
+!!! example "Adding a tags index"
+ === "Basic tag index"
+
+ To configure a tag index using the public version, add a `tags_file` entry
+ to your configuration of the tags plugin and configure it in your `nav`
+ section. Remember to add a colon at the end of the existing `tags` entry.
+
+ ```yaml hl_lines="8-9 17"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ - tags:
+ tags_file: blog/tags.md
+
+ nav:
+ - Home: index.md
+ - Install: install.md
+ - Usage: usage.md
+ - Blog:
+ - blog/index.md
+ Tags: blog/tags.md
+ ```
+
+ The tag index will be appended to the configured page, which you should
+ now create at the location specified.
+
+ Note that you can put the tag index page anywhere in your primary
+ navigation, so if you are using tags elsewhere instead of just in your
+ blog then you may want to have the tag index outside the blog section
+ of the navigation.
+
+
+ === "Insider Edition"
+
+ To add a tag index, you add a placeholder in a Markdown file to tell
+ the plugin to insert an index at that point. This means that you
+ can add content before and after the index. Crucially, you can add
+ placeholders in multiple pages, each with a configuration of what
+ subset of tags should be displayed in the index.
+
+ The simplest index page looks like this. Create it under `docs/tags.md`.
+
+ ```markdown
+ # Tag index
+
+ ```
+
+ Now, you may want to keep the tags for your blog separate from tags
+ you use in the rest of your page. You can achieve this by assigning
+ the tag index a scope. Put the following under `docs/blog/tags.md`:
+
+ ```markdown
+ # Tag index for the blog
+
+ ```
+
+ You now have two index pages: one covers the whole site and one
+ covers only the blog. Add both to the navigation:
+
+ ```yaml
+ nav:
+ - Home: index.md
+ - Tags: tags.md
+ - Blog:
+ - blog/index.md
+ - blog/tags.md
+ ```
+
+ The tags plugin in the Insider Edition is an incredibly powerful tool
+ and we can only scratch the surface of what is possible with it. If you
+ want to explore more after you have worked for this part of the tutorial,
+ have a look at the [tags plugin reference].
+
+[tags plugin reference]: ../../plugins/tags.md
+
+## Defining authors
+
+If your blog has more than one author then you may want to identify the author
+for each blog post. The blog plugin allows you to create a file that contains
+the author information and to then reference the authors of a particular post in
+the page header.
+
+!!! example "Create author info"
+
+ Create a file `docs/blog/.authors.yml` with this content:
+
+ ```yaml
+ authors:
+ team:
+ name: Team
+ description: Creator
+ avatar: https://simpleicons.org/icons/materialformkdocs.svg
+ squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://github.com/squidfunk.png
+ ```
+
+ and then add a line to the header of the first post:
+
+
+ ```hl_lines="5-6"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ authors:
+ - team
+ ---
+ ```
+
+ Note that `authors` is a list, so you can specify multiple authors.
+
+With the Insiders edition, you can create custom author index pages that
+can highlight the contributions of an author as well as provide additional
+information about them.
+
+!!! example "Add author page "
+
+ First, you need to enable author profiles in the `mkdocs.yml`:
+
+ ```yaml hl_lines="8"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ authors_profiles: true
+ ```
+
+ Check your blog to see that there is now an extra entry in the main
+ navigation next to `archive` and `categories` that lists the authors and
+ their contributions.
+
+ To customize the author page, you can create a page that overrides the one
+ generated by default. First, create the `author` directory that the profile
+ pages will live in:
+
+ ```hl_lines="3"
+ docs
+ ├── blog
+ │ ├── author
+ │ ├── index.md
+ │ └── posts
+ │ ├── draft.md
+ │ └── myfirst.md
+ └── index.md
+ ```
+
+ Then create a page `docs/blog/author/team.md`:
+
+ ```
+ # The Material Team
+
+ A small group of people dedicated to making writing documentation easy, if
+ not outright fun! Here are some of the things we have blogged about:
+ ```
+
+ As you can see, the author index gets appended to the content you have
+ written in the Markdown file.
+
+## Pagination
+
+Once your blog starts growing, you may not want to pay attention to the number
+of posts displayed per page. By default, the plugin displays up to 10 posts on
+the index pages. You can change this number separately for the main index,
+the archive index pages, and the category index pages.
+
+!!! example "Changing pagination"
+
+ Add five more blog posts, then set the pagination setting to show five per
+ page only:
+
+ ```yaml hl_lines="7"
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ authors_profiles: true
+ pagination_per_page: 5
+ ```
+
+ You will see that the pagination setting for archive and category pages
+ are inherited from the setting you added. If you want to have different
+ settings for the different index pages, you can specify each setting
+ separately:
+
+ ```yaml
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ authors_profiles: true
+ pagination_per_page: 5
+ archive_pagination_per_page: 10
+ categories_pagination_per_page: 10
+ ```
+
+## Blog table of contents
+
+Another thing you may want to do once you have a large enough number of posts
+is to turn on the function that produces a table of contents for the blog
+index pages, giving your readers the opportunity to quickly scan the content
+of each page for something that interests them without having to scroll
+(assuming that the number of post per page is not too big).
+
+!!! example "Turn on the table of contents feature"
+
+ To produce a table of contents for the blog index pages, add the following
+ to the configuration of the blog plugin:
+
+ ```yaml hl_lines="2"
+ - blog:
+ blog_toc: true
+ archive_date_format: MMMM yyyy
+ # ...
+ ```
+
+## Custom slugs
+
+If, for some reason, you are not happy with the way that Material for MkDocs
+turns headings into slugs, you can create your own slugify function or you
+can manually define a slug for a specific post.
+
+!!! example "Slugify function"
+
+ To define your own slugify function, you need to write a Python function
+ that converts text into a slug given additional arguments from the
+ configuration. You also need to write a function that returns that
+ function.
+
+ Say you want to define two slugify functions that you can switch between.
+ The first one returns a slug similar to what the default slugify function
+ produces. The second one cuts the result of that up into words and returns
+ a slug based on a maximum of five of them:
+
+ ```python
+ import re, functools, unicodedata
+
+ RE_HTML_TAGS = re.compile(r'?[^>]*>', re.UNICODE)
+ RE_INVALID_SLUG_CHAR = re.compile(r'[^\w\- ]', re.UNICODE)
+ RE_WHITESPACE = re.compile(r'\s', re.UNICODE)
+
+ def _make_slug(text, sep, **kwargs):
+ slug = unicodedata.normalize('NFC', text)
+ slug = RE_HTML_TAGS.sub('', slug)
+ slug = RE_INVALID_SLUG_CHAR.sub('', slug)
+ slug = slug.strip().lower()
+ slug = RE_WHITESPACE.sub(sep, slug)
+ return slug
+
+ def _make_slug_short(text, sep, **kwargs):
+ words = _make_slug(text, sep, **kwargs).split(sep)
+ return sep.join(words[:5])
+
+ def slugify(**kwargs):
+ if 'short' in kwargs and kwargs['short']:
+ return functools.partial(_make_slug_short, **kwargs)
+ return functools.partial(_make_slug, **kwargs)
+ ```
+ Save this code in `ext/slugs.py` and also add an (empty) `__init__.py`
+ file to indicate that the directory is a module. Now you can configure
+ your custom slugify code like this:
+
+ ```yaml hl_lines="4-6"
+ plugins:
+ - blog:
+ # other entries omitted
+ post_slugify: !!python/object/apply:ext.slugs.slugify
+ kwds:
+ short: true
+ ```
+
+ Change the heading of a blog post to be longer than five words and observe
+ how the slugify function shortens the URL. Change the `short` attribute to
+ `false` and you can turn this off again.
+
+If you want to influence the slug only for a single blog post, you can define
+it manually by specifying it in the header of the post. Note that this is meant
+as a last resort option. Specifying a custom slug manually for every post would
+be tedious.
+
+!!! example "Manually define slug"
+
+ If, for example, you wanted the slug to be 'ny-eve' instead of the somewhat
+ lengthy 'happy-new-years-eve', you could add the following:
+
+ ```hl_lines="7"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ readtime: 15
+ pin: true
+ slug: ny-eve
+ ---
+ ```
+
+ The URL for this post should now be
+ `http://localhost:8000/blog/2023/01/31/ny-eve/`.
+
+## What's next?
+
+You may want to increase engagement with your blog by allowing people to
+subscribe to an RSS feed, by providing links to your social media profiles, by
+providing share and like buttons, or by setting up a comment system.
+The [engagement and dissemination tutorial] walks you through setting these up.
+
+[engagement and dissemination tutorial]: engage.md
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
new file mode 100644
index 00000000000..ddfd04dba95
--- /dev/null
+++ b/docs/tutorials/index.md
@@ -0,0 +1,58 @@
+# Tutorials
+
+In addition to the basic getting started guides, we offer tutorials that aim to
+show how you can use Material for MkDocs in different use cases. In contrast to
+the getting started guides or the reference documentation, the tutorials show
+the breadth of features available in Material for MkDocs but also within
+the wider MkDocs ecosystem.
+
+The tutorials guide you through worked examples, so by following them you should
+gain not only an understanding of how to use Material for MkDocs, but also
+a template for your own projects. For convenience, these templates are also
+available as template repositories on GitHub.
+
+The tutorials assume that you have installed either the [public version] or the
+[Insiders edition] of Material for MkDocs and that you have worked through the
+[creating your site] setup guide.
+
+Note that where the features we use require the Insiders edition, we mark these
+with the heart icon: If you are using the public version
+then you can skip these steps. Sometimes there will be ways of achieving the
+same goal that differ between the public version and the Insider edition. In
+that case, we will show them in a tabbed view so you can see one or the other.
+
+[public version]: ../getting-started.md
+[Insiders edition]: ../insiders/getting-started.md
+[creating your site]: ../creating-your-site.md
+
+!!! note "Feedback wanted!"
+ The tutorials are a recent addition to our documentation and we are still
+ working out what shape they should have in the end. Please [provide any
+ feedback you might have in this discussion thread].
+
+ Note, however, that suggestions should be specific and feasible. We want to
+ focus on creating more content at the moment, instead of developing a
+ specific styling or behaviour for the tutorials. If there are worthwhile
+ improvements that we can make through simple customization then we are happy
+ to consider those.
+
+[provide any feedback you might have in this discussion thread]: https://github.com/squidfunk/mkdocs-material/discussions/7220
+
+## Blogs
+* [Basics](blogs/basic.md) (20 min)
+ covers the basics of setting up a blog, including post metadata.
+* [Navigation, pagination, multiple authors](blogs/navigation.md) (30 min)
+ describes how to make it easier for your readers to find content.
+* [Engagement and dissemination](blogs/engage.md) (30 min)
+ walks you through ways of increasing engagement with your content.
+
+[:octicons-repo-template-24: Template Repository](https://github.com/mkdocs-material/create-blog)
+
+## Social cards
+* [Basics](social/basic.md) (20 min)
+ shows you how to configure Material for MkDocs to create social cards for
+ your content.
+* [Custom cards](social/custom.md) (15 min)
+ shows you how to design your own custom social cards.
+
+[:octicons-repo-template-24: Template Repository](https://github.com/mkdocs-material/create-social-cards)
diff --git a/docs/tutorials/social/basic.md b/docs/tutorials/social/basic.md
new file mode 100644
index 00000000000..aaea6c7f6bd
--- /dev/null
+++ b/docs/tutorials/social/basic.md
@@ -0,0 +1,203 @@
+# Basic social cards
+
+Social cards are images that other systems such as social media can display as
+a preview for content linked to. It is easy to get started with the social
+plugin, true to the motto of Material with MkDocs: "batteries included."
+
+## Basics
+
+Before you start, there are just a couple of [dependencies to install]. These
+are libraries for image processing that the plugin needs to produce the social
+cards, as well as their Python bindings.
+
+[dependencies to install]: https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/
+
+With those prerequisites met, it is simply a matter of activating the plugin,
+which will:
+
+* produce the social cards as PNG images for each page in your site;
+* create meta data in the headers of your site's pages that will provide
+ social media systems with key information and tell them how to find the
+ social card image.
+
+!!! example "Add social cards"
+
+ Simply add the social plugin to your list of plugins:
+
+ ```yaml hl_lines="3"
+ plugins:
+ - search
+ - social
+ - ...
+ ```
+
+Now, when you run `mkdocs build` and look at the `site` directory, you will
+see that it contains subfolders under `assets/images/social` that reflect
+the structure of your Markdown files. Each page has a corresponding PNG file
+that contains the social card image.
+
+Have a look at the generated HTML and you will see the metadata produced in
+the `head` element, including one entry that points to the image.
+
+## Background color
+
+The social plugin has configuration options for changing aspects such as colors,
+images, fonts, logos, the title, even the description. You can configure them
+for all social cards in the `mkdocs.yml` and, in the Insiders Edition, they can
+be overridden in the page header for individual pages.
+
+!!! example "Change the background color"
+
+ To change the background color to an attention-grabbing hot pink,
+ you might add:
+
+ ```yaml hl_lines="4-5"
+ plugins:
+ ...
+ - social:
+ cards_layout_options:
+ background_color: "#ff1493"
+ ```
+
+## Logos
+
+By default, the plugin uses the logo that you set for the whole site, either
+through the `theme.logo` or the `theme.icon.logo` setting. The difference
+between the two is that the `theme.icon.logo` version will directly embed the
+logo's SVG code into the HTML, allowing it to inherit CSS color settings. When
+you use `theme.logo`, the Material includes the logo as an image.
+
+You can set your own logo specific for the social cards as well. The path used
+is relative to your project root and needs to point to an SVG file or a pixel
+image. It should be rectangular and have a transparent background.
+
+!!! example "Set your own logo"
+
+ ```yaml hl_lines="3-4"
+ plugins:
+ - social:
+ cards_layout_options:
+ logo: docs/assets/images/ourlogo.png
+ ```
+
+## Background images
+
+In addition to adding your own logo, the most impactful way to personalize your
+social cards is to add a background image instead of the default solid color
+background. Make sure you choose one that will contrast well with the other
+elements of the card.
+
+Also, the background color gets rendered *on top of* the background image,
+allowing you to use a transparent color to tint an image. To use just the image,
+use the color value `transparent`.
+
+!!! example "Add background image"
+
+ ```yaml hl_lines="4 5"
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: transparent
+ ```
+
+The path to the background image is resolved from the root of your project,
+so this is where you should make the `layouts` directory and place the
+background image. The default site of the social cards included with the plugin
+is 1200x630 pixels, so choose an image that size or one that scales well to it.
+
+## Additional layouts and styles
+
+The Insiders Edition provides additional layouts as well as the option to
+configure different styles for different (kinds of) pages.
+
+The Insiders Edition comes with a number of additional layouts for the social
+cards. For example, the `default/variant` layout adds a page icon to the card.
+You can use this to distinguish social cards visually, depending on what kind
+of page you are sharing.
+
+For example, imagine you have a set of pages that advertise events and you want
+to include a calendar icon as a visual indication that a card advertises an
+event. In the following, you will set up a directory for event pages and use
+the meta plugin to assign them a calendar icon.
+
+!!! example "Social cards for event pages"
+
+ First, create a directory in your `docs` directory to hold the event pages:
+
+ ```
+ $ mkdir docs/events
+ ```
+
+ Then, add a file `.meta.yml` inside this new directory with settings for
+ the page icon and a hot pink background color that will stand out on
+ social media. Note that you can override the background image by setting it
+ to `null` here since it is not visible anyway because of the opaque coloring.
+
+ ```yaml
+ ---
+ icon: material/calendar-plus
+ social:
+ cards_layout_options:
+ background_image: null
+ background_color: "#ff1493"
+ ---
+ ```
+
+ Now add a page within the `docs/events` directoy. It does not need to have
+ any special content, just a top level header.
+
+ To turn on the `default/variant` layout in `mkdocs.yml`, add the
+ `cards_layout` option and also add the meta plugin:
+
+ ```yaml
+ plugins:
+ - meta
+ - social:
+ cards_layout: default/variant
+ ```
+
+ After running `mkdocs build`, you can see that the social card at
+ `site/assets/images/social/events/index.png` features the page icon.
+
+Note that the icon will also appear next to the navigation element for the
+page. If that is not what you want then you will need to modify the social
+card template to gets its icons from another source. You can learn how to
+do this in the [custom social cards tutorial](custom.md).
+
+## Per-page settings
+
+With the Insiders Edition, you can customize the card layout for each
+page by adding settings to the page header. You have effectively done this
+in the previous exercise, but using the meta plugin to affect a whole set of
+pages.
+
+Say that in addition to regular events you also have the odd webinar and
+for this you want to set a different icon and also set the description to
+indicate that the event is part of the webinar series.
+
+!!! example "Override card style in page header"
+
+ Add the following to the top of the page in `docs/events` or create a new
+ one:
+
+ ```yaml
+ ---
+ icon: material/web
+ social:
+ cards_layout_options:
+ description: Our Webinar Series
+ ---
+ ```
+
+## What's next?
+
+With the Insiders Edition, you can also define custom layouts if the
+configuration options introduced above as not enough to meet your needs.
+Continue to the [custom social cards tutorial](custom.md) if you want to
+find out how to do this.
+
+Social cards are particularly useful for blog posts. If you have a blog,
+you need to do nothing more than to turn on both plugins to create social cards
+to advertise your latest blog posts. If you do not have one yet but would like
+to, why not check out the [blog tutorials](../index.md#blogs)?
diff --git a/docs/tutorials/social/custom.md b/docs/tutorials/social/custom.md
new file mode 100644
index 00000000000..fdc08d26f2f
--- /dev/null
+++ b/docs/tutorials/social/custom.md
@@ -0,0 +1,142 @@
+# Custom cards
+
+The Insiders Edition allows you to define custom layouts for your social cards
+to suit your specific needs if the configuration options are not enough.
+For example, you may want to define a social card to advertise a new release
+of your product. It should have an icon indicating a launch announcement as
+well as the version number of the release on the card.
+
+## Setup
+
+You can either design a custom layout from scratch or use an existing layout
+as the basis that you add to or otherwise modify. In this tutorial, you will
+use the default layout as the basis.
+
+!!! example "Copy default layout to customize "
+
+ Copy the default social card layout from your installation of Material
+ for MkDocs to a new directory `layouts`. The instructions below assume you
+ are in your project root and have a virtual environment within this. The
+ path on your machine, of course, may differ.
+
+ ```
+ $ mkdir layouts
+ $ cp venv/lib/python3.12/site-packages/material/plugins/social/templates/default/variant.yml \
+ layouts/release.yml
+ ```
+
+ Before customizing the social cards, you need to tell the plugin where to
+ find them as well as tell MkDocs to watch for any changes. Add the following
+ to the plugin configuration in your `mkdocs.yml`:
+
+ ``` yaml hl_lines="2-6"
+ plugins:
+ - social:
+ cards_layout_dir: layouts
+
+ watch:
+ - layouts
+ ```
+
+Have a look at the contents of `release.yml`. You will see that there are:
+
+* a number of definitions of content pulled from the site,
+* definitions of tags that end up in the `meta` elements in the page header
+ of each page,
+* a specification that consists of a number of layers that the social plugin
+ applies on top of each other in the order in which they are defined.
+
+## Define page metadata
+
+In the following, you will add a version number to the social card. This
+assumes you have a changelog page with information about each release.
+Add the version number of the latest version to the page header (so it does
+not need to be parsed out of the Markdown content):
+
+!!! example "Defining the release data "
+
+ Create a page `docs/changelog.md` with the following content:
+
+ ```yaml
+ ---
+ icon: material/rocket-launch-outline
+ social:
+ cards_layout: release
+ cards_layout_options:
+ title: New release!
+ latest: 1.2.3
+ ---
+
+ # Releases
+ ```
+
+## Extract page metadata
+
+With the data defined in the page header, you can now add code to the layout
+that pulls it out and makes it available to render later on. This is to separate
+the data manipulation from the actual layout instructions and so make the
+layout file easier to read.
+
+!!! example "Adding data definitions"
+
+ Add the following at the top of the layout file:
+
+ ```yaml hl_lines="2-9"
+ definitions:
+ - &latest >-
+ {%- if 'latest' in page.meta %}
+ {{ page.meta['latest']}}
+ {%- else -%}
+ No release version data defined!
+ {%- endif -%}
+ ```
+
+The code presented here checks whether the page header contains the necessary
+entries and spits out a message to the social card if not. Unfortunately, there
+is no straightforward way to raise an exception or log an error, so the messages
+merely appear in the social card produced.
+
+## Add release version layer
+
+The next step is to use these data definitions in a new layer and add it to the
+ones already present.
+
+!!! example "Render release version"
+
+ Finally, add the following to end of the custom layout:
+
+ ```yaml
+ - size: { width: 990, height: 50 }
+ offset: { x: 50, y: 360 }
+ typography:
+ content: *latest
+ align: start
+ color: *color
+ ```
+
+You should now see the social plugin use the custom layout on the changelog page
+you set up.
+
+## Adjust layout
+
+Finally, the rocket icon used for the changelog page is not quite in the right
+position. Find the please where the `page_icon` variable is used to create the
+page icon layer and adjust the horizontal position to 600 instead of 800.
+
+!!! tip "Debugging layout files"
+
+ Should you find that your layouts are causing your MkDocs build to fail,
+ there are a number of things you can do:
+
+ 1. Run Mkdocs with the `--verbose` option to get more detailed reporting.
+ 2. Comment out things you recently added or that you suspect are the cause
+ 3. Install the `jinja2` command-line tool with `pip install Jinja2` and
+ run it over your layout file, for example: `jinja2 event.yml`.
+
+## What's next?
+
+If you do not have a blog yet, why not check out the
+[blog tutorials](../index.md#blogs) and learn how to set one up? The social
+plugin will help you draw attention to your posts on social media.
+
+Check out the [other tutorials](../index.md) we have prepared for you.
\ No newline at end of file
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 24defe9f5ae..bab2d290fff 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -146,7 +146,7 @@ viewports]:
```
[Tabbed]: setup/extensions/python-markdown-extensions.md#tabbed
- [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
+ [better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214
#### `pymdownx.superfences`
diff --git a/includes/debug/cairo-lookup-linux.py b/includes/debug/cairo-lookup-linux.py
new file mode 100644
index 00000000000..5f9fc557acd
--- /dev/null
+++ b/includes/debug/cairo-lookup-linux.py
@@ -0,0 +1,111 @@
+import inspect
+import os
+import shutil
+import subprocess
+from ctypes import util
+
+
+class CustomPopen(subprocess.Popen):
+
+ def __init__(self, *args, **kwargs):
+ print(f"Subprocess command:\n {' '.join(args[0])}")
+ super().__init__(*args, **kwargs)
+
+ def communicate(self, *args, **kwargs):
+ out, _ = super().communicate(*args, **kwargs)
+ out = out.rstrip()
+ print("Subprocess output:")
+ if out:
+ print(f" {os.fsdecode(out)}")
+ else:
+ print(f" Output is empty")
+ return out, _
+
+ def __getattribute__(self, name_):
+ att = super().__getattribute__(name_)
+ if name_ == "stdout" and att is not None:
+ att.read = self.read_wrapper(att.read)
+ return att
+
+ @staticmethod
+ def read_wrapper(func):
+
+ if func.__name__ == "wrapper":
+ return func
+
+ def wrapper(*args, **kwargs):
+ output = func(*args, **kwargs)
+ print("Subprocess output:")
+ for line_ in os.fsdecode(output).split("\n"):
+ print(line_)
+ return output
+
+ return wrapper
+
+
+subprocess.Popen = CustomPopen
+
+print("ctypes.util script with the find_library:")
+print(inspect.getsourcefile(util.find_library), end="\n\n")
+
+print("find_library function:")
+func_lines = list(map(str.rstrip, inspect.getsourcelines(util.find_library)[0]))
+indent = len(func_lines[0]) - len(func_lines[0].lstrip())
+for line in func_lines:
+ print(line.replace(" " * indent, "", 1))
+
+library_names = ("cairo-2", "cairo", "libcairo-2")
+filenames = ("libcairo.so.2", "libcairo.2.dylib", "libcairo-2.dll")
+c_compiler = shutil.which("gcc") or shutil.which("cc")
+ld_env = os.environ.get("LD_LIBRARY_PATH")
+first_found = ""
+
+print("\nLD_LIBRARY_PATH =", ld_env, end="\n\n")
+
+for name in library_names:
+ if hasattr(util, "_findSoname_ldconfig"):
+ result = util._findSoname_ldconfig(name)
+ print(f"_findSoname_ldconfig({name}) ->", result)
+ if result:
+ print(f"Found {result}")
+ if not first_found:
+ first_found = result
+ print("---")
+ if c_compiler and hasattr(util, "_findLib_gcc"):
+ result = util._findLib_gcc(name)
+ print(f"_findLib_gcc({name}) ->", result)
+ if result and hasattr(util, "_get_soname"):
+ result = util._get_soname(result)
+ if result:
+ print(f"Found {result}")
+ if not first_found:
+ first_found = result
+ print("---")
+ if hasattr(util, "_findLib_ld"):
+ result = util._findLib_ld(name)
+ print(f"_findLib_ld({name}) ->", result)
+ if result and hasattr(util, "_get_soname"):
+ result = util._get_soname(result)
+ if result:
+ print(f"Found {result}")
+ if not first_found:
+ first_found = result
+ print("---")
+ if hasattr(util, "_findLib_crle"):
+ result = util._findLib_crle(name, False)
+ print(f"_findLib_crle({name}) ->", result)
+ if result and hasattr(util, "_get_soname"):
+ result = util._get_soname(result)
+ if result:
+ print(f"Found {result}")
+ if not first_found:
+ first_found = result
+ print("---")
+
+if first_found:
+ filenames = (first_found,) + filenames
+
+print(f"The path is {first_found or 'not found'}")
+print("List of files that FFI will try to load:")
+for filename in filenames:
+ print("-", filename)
diff --git a/includes/debug/cairo-lookup-macos.py b/includes/debug/cairo-lookup-macos.py
new file mode 100644
index 00000000000..7ec8367c90b
--- /dev/null
+++ b/includes/debug/cairo-lookup-macos.py
@@ -0,0 +1,49 @@
+import os
+from ctypes.macholib import dyld
+from itertools import chain
+
+library_names = ("cairo-2", "cairo", "libcairo-2")
+filenames = ("libcairo.so.2", "libcairo.2.dylib", "libcairo-2.dll")
+first_found = ""
+names = []
+
+for name in library_names:
+ names += [
+ "lib%s.dylib" % name,
+ "%s.dylib" % name,
+ "%s.framework/%s" % (name, name),
+ ]
+
+for name in names:
+ for path in dyld.dyld_image_suffix_search(
+ chain(
+ dyld.dyld_override_search(name),
+ dyld.dyld_executable_path_search(name),
+ dyld.dyld_default_search(name),
+ )
+ ):
+ if os.path.isfile(path):
+ print(f"Found: {path}")
+ if not first_found:
+ first_found = path
+ continue
+
+ try:
+ if dyld._dyld_shared_cache_contains_path(path):
+ print(f"Found: {path}")
+ if not first_found:
+ first_found = path
+ continue
+ except NotImplementedError:
+ pass
+
+ print(f"Doesn't exist: {path}")
+ print("---")
+
+if first_found:
+ filenames = (first_found,) + filenames
+
+print(f"The path is {first_found or 'not found'}")
+print("List of files that FFI will try to load:")
+for filename in filenames:
+ print("-", filename)
diff --git a/includes/debug/cairo-lookup-windows.py b/includes/debug/cairo-lookup-windows.py
new file mode 100644
index 00000000000..70ed286a802
--- /dev/null
+++ b/includes/debug/cairo-lookup-windows.py
@@ -0,0 +1,31 @@
+import os
+
+library_names = ("cairo-2", "cairo", "libcairo-2")
+filenames = ("libcairo.so.2", "libcairo.2.dylib", "libcairo-2.dll")
+first_found = ""
+names = []
+
+for name in library_names:
+ if name.lower().endswith(".dll"):
+ names += [name]
+ else:
+ names += [name, name + ".dll"]
+
+for name in names:
+ for path in os.environ["PATH"].split(os.pathsep):
+ resolved_path = os.path.join(path, name)
+ if os.path.exists(resolved_path):
+ print(f"Found: {resolved_path}")
+ if not first_found:
+ first_found = resolved_path
+ continue
+ print(f"Doesn't exist: {resolved_path}")
+ print("---")
+
+if first_found:
+ filenames = (first_found,) + filenames
+
+print(f"The path is {first_found or 'not found'}")
+print("List of files that FFI will try to load:")
+for filename in filenames:
+ print("-", filename)
diff --git a/includes/mkdocs.md b/includes/mkdocs.md
index fc3629eae95..67f7491c06b 100644
--- a/includes/mkdocs.md
+++ b/includes/mkdocs.md
@@ -3,7 +3,9 @@
[mkdocs.metadata]: https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data
[mkdocs.env]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
[mkdocs.docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+ [mkdocs.extra_templates]: https://www.mkdocs.org/user-guide/configuration/#extra_templates
[mkdocs.site_dir]: https://www.mkdocs.org/user-guide/configuration/#site_dir
+ [mkdocs.site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
[mkdocs.site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
[mkdocs.nav]: https://www.mkdocs.org/user-guide/configuration/#nav
[mkdocs.plugins]: https://www.mkdocs.org/user-guide/configuration/#plugins
diff --git a/material/__init__.py b/material/__init__.py
index 36c6b4c9b02..c0ef38c8efc 100644
--- a/material/__init__.py
+++ b/material/__init__.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 Martin Donath
+# Copyright (c) 2016-2024 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
@@ -18,4 +18,4 @@
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
-__version__ = "9.4.6"
+__version__ = "9.5.43"
diff --git a/material/extensions/__init__.py b/material/extensions/__init__.py
index d1899378578..9c58b37928d 100644
--- a/material/extensions/__init__.py
+++ b/material/extensions/__init__.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 Martin Donath
+# Copyright (c) 2016-2024 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
diff --git a/material/extensions/emoji.py b/material/extensions/emoji.py
index c8c955cc4b3..df886f6b046 100644
--- a/material/extensions/emoji.py
+++ b/material/extensions/emoji.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2023 Martin Donath
+# Copyright (c) 2016-2024 Martin Donath
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
diff --git a/material/overrides/assets/javascripts/custom.4e50d00f.min.js b/material/overrides/assets/javascripts/custom.4e50d00f.min.js
new file mode 100644
index 00000000000..9c08361e06c
--- /dev/null
+++ b/material/overrides/assets/javascripts/custom.4e50d00f.min.js
@@ -0,0 +1,5 @@
+"use strict";(()=>{var go=Object.create;var Ar=Object.defineProperty;var wo=Object.getOwnPropertyDescriptor;var So=Object.getOwnPropertyNames,et=Object.getOwnPropertySymbols,Eo=Object.getPrototypeOf,tt=Object.prototype.hasOwnProperty,Oo=Object.prototype.propertyIsEnumerable;var rt=(e,r,t)=>r in e?Ar(e,r,{enumerable:!0,configurable:!0,writable:!0,value:t}):e[r]=t,Je=(e,r)=>{for(var t in r||(r={}))tt.call(r,t)&&rt(e,t,r[t]);if(et)for(var t of et(r))Oo.call(r,t)&&rt(e,t,r[t]);return e};var Me=(e,r)=>()=>(r||e((r={exports:{}}).exports,r),r.exports);var To=(e,r,t,o)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of So(r))!tt.call(e,n)&&n!==t&&Ar(e,n,{get:()=>r[n],enumerable:!(o=wo(r,n))||o.enumerable});return e};var ot=(e,r,t)=>(t=e!=null?go(Eo(e)):{},To(r||!e||!e.__esModule?Ar(t,"default",{value:e,enumerable:!0}):t,e));var De=Me(Z=>{(function(){var e,r,t,o,n,i,f,u,c,a,s,p,d,l,m,h,b,w,E,k;k=150,a=20,E=150,c=.75,Z.score=function(v,x,S){var T,y,g,_;return y=S.preparedQuery,T=S.allowErrors,T||n(v,y.core_lw,y.core_up)?(_=v.toLowerCase(),g=r(v,_,y),Math.ceil(g)):0},Z.isMatch=n=function(v,x,S){var T,y,g,_,W,U,L;if(g=v.length,_=x.length,!g||_>g)return!1;for(T=-1,y=-1;++y<_;){for(W=x.charCodeAt(y),U=S.charCodeAt(y);++T-1)return m(v,x,de,te,fe,Q,N);for(Ae=new Array(Q),W=new Array(Q),_r=w(Q,N),V=Math.ceil(c*Q)+5,re=V,L=!0,M=-1;++Mce&&(ce=Ke),U=0,te[M]===Or)if(Tr=u(j,v,x),U=_>0?_:d(v,x,de,te,j,M,Tr),g=Er+p(j,M,Tr,y,U),g>ce)ce=g,re=V;else{if(ye&&--re<=0)return Math.max(ce,Ae[Q-1])*_r;ye=!1}Er=Ke,_=W[M],W[M]=U,Ae[M]=ce}}return ce=Ae[Q-1],ce*_r},Z.isWordStart=u=function(v,x,S){var T,y;return v===0?!0:(T=x[v],y=x[v-1],i(y)||T!==S[v]&&y===S[v-1])},Z.isWordEnd=f=function(v,x,S,T){var y,g;return v===T-1?!0:(y=x[v],g=x[v+1],i(g)||y===S[v]&&g!==S[v+1])},i=function(v){return v===" "||v==="."||v==="-"||v==="_"||v==="/"||v==="\\"},b=function(v){var x;return vy?T:y)+10):g+k*y},Z.scoreConsecutives=d=function(v,x,S,T,y,g,_){var W,U,L,j,M,N,V;for(U=v.length,j=S.length,L=U-y,M=j-g,W=L-1&&(M=u(L,v,x),M&&(y=L))),U=-1,j=0;++U1&&L>1))return t;for(y=0,V=0,re=0,M=0,_=-1,W=-1;++W-1){V++;continue}else break;for(;++_12*W)return!1;for(g=-1;++g<_;)if(u(g,v,x)&&++y>T)return!1;return!0}}).call(Z)});var wr=Me(Qe=>{(function(){var e,r,t,o,n,i,f,u,c,a;a=De(),i=a.isMatch,e=a.computeScore,u=a.scoreSize,c=20,t=2.5,Qe.score=function(s,p,d){var l,m,h,b;return m=d.preparedQuery,l=d.allowErrors,l||i(s,m.core_lw,m.core_up)?(b=s.toLowerCase(),h=e(s,b,m),h=f(s,b,h,d),Math.ceil(h)):0},f=function(s,p,d,l){var m,h,b,w,E,k,v,x,S,T;if(d===0)return 0;for(S=l.preparedQuery,T=l.useExtensionBonus,x=l.pathSeparator,E=s.length-1;s[E]===x;)E--;if(b=s.lastIndexOf(x,E),v=E-b,k=1,T&&(k+=n(p,S.ext,b,E,2),d*=k),b===-1)return d;for(w=S.depth;b>-1&&w-- >0;)b=s.lastIndexOf(x,b-1);return h=b===-1?d:k*e(s.slice(b+1,E+1),p.slice(b+1,E+1),S),m=.5*c/(c+r(s,E+1,x)),m*h+(1-m)*d*u(0,t*v)},Qe.countDir=r=function(s,p,d){var l,m;if(p<1)return 0;for(l=0,m=-1;++m