- 
- 
- 
@@ -48,7 +44,7 @@
- Check out the demo –
+ Check out the demo –
squidfunk.github.io/mkdocs-material.
diff --git a/docs/contributing/adding-translations.md b/docs/contributing/adding-translations.md
new file mode 100644
index 000000000..dbbc4edc7
--- /dev/null
+++ b/docs/contributing/adding-translations.md
@@ -0,0 +1,125 @@
+# Translations
+
+It's unbelievable – with the help of international community contributions,
+Material for MkDocs has been translated into 60+ languages. As you can imagine,
+it's impossible for us maintainers to keep all languages up-to-date, and new
+features sometimes require new translations.
+
+If you would like to help us to make Material for MkDocs even more globally
+accessible and have noticed a missing translation in your language, or would
+like to add a new language, you can help us by following the steps of the guide
+below.
+
+## Before creating an issue
+
+Translations change frequently, which is why we want to make sure that you don't
+invest your time in duplicating work. Before adding translations, please check
+the following things:
+
+### Check language availability
+
+With more than 60 languages, the chances are good that your language is already
+supported by Material for MkDocs. You can check if your language is available,
+or needs improvements or additional translations by inspecting the list of
+[supported languages]:
+
+- __Your language is already supported__ – in this case, you can check if there
+ are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
+
+- __Your language is missing__ – in that case, you can help us add support
+ for your language to Material for MkDocs! Read on, to learn how to do this.
+
+ [supported languages]: ../setup/changing-the-language.md#site-language
+
+### Search our issue tracker
+
+Another user might have already created an issue supplying the missing
+translations for your language that still needs to be integrated by us
+maintainers. To avoid investing your time in duplicated work, please search the
+[issue tracker] beforehand.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+---
+
+At this point, when you have made sure that Material for MkDocs doesn't already
+support your language, you can add new translations for it by following the
+issue template.
+
+## Issue template
+
+We have created an issue template that makes contributing translations as simple
+as possible. It is the result of our experience with 60+ language contributions
+and updates over the last couple of years, and consists of the following parts:
+
+- [Title]
+- [Translations]
+- [Country flag] optional
+- [Checklist]
+
+ [Title]: #title
+ [Translations]: #translations
+ [Country flag]: #country-flag
+ [Checklist]: #checklist
+
+### Title
+
+When you update an already existing language, you can just leave the title as it
+is. Adding support for a new language, replace the `...` in the pre-filled title
+with the name of your language.
+
+| | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Translations
+
+If a translation contains an :arrow_left: icon on the right side, it is missing.
+You can translate this line and remove the :arrow_left: icon. If you don't know
+how to translate specific lines, simply leave them for other contributors to
+complete. To ensure the accuracy of your translation, consider double-checking the
+context of the words by looking at our [English translations].
+
+[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+
+### Country flag optional { #country-flag }
+
+For a better overview, our list of [supported languages] includes country flags
+next to the language names. You can help us select a flag for your language by
+adding the shortcode for the country flag to this field. Go to our
+[emoji search] and enter `flag` to find all available shortcodes.
+
+!!! question "What if my flag is not available?"
+
+ [Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
+ such as states, provinces, or regions, are not supported. If you're adding
+ translations for a subdivision, please choose the most appropriate available
+ flag.
+
+ [Twemoji]: https://twemoji.twitter.com/
+ [emoji search]: ../reference/icons-emojis.md#search
+
+> __Why this might be helpful__: adding a country flag next to the country name
+> can be helpful for you and for others to find the language in the list of
+> supported languages faster and easier. If your country's flag is not supported
+> by [Twemoji], you can help us choose an alternative.
+
+### Checklist
+
+Thanks for following the guide and helping us to add new translations to Material
+for MkDocs – you are almost done. The checklist ensures that you have read this
+guide and have worked to your best knowledge to provide us with everything we need
+to integrate your contribution.
+
+__We'll take it from here.__
+
+---
+
+## Attribution
+
+If you submit a translation using the template above, you will be __credited as
+a co-author__ in the commit, so you don't need to open a pull request. You have
+done a significant contribution to the project, making Material for MkDocs
+accessible to more people around the world. Thank you!
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 130c02745..37cd5b086 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -1,58 +1,202 @@
# Contributing
-Material for MkDocs is an actively maintained and constantly improved project
-that caters to a diverse user base with varying backgrounds and needs. In order
-to effectively address the needs of all our users, evaluate requests, and fix
-bugs, a lot of work from us maintainers is required.
+Material for MkDocs is an actively maintained and constantly evolving project
+serving a diverse user base with versatile backgrounds and needs. In order to
+efficiently address the requirements of all our users, evaluate change requests,
+and fix bugs, we put in a lot of work.
-## How to contribute
-
-We have invested quite a lot of time in creating better templates for our
-[issue tracker], optimizing the processes for our users to report bugs, request
-features or changes, contribute to the project, or exchange with our community.
-This section of the documentation explains each process.
+Our ever-growing community includes many active users, who open new
+issues and discussions several times a day, evolving our [issue tracker] and
+[discussion board] into a knowledge base – an important addition to
+our [documentation] – yielding value to both new and experienced users.
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [documentation]: https://squidfunk.github.io/mkdocs-material/
+
+## How you can contribute
+
+We understand that reporting bugs, raising change requests, as well as engaging
+in discussions can be time-consuming, which is why we've carefully optimized our
+issue templates and defined guidelines to improve the overall interaction
+within the project. We've invested a lot of time and effort into making our
+[issue tracker] and [discussion board] as efficient as possible.
+
+Our goal is to ensure that our documentation, as well as issue tracker and
+discussion board, are __well-structured__, __easy to navigate__, and
+__searchable__, so you can find what you need quickly and efficiently. Thus,
+when you follow our guidelines, we can help you much faster.
+
+In this section, we guide your through our processes.
### Creating an issue
-- :material-bug:{ .lg .middle } __Something is not working?__
+- :material-bug-outline:
+ __Something is not working?__
---
- Report a bug in Material for MkDocs by creating an issue and a reproduction
+ Report a bug in Material for MkDocs by creating an issue with a
+ reproduction
+
+ ---
[:octicons-arrow-right-24: Report a bug][report a bug]
-- :material-file-document:{ .lg .middle } __Missing information in our docs?__
+- :material-file-document-remove-outline:
+ __Missing information in our docs?__
---
- Report missing information or potential inconsistencies in our documentation
+ Report missing information or potential inconsistencies in our
+ documentation
+
+ ---
[:octicons-arrow-right-24: Report a docs issue][report a docs issue]
-- :material-lightbulb-on:{ .lg .middle } __Want to submit an idea?__
+- :material-lightbulb-on-20:
+ __Want to submit an idea?__
---
- Propose a change or feature request or suggest an improvement
+ Propose a change, feature request, or suggest an improvement
+
+ ---
[:octicons-arrow-right-24: Request a change][request a change]
-- :material-chat-question:{ .lg .middle } __Have a question or need help?__
+- :material-account-question-outline:
+ __Have a question or need help?__
---
- Ask questions on our discussion board and get in touch with our community
+ Ask a question on our [discussion board] and get in touch with our
+ community
- [:octicons-arrow-right-24: Ask a question][ask a question]
+ ---
+
+ [:octicons-arrow-right-24: Ask a question][discussion board]
+
+
+
+### Contributing
+
+
+
+- :material-translate:
+ __Missing support for your language?__
+
+ ---
+
+ Add or improve translations for a new or already supported language
+
+ ---
+
+ [:octicons-arrow-right-24: Add a translation][add a translation]
+
+- :material-source-pull:
+ __Want to create a pull request?__
+
+ ---
+
+ Learn how to create a comprehensive and useful pull request (PR)
+
+ ---
+
+ [:octicons-arrow-right-24: Create a pull request][create a pull request]
[report a bug]: reporting-a-bug.md
[report a docs issue]: reporting-a-docs-issue.md
[request a change]: requesting-a-change.md
- [ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
+ [add a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
+ [create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
+
+## Checklist
+
+Before interacting within the project, please take a moment to consider the
+following questions. By doing so, you can ensure that you are using the correct
+issue template and that you provide all necessary information when interacting
+with our community.
+
+!!! warning "Issues, discussions, and comments are forever"
+
+ Please note that everything you write is permanent and will remain
+ for everyone to read – forever. Therefore, please always be nice and
+ constructive, follow our contribution guidelines, and comply with our
+ [Code of Conduct].
+
+### Before creating an issue
+
+- Are you using the appropriate issue template, or is there another issue
+ template that better fits the context of your request?
+
+- Have you checked if a similar bug report or change request has already been
+ created, or have you stumbled upon something that might be related?
+
+- Did your fill out every field as requested and did you provide all additional
+ information we maintainers need to comprehend your request?
+
+### Before asking a question
+
+- Is the topic a question for our [discussion board], or is it a bug report or
+ change request that should better be raised on our [issue tracker]?
+
+- Is there an open discussion on the topic of your request? If the answer is yes,
+ does your question match the direction of the discussion, or should you open a
+ new discussion?
+
+- Did your provide our community with all the necessary information to
+ understand your question and help you quickly, or can you make it easier to
+ help you?
+
+### Before commenting
+
+- Is your comment relevant to the topic of the current page, post, issue, or
+ discussion, or is it a better idea to create a new issue or discussion?
+
+- Does your comment add value to the conversation? Is it constructive and
+ respectful to our community and us maintainers? Could you just use a
+ [:octicons-smiley-16: reaction][reaction] instead?
+
+ [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
+ [reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
+
+## 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].
+
+### 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
+inappropriate, offensive, or harmful behavior.
+
+We take violations seriously and will take appropriate action in response.
diff --git a/docs/contributing/reporting-a-bug.md b/docs/contributing/reporting-a-bug.md
index 5602bd7b7..5d40218b4 100644
--- a/docs/contributing/reporting-a-bug.md
+++ b/docs/contributing/reporting-a-bug.md
@@ -1,9 +1,9 @@
-# Reporting a bug
+# Bug reports
Material for MkDocs is an actively maintained project that we constantly strive
to improve. With a project of this size and complexity, bugs may occur. If you
think you have discovered a bug, you can help us by submitting an issue in our
-public [issue tracker] by following this guide.
+public [issue tracker], following this guide.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
@@ -14,7 +14,7 @@ of this project are trying very hard to keep the number of open issues down by
fixing bugs as fast as possible. By following this guide, you will know exactly
what information we need to help you quickly.
-__But first, please try the following things before creating an issue.__
+__But first, please do the following things before creating an issue.__
### Upgrade to latest version
@@ -37,7 +37,7 @@ We can't offer official support for bugs that might hide in your overrides, so
make sure to omit the following settings from `mkdocs.yml`:
- [`theme.custom_dir`][theme.custom_dir]
- - [`theme.hooks`][theme.hooks]
+ - [`hooks`][hooks]
- [`extra_css`][extra_css]
- [`extra_javascript`][extra_javascript]
@@ -63,10 +63,10 @@ problems.__
[JavaScript]: ../customization.md#additional-javascript
[theme extension]: ../customization.md#extending-the-theme
[theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
- [theme.hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
+ [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/discussions
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/issues
[StackOverflow]: https://stackoverflow.com
[that our documentation explicitly mentions]: ?q="extends+base"
@@ -104,7 +104,7 @@ them in the bug report.__[^2]
[^2]:
We might be using terminology in our documentation different from yours,
- but mean the same. When you include the search terms and related links
+ but we mean the same. When you include the search terms and related links
in your bug report, you help us to adjust and improve the documentation.
---
@@ -119,13 +119,13 @@ how to create a complete and helpful bug report.
## Issue template
We have created a new issue template to make the bug reporting process as simple
-as possible and more efficient for the community and us. It is the result of
+as possible and more efficient for our community and us. It is the result of
our experience answering and fixing more than 1,600 issues (and counting) and
consists of the following parts:
- [Title]
- [Context] optional
-- [Description]
+- [Bug description]
- [Related links]
- [Reproduction]
- [Steps to reproduce]
@@ -134,7 +134,7 @@ consists of the following parts:
[Title]: #title
[Context]: #context
- [Description]: #description
+ [Bug description]: #bug-description
[Related links]: #related-links
[Reproduction]: #reproduction
[Steps to reproduce]: #steps-to-reproduce
@@ -152,12 +152,12 @@ can be inferred from the title.
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
| :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
| :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
-| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Context optional { #context }
Before describing the bug, you can provide additional context for us to
-understand what you are trying to achieve. Explain the circumstances
+understand what you were trying to achieve. Explain the circumstances
in which you're using Material for MkDocs, and what you _think_ might be
relevant. Don't write about the bug here.
@@ -165,7 +165,7 @@ relevant. Don't write about the bug here.
> environments or edge cases, for example, when your documentation contains
> thousands of documents.
-### Description
+### Bug description
Now, to the bug you want to report. Provide a clear, focused, specific, and
concise summary of the bug you encountered. Explain why you think this is a bug
@@ -239,7 +239,7 @@ it allows us maintainers to instantly recreate the necessary conditions to
inspect the bug to quickly find its root cause. It's a proven fact that issues
with concise and small reproductions can be fixed much faster.
-[:material-bug: Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
+[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
---
@@ -256,7 +256,7 @@ will automatically upload it to GitHub.
While we know that it is a good practice among developers to include a link
to a repository with the bug report, we currently don't support those in our
- process. The reason is that the reproduction which is automatically
+ process. The reason is that the reproduction, which is automatically
produced by the [built-in info plugin] contains all of the necessary
environment information that is often forgotten to be included.
@@ -264,16 +264,16 @@ will automatically upload it to GitHub.
have trouble creating repositories.
[Create reproduction]: ../guides/creating-a-reproduction.md
- [built-in info plugin]: ../guides/creating-a-reproduction.md#creating-a-zip-file
+ [built-in info plugin]: ../plugins/info.md
### Steps to reproduce
-At this point, you provided us with enough information to understand the bug,
-and you gave us a reproduction that we could run and inspect. However, when we
-run your reproduction, it might not be immediately apparent how we can see
+At this point, you provided us with enough information to understand the bug
+and provided us with a reproduction that we could run and inspect. However, when
+we run your reproduction, it might not be immediately apparent how we can see
the bug in action.
-Next, please list the specific steps we should follow when running your
+Thus, please list the specific steps we should follow when running your
reproduction to observe the bug. Keep the steps short and concise, and make sure
not to leave anything out. Use simple language as you would explain it to a
five-year-old, and focus on continuity.
@@ -284,11 +284,17 @@ five-year-old, and focus on continuity.
### Browser optional { #browser }
-If you're reporting a bug that only happens in one or more _specific_ browsers,
+If you're reporting a bug that only occurs in one or more _specific_ browsers,
we need to know which browsers are affected. This field is optional, as it is
only relevant when the bug you are reporting does not involve a crash when
[previewing] or [building] your site.
+---
+
+:material-incognito: __Incognito mode__ – Please verify that a the bug is
+not caused by a browser extension. Switch to incognito mode and try to reproduce
+the bug. If it's gone, it's caused by an extension.
+
> __Why we need this__: some bugs only occur in specific browsers or versions.
> Since now, almost all browsers are evergreen, we usually don't need to know the
> version in which it occurs, but we might ask for it later. When in doubt, add
@@ -300,15 +306,8 @@ only relevant when the bug you are reporting does not involve a crash when
### Checklist
Thanks for following the guide and creating a high-quality and complete bug
-report – you are almost done. This section ensures that you have read this guide
-and have worked to the best of your knowledge to provide us with everything we
-need to know to help you.
+report – you are almost done. The checklist ensures that you have read this guide
+and have worked to your best knowledge to provide us with everything we need to
+know to help you.
__We'll take it from here.__
-
-## Incomplete issues
-
-Please understand that we reserve the right to close incomplete issues which
-do not contain minimal reproductions or do not adhere to the quality standards
-and requirements mentioned in this document. Issues can be reopened when the
-missing information has been provided.
diff --git a/docs/contributing/reporting-a-docs-issue.md b/docs/contributing/reporting-a-docs-issue.md
index ac81d67aa..460aadf77 100644
--- a/docs/contributing/reporting-a-docs-issue.md
+++ b/docs/contributing/reporting-a-docs-issue.md
@@ -1,18 +1,18 @@
-# Reporting a docs issue
+# Documentation issues
-In the past seven years, our documentation has grown to more than 60 pages. With
-a site being this large, inconsistencies can occur. If you find an inconsistency
-or see room for clarification or improvement, please submit an issue to
-our public [issue tracker] by following this guide.
+Our documentation is composed of more than 80 pages and includes extensive
+information on features, configurations, customizations, and much more. If you
+have found an inconsistency or see room for improvement, please follow this
+guide to submit an issue on our [issue tracker].
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
## Issue template
Reporting a documentation issue is usually less involved than reporting a bug,
-as we don't need a [reproduction]. Please thoroughly read the following guide
-before creating a new documentation issue, and provide the following information
-as part of the issue:
+as we don't need a [reproduction]. Please thoroughly read this guide before
+creating a new documentation issue, and provide the following information as
+part of the issue:
- [Title]
- [Description]
@@ -31,43 +31,45 @@ as part of the issue:
A good title should be a short, one-sentence description of the issue, contain
all relevant information and, in particular, keywords to simplify the search in
-the issue tracker.
+our issue tracker.
| | Example |
-| -------- | -------- |
+| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
-| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Description
-Provide a clear and concise summary of the inconsistency or issue you
-encountered in the documentation or the documentation section that needs
-improvement. Explain why you think the documentation should be adjusted and
+Provide a clear and concise summary of the inconsistency or issue you
+encountered in the documentation or the documentation section that needs
+improvement. Explain why you think the documentation should be adjusted and
describe the severity of the issue:
-- __Keep it short and concise__ – if the inconsistency or issue can be
- precisely explained in one or two sentences, perfect. Maintainers and
- future users will be grateful for having to read less.
+- __Keep it short and concise__ – if the inconsistency or issue can be
+ precisely explained in one or two sentences, perfect. Maintainers and future
+ users will be grateful for having to read less.
- __One issue at a time__ – if you encounter several unrelated inconsistencies,
- please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
+ please create separate issues for them. Don't report them in the same issue
+ – it makes attribution difficult.
-> __Why we need this__: in order for us to understand the problem, we need a
-> clear description of it and quantify its impact, which is essential for triage
-> and prioritization.
+> __Why we need this__: describing the problem clearly and concisely is a
+> prerequisite for improving our documentation – we need to understand what's
+> wrong, so we can fix it.
### Related links
-After you described the documentation section that needs to be adjusted above,
+After you described the documentation section that needs to be adjusted above,
we now ask you to share the link to this specific documentation section and
-other possibly related sections. Make sure to use anchor links (permanent links)
+other possibly related sections. Make sure to use anchor links (permanent links)
where possible, as it simplifies discovery.
-> __Why we need this__: providing the links to the documentation help us
-> understand which sections of our documentation need to be adjusted, extended,
+> __Why we need this__: providing the links to the documentation help us
+> understand which sections of our documentation need to be adjusted, extended,
> or overhauled.
+
### Proposed change optional { #proposed-change }
Now that you have provided us with the description and links to the
@@ -75,15 +77,15 @@ documentation sections, you can help us, maintainers, and the community by
proposing an improvement. You can sketch out rough ideas or write a concrete
proposal. This field is optional but very helpful.
-> __Why we need this__: improvement proposal can be beneficial for other users
-> who encounter the same issue, as they offer solutions before we maintainers
-> can update the documentation.
+> __Why we need this__: an improvement proposal can be beneficial for other
+> users who encounter the same issue, as they offer solutions before we
+> maintainers can update the documentation.
### Checklist
-Thanks for following the guide and creating a high-quality and complete issue
-report – you are almost done. This section ensures that you have read this guide
-and have worked to the best of your knowledge to provide us with every piece of
-information we need to improve our documentation.
+Thanks for following the guide and providing valuable feedback for our
+documentation – you are almost done. The checklist ensures that you have read
+this guide and have worked to your best knowledge to provide us with every piece
+of information we need to improve it.
__We'll take it from here.__
diff --git a/docs/contributing/requesting-a-change.md b/docs/contributing/requesting-a-change.md
index 25b7e55f0..a708ae50d 100644
--- a/docs/contributing/requesting-a-change.md
+++ b/docs/contributing/requesting-a-change.md
@@ -1,22 +1,22 @@
-# Requesting a change
+# Change requests
Material for MkDocs is a powerful tool for creating beautiful and functional
-project documentation. With more than 20,000 users, we understand that our
-project serves a wide range of use cases, which is why we have created the
-following guide.
+documentation. With more than 20,000 users, we understand that our project
+serves a wide range of use cases, which is why we have created the following
+guide.
---
Put yourself in our shoes – with a project of this size, it can be challenging
to maintain existing functionality while constantly adding new features at the
same time. We highly value every idea or contribution from our community, and
-we kindly ask you to take the time to read the following guidelines before
-submitting your change request in our public [issue tracker]. This will help us
-better understand the proposed change and how it will benefit the community.
+we kindly ask you to take the time to read the following guidelines before
+submitting your change request in our public [issue tracker]. This will help us
+better understand the proposed change and how it will benefit our community.
This guide is our best effort to explain the criteria and reasoning behind our
decisions when evaluating change requests and considering them for
-implementation.
+implementation.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
@@ -27,45 +27,52 @@ ask you to do some preliminary work by answering some questions to determine if
your idea is a good fit for Material for MkDocs and matches the project's
[philosophy] and tone.
-__Please find answers to the following questions before creating an issue.__
+__Please do the following things before creating an issue.__
[philosophy]: ../philosophy.md
### It's not a bug, it's a feature
Change requests are intended to suggest minor adjustments, ideas for new
-features, or to influence the project's direction and vision. It is important
-to note that change requests are not intended for reporting bugs, as they're
-missing essential information for debugging.
+features, or to kindly influence the project's direction and vision. It is
+important to note that change requests are not intended for reporting bugs, as
+they're missing essential information for debugging.
If you want to report a bug, please refer to our [bug reporting guide] instead.
[bug reporting guide]: reporting-a-bug.md
-### Source of inspiration
+### Look for sources of inspiration
If you have seen your idea implemented in another static site generator or
theme, make sure to collect enough information on its implementation before
submitting, as this allows us to evaluate potential fit more quickly. Explain
what you like and dislike about the implementation.
-### Benefit for the community
+### Connect with our community
-Our [discussion board] is the best place to connect with our community. When
-evaluating new ideas, it's essential to seek input from other users and consider
+Our [discussion board] is the best place to connect with our community. When
+evaluating new ideas, it's essential to seek input from other users and consider
alternative viewpoints. This approach helps to implement new features in a way
that benefits a large number of users.
-[:octicons-comment-discussion-16: Start a discussion][Start a discussion]{ .md-button .md-button--primary }
+__Keep track of all search terms and relevant links, you'll need
+them in the change request.__[^1]
+
+ [^1]:
+ We might be using terminology in our documentation different from yours,
+ but we mean the same. When you include the search terms and related links
+ in your change request, you help us to adjust and improve the documentation.
+
+[:octicons-comment-discussion-16: Start a discussion][discussion board]{ .md-button .md-button--primary }
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
- [Start a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
## Issue template
-Now that you have taken the time to do the necessary preliminary work and ensure
+Now that you have taken the time to do the necessary preliminary work and ensure
that your idea meets our requirements, you are invited to create a change
-request. The following guide will walk you through all the necessary steps to
+request. The following guide will walk you through all the necessary steps to
help you submit a comprehensive and useful issue:
- [Title]
@@ -87,15 +94,15 @@ help you submit a comprehensive and useful issue:
### Title
A good title is short and descriptive. It should be a one-sentence executive
-summary of the idea, so the potential impact and benefit for the community can
+summary of the idea, so the potential impact and benefit for our community can
be inferred from the title.
| | Example |
-| -------- | -------- |
+| -------- | -------- |
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
-| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
### Context optional { #context }
@@ -111,13 +118,13 @@ relevant. Don't write about the change request here.
### Description
-Next, provide a detailed and clear description of your idea. Explain why your
-idea is relevant to Material for MkDocs and must be implemented here, and not
-in one of its dependencies:[^1]
+Next, provide a detailed and clear description of your idea. Explain why your
+idea is relevant to Material for MkDocs and must be implemented here and not
+in one of its dependencies:[^2]
- [^1]:
+ [^2]:
Sometimes, users suggest ideas on our [issue tracker] that concern one of
- our upstream dependencies, including [MkDocs], [Python Markdown],
+ our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
[Python Markdown Extensions] or third-party plugins. It's a good idea to
think about whether your idea is beneficial to other themes, upstreaming
change requests for a bigger impact.
@@ -126,12 +133,12 @@ in one of its dependencies:[^1]
[the benefits of your idea][Use cases] here, we're getting there.
Focus on describing the proposed change request as precisely as possible.
-- __Keep it short and concise__ – be brief and to the point when describing
+- __Keep it short and concise__ – be brief and to the point when describing
your idea, there is no need to over-describe it. Maintainers and future
users will be grateful for having to read less.
-- __One idea at a time__ – if you have multiple ideas that don't belong
-together, please open separate change requests for each of those ideas.
+- __One idea at a time__ – if you have multiple ideas that don't belong
+ together, please open separate change requests for each of those ideas.
---
@@ -140,65 +147,95 @@ way to add the proposed change, you can help other users by sharing it here
before we maintainers can add it to our code base.
> __Why we need this__: To understand and evaluate your proposed change, we
-> need to have a clear understanding of your idea. By providing a detailed and
+> need to have a clear understanding of your idea. By providing a detailed and
> precise description, you can help save you and us time spent discussing
> further clarification of your idea in the comments.
- [MkDocs]: https://www.mkdocs.org
[Python Markdown]: https://python-markdown.github.io/extensions/
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
- [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
### Related links
-Please provide any relevant links to issues, discussions, or documentation
+Please provide any relevant links to issues, discussions, or documentation
sections related to your change request. If you (or someone else) already
-discussed this idea with the community on our discussion board, please include
+discussed this idea with our community on our discussion board, please include
the link to the discussion as well.
> __Why we need this__: Related links help us gain a comprehensive
> understanding of your change request by providing additional context.
> Additionally, linking to previous issues and discussions allows us
-> to quickly evaluate the feedback and input already provided by the community.
+> to quickly evaluate the feedback and input already provided by our community.
### Use cases
Explain how your change request would work from an author's and user's
-perspective – what's the expected impact, and why does it benefit not only you
+perspective – what's the expected impact, and why does it not only benefit you,
but other users? How many of them? Furthermore, would it potentially break
existing functionality?
-> __Why we need this__: Understanding the use cases and benefits of an idea is
-> crucial in evaluating its potential impact and usefulness for the project and
-> its users. This information helps us to understand the expected value of the
+> __Why we need this__: Understanding the use cases and benefits of an idea is
+> crucial in evaluating its potential impact and usefulness for the project and
+> its users. This information helps us to understand the expected value of the
> idea and how it aligns with the goals of the project.
### Visuals optional { #visuals }
-We now have a clear and detailed description of your idea, including information
-on its potential use cases and relevant links for context. If you have any
-visuals, such as sketches, screenshots, mockups, or external assets, you may
+We now have a clear and detailed description of your idea, including information
+on its potential use cases and relevant links for context. If you have any
+visuals, such as sketches, screenshots, mockups, or external assets, you may
present them in this section.
__You can drag and drop the files here or include links to external assets.__
-Additionally, if you have seen this change, feature, or improvement used in
-other static site generators or themes, please provide an example by showcasing
+Additionally, if you have seen this change, feature, or improvement used in
+other static site generators or themes, please provide an example by showcasing
it and describing how it was implemented and incorporated.
-> __Why we need this__: Illustrations and visuals can help us maintainers
-> better understand and envision your idea. Screenshots, sketches, or mockups
-> can create an additional level of detail and clarity that text alone may not
-> be able to convey. Also, seeing how your idea has been implemented in other
-> projects can help us understand its potential impact and feasibility in
-> Material for MkDocs, which helps us maintainers evaluate and triage
-> change requests.
+> __Why this might be helpful__: Illustrations and visuals can help us
+> maintainers better understand and envision your idea. Screenshots, sketches,
+> or mockups can create an additional level of detail and clarity that text
+> alone may not be able to convey. Also, seeing how your idea has been
+> implemented in other projects can help us understand its potential impact and
+> feasibility in Material for MkDocs, which helps us maintainers evaluate and
+> triage change requests.
### Checklist
-Thanks for following the change request guide and creating a high-quality
-change request. This section ensures that you have read this guide and have
-worked to the best of your knowledge to provide us with every piece of
-information to review your idea for Material for MkDocs.
+Thanks for following the guide and creating a high-quality change request – you
+are almost done. The checklist ensures that you have read this guide and have
+worked to your best knowledge to provide us with every piece of information to
+review your idea for Material for MkDocs.
__We'll take it from here.__
+
+---
+
+## Rejected requests
+
+__Your change request got rejected? We're sorry for that.__ We understand it can
+be frustrating when your ideas don't get accepted, but as the maintainers of a
+very popular project, we always need to consider the needs of our entire
+community, sometimes forcing us to make tough decisions.
+
+We always have to consider and balance many factors when evaluating change
+requests, and we explain the reasoning behind our decisions whenever we can.
+If you're unsure why your change request was rejected, please don't hesitate
+to ask for clarification.
+
+The following principles (in no particular order) form the basis for our
+decisions:
+
+- [ ] Alignment with vision and tone of the project
+- [ ] Compatibility with existing features and plugins
+- [ ] Compatibility with all screen sizes and browsers
+- [ ] Effort of implementation and maintenance
+- [ ] Usefulness to the majority of users
+- [ ] Simplicity and ease of use
+- [ ] Accessibility
+
+But that's not the end of your idea – you can always implement it on your own
+via [customization]. If you're unsure about how to do that or want to know if
+someone has already done it, feel free to get in touch with our community on
+the [discussion board].
+
+ [customization]: ../customization.md
diff --git a/docs/schema/plugins.json b/docs/schema/plugins.json
index e8e16dbeb..c25767d58 100644
--- a/docs/schema/plugins.json
+++ b/docs/schema/plugins.json
@@ -93,7 +93,7 @@
]
},
"external-community": {
- "description": "External plugins, schema provided by the community",
+ "description": "External plugins, schema provided by our community",
"anyOf": [
{
"$ref": "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/schema.json"
diff --git a/docs/setup/changing-the-language.md b/docs/setup/changing-the-language.md
index 6465b55b3..d23a86611 100644
--- a/docs/setup/changing-the-language.md
+++ b/docs/setup/changing-the-language.md
@@ -37,9 +37,9 @@ the default slug function works. Consider using a [Unicode-aware slug function].
!!! tip "Translations missing? Help us out, it takes only 5 minutes"
Material for MkDocs relies on outside contributions for adding and updating
- translations for the almost 60 languages it supports. If your language shows
- that some translations are missing, click on the link to add them. If your
- language is not in the list, click here to [add a new language].
+ translations for the more than 60 languages it supports. If your language
+ shows that some translations are missing, click on the link to add them. If
+ your language is not in the list, click here to [add a new language].
[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
[language selector]: #site-language-selector
diff --git a/material/extensions/emoji.py b/material/extensions/emoji.py
index aa2e5b778..b0ed3cab8 100644
--- a/material/extensions/emoji.py
+++ b/material/extensions/emoji.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2023 Martin Donath