Merge pull request #5320 from squidfunk/docs/guides

Updated guides

.github/ISSUE_TEMPLATE/03-request-a-change.yml

@@ -51,7 +51,7 @@ body:
       description: >-
         Please explain how your idea will work from an author's and user's
         perspective. Elaborate on how the change would positively impact not only
-        you but the community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
+        you but our community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
         of the project.
         [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#use-cases)
     validations:

.github/ISSUE_TEMPLATE/04-add-translations.yml

@@ -7,17 +7,21 @@ body:
 
   - type: markdown
     attributes:
-      value: >-
+      value: |-
-        **Important**: Before creating a new translation, please make sure that
+        **Important**: Before creating a new translation, please check if
-        Material for MkDocs does not already include support for your language.
+        Material for MkDocs already supports your language. Review the list of
-        Please check the list of all [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language)
+        [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language),
-        and help us by adding missing translations.
+        pick your language to add new or improve existing translations.
 
   - type: textarea
     id: translations
     attributes:
       label: Translations
-      description: Please translate the labels on the right, e.g., "Copy to clipboard", etc.
+      description: >-
+        Please translate the labels on the right. For new languages, translate
+        each line. For existing languages, only translate lines containing the
+        icon :arrow_left: and remove the icon before submitting.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-a-translation/#translations)
       value: |-
         {% macro t(key) %}{{ {
           "language": "en",
@@ -76,13 +80,25 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    id: country-flag
+    attributes:
+      label: Country flag icon
+      description: >-
+        Please add the flag of the country when adding a new language. Select
+        it on our [Icons, Emojis site](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
+        by entering `flag` in the search field. If your flag is not provided by
+        Twemoji, please choose the closest matching flag.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-a-translation/#country-flag)
+      placeholder: |-
+        Post the flag of the country here.
+
   - type: checkboxes
     id: checklist
     attributes:
       label: Before submitting
       description: >-
-        Please ensure that your translation fulfills the following
+        Please ensure that your translation fulfills the following requirements.
-        requirements.
       options:
         - label: I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
           required: true
@@ -91,4 +107,3 @@ body:
         - label: >-
             __Optional__: I want to integrate this translation myself and create a
             pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).
-

.github/ISSUE_TEMPLATE/config.yml

@@ -22,4 +22,6 @@ blank_issues_enabled: false
 contact_links:
   - name: Ask a question
     url: https://github.com/squidfunk/mkdocs-material/discussions
-    about: Have a question or need help? Connect with the community on our discussion board
+    about: >
+      Have a question or need help? Connect with our community on the
+      discussion board

CODE_OF_CONDUCT.md

@@ -16,7 +16,7 @@ Examples of behavior that contributes to creating a positive environment include
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
 * Gracefully accepting constructive criticism
-* Focusing on what is best for the community
+* Focusing on what is best for our community
 * Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
@@ -54,12 +54,12 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at
+reported by contacting the project team privately at hello@squidfunk.com. The
-https://gitter.im/squidfunk/mkdocs-material. The project team will review and 
+project team will review and investigate all complaints, and will respond in a
-investigate all complaints, and will respond in a way that it deems appropriate
+way that it deems appropriate to the circumstances. The project team is
-to the circumstances. The project team is obligated to maintain confidentiality
+obligated to maintain confidentiality with regard to the reporter of an
-with regard to the reporter of an incident. Further details of specific
+incident. Further details of specific enforcement policies may be posted
-enforcement policies may be posted separately.
+separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other

CONTRIBUTING.md

@@ -1,112 +1,61 @@
 # Contributing
 
-Interested in contributing to the Material for MkDocs? Have a question? Want to 
+Material for MkDocs is an actively maintained and constantly improved project
-report a bug? Before you do, please read the following guidelines.
+that serves a diverse user base with varying backgrounds and needs. In order to
+effectively address the needs of all our users, evaluate change requests, and
+fix bugs, we maintainers need to put in a lot of work. We have devoted
+significant effort to 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.
 
-## Submission context
+Given the wealth of valuable knowledge contained in numerous issues and
-
+discussions, we consider our [issue tracker] and [discussion board] to serve as
-### Got a question or problem?
+a crucial __knowledge base__ that is an important addition to our [documentation]
-
+and brings value to both new and experienced users of Material for MkDocs.
-For quick questions there's no need to open an issue as you can reach us on
-[gitter.im].
-
-  [gitter.im]: https://gitter.im/squidfunk/mkdocs-material
-
-### Found a bug?
-
-If you found a bug in the source code, you can help us by submitting an issue
-to the [issue tracker] in our GitHub repository. Even better, you can submit
-a Pull Request with a fix. However, before doing so, please read the
-[submission guidelines].
 
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
-  [submission guidelines]: #submission-guidelines
+  [documentation]: https://squidfunk.github.io/mkdocs-material/
 
-### Missing a feature?
+## How to contribute
 
-You can request a new feature by submitting an issue to our GitHub Repository.
+### Creating an issue
-If you would like to implement a new feature, please submit an issue with a
-proposal for your work first to be sure that it is of use to everyone, as
-Material for MkDocs is highly opinionated. Please consider what kind of change
-it is:
 
-* For a **major feature**, first open an issue and outline your proposal so
+-   #### [Report a bug]
-  that it can be discussed. This will also allow us to better coordinate our
-  efforts, prevent duplication of work, and help you to craft the change so
-  that it is successfully accepted into the project.
 
-* **Small features and bugs** can be crafted and directly submitted as a Pull
+    __Something is not working?__ Report a bug in Material for MkDocs by
-  Request. However, there is no guarantee that your feature will make it into
+    creating an issue with a reproduction
-  the `master`, as it's always a matter of opinion whether if benefits the
-  overall functionality of the project.
 
-### Missing translations?
+-   #### [Report a docs issue]
 
-Material for MkDocs supports 60+ languages with the help of community
+    __Missing information in our docs?__ Report missing information or
-contributions. When new features are added, sometimes, new translations are
+    potential inconsistencies in our documentation
-necessary as well. It's impossible for the maintainers of the project to update
-all translations (we just don't speak 60+ languages), so we have to rely on
-our contributors to update translations incrementally. This process is pretty
-simple, so if you find a translation missing in your language, follow these
-guidelines:
 
-1.  Fork the repository.
+-   #### [Request a change]
 
-2.  Open up the [translation file for your language] as well as the
+    __Want to submit an idea?__ Propose a change, feature request, or
-    [English translations], as they are always up-to-date. Compare them
+    suggest an improvement
-    side-by-side and add the missing translations. __Important__: only add the
-    translations that are different from the defaults, e.g. if your language
-    is left-to-right, don't add the `direction` translation, as English is
-    left-to-right as well. The following translations are for technical
-    purposes and should not be updated, so if they're missing from your
-    language, it's for good reason:
 
-    - `search.config.lang`
+-   #### [Ask a question]
-    - `search.config.pipeline`
-    - `search.config.separator`
 
-3.  Create a PR (see below) with your changes.
+    __Have a question or need help?__ Ask a question on our [discussion board]
+    and get in touch with our community
 
-  [translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
+### Contributing
-  [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
 
-## Submission guidelines
+-   #### [Add a translation]
 
-### Submitting an issue
+    __Missing support for your language?__ Add missing translations for a new
+    or already supported language
 
-Before you submit an issue, please search the issue tracker, maybe an issue for
+-   #### [Create a pull request]
-your problem already exists, and the discussion might inform you of workarounds
-readily available.
 
-We want to fix all the issues as soon as possible, but before fixing a bug, we
+    __Want to create a pull request?__ Learn how to create a comprehensive
-need to reproduce and confirm it. In order to reproduce bugs, we will
+    and useful pull request (PR)s
-systematically ask you to provide a minimal reproduction scenario using the
-custom issue template. Please stick to the issue template.
 
-Unfortunately, we are not able to investigate / fix bugs without a minimal
+  [Report a bug]: reporting-a-bug.md
-reproduction scenario, so if we don't hear back from you, we may close the issue.
+  [Report a docs issue]: reporting-a-docs-issue.md
-
+  [Request a change]: requesting-a-change.md
-### Submitting a Pull Request (PR)
+  [Ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
-
+  [Add a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
-Search GitHub for an open or closed PR that relates to your submission. You
+  [Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
-don't want to duplicate effort. If you do not find a related issue or PR,
-go ahead.
-
-1.  **Development**: Fork the project, set up the [development environment],
-    make your changes in a separate git branch and add descriptive messages to
-    your commits.
-
-2.  **Build**: Before submitting a pull request, [build the theme]. This is
-    a mandatory requirement for your PR to get accepted, as the theme should be 
-    installable through GitHub at all times.
-
-3.  **Pull Request**: After building the theme, commit the compiled output,
-    push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
-    suggest changes, make the required updates, rebase your branch and push the
-    changes to your GitHub repository, which will automatically update your PR.
-
-After your PR is merged, you can safely delete your branch and pull the changes
-from the main (upstream) repository.
-
-  [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
-  [build the theme]: https://squidfunk.github.io/mkdocs-material/customization/#building-the-theme

README.md

@@ -20,10 +20,6 @@
     src="https://img.shields.io/pypi/dm/mkdocs-material.svg"
     alt="Downloads"
   /></a>
-  <a href="https://gitter.im/squidfunk/mkdocs-material"><img 
-    src="https://badges.gitter.im/squidfunk/mkdocs-material.svg" 
-    alt="Chat on Gitter"
-  /></a>
   <a href="https://pypi.org/project/mkdocs-material"><img
     src="https://img.shields.io/pypi/v/mkdocs-material.svg"
     alt="Python Package Index"

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] <small>optional</small>
+- [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 <small>optional</small> { #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!

docs/contributing/index.md

@@ -1,58 +1,202 @@
 # Contributing
 
-Material for MkDocs is an actively maintained and constantly improved project 
+Material for MkDocs is an actively maintained and constantly evolving project
-that caters to a diverse user base with varying backgrounds and needs. In order
+serving a diverse user base with versatile backgrounds and needs. In order to
-to effectively address the needs of all our users, evaluate requests, and fix 
+efficiently address the requirements of all our users, evaluate change requests,
-bugs, a lot of work from us maintainers is required.
+and fix bugs, we put in a lot of work.
 
-## How to contribute
+Our ever-growing community includes many active users, who open new
-
+issues and discussions several times a day, evolving our [issue tracker] and
-We have invested quite a lot of time in creating better templates for our
+[discussion board] into a knowledge base – an important addition to
-[issue tracker], optimizing the processes for our users to report bugs, request
+our [documentation] – yielding value to both new and experienced users.
-features or changes, contribute to the project, or exchange with our community. 
-This section of the documentation explains each process.
 
+  [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
 
 <div class="grid cards" markdown>
 
--   :material-bug:{ .lg .middle } __Something is not working?__
+-   :material-bug-outline: &nbsp;
+    __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: &nbsp;
+    __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: &nbsp;
+    __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: &nbsp;
+    __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]
+
+</div>
+
+### Contributing
+
+<div class="grid cards" markdown>
+
+-   :material-translate: &nbsp;
+    __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: &nbsp;
+    __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]
 
 </div>
 
   [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.

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] <small>optional</small>
-- [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 <small>optional</small> { #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:&nbsp; 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,
+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
+and provided us with a reproduction that we could run and inspect. However, when
-run your reproduction, it might not be immediately apparent how we can see
+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 <small>optional</small> { #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
+report – you are almost done. The checklist ensures that you have read this guide
-and have worked to the best of your knowledge to provide us with everything we
+and have worked to your best knowledge to provide us with everything we need to
-need to know to help you.
+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.

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
+Our documentation is composed of more than 80 pages and includes extensive
-a site being this large, inconsistencies can occur. If you find an inconsistency
+information on features, configurations, customizations, and much more. If you
-or see room for clarification or improvement, please submit an issue to
+have found an inconsistency or see room for improvement, please follow this
-our public [issue tracker] by following this guide.
+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
+as we don't need a [reproduction]. Please thoroughly read this guide before
-before creating a new documentation issue, and provide the following information
+creating a new documentation issue, and provide the following information as
-as part of the issue:
+part of the issue:
 
 - [Title]
 - [Description]
@@ -31,13 +31,13 @@ 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
 
@@ -47,15 +47,16 @@ 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
+    precisely explained in one or two sentences, perfect. Maintainers and future
-    future users will be grateful for having to read less.
+    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
+> __Why we need this__: describing the problem clearly and concisely is a
-> clear description of it and quantify its impact, which is essential for triage
+> prerequisite for improving our documentation – we need to understand what's
-> and prioritization.
+> wrong, so we can fix it.
 
 ### Related links
 
@@ -68,6 +69,7 @@ where possible, as it simplifies discovery.
 > understand which sections of our documentation need to be adjusted, extended,
 > or overhauled.
 
+
 ### Proposed change <small>optional</small> { #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 
+> __Why we need this__: an improvement proposal can be beneficial for other
-> who encounter the same issue, as they offer solutions before we maintainers
+> users who encounter the same issue, as they offer solutions before we
-> can update the documentation.
+> maintainers can update the documentation.
 
 ### Checklist
 
-Thanks for following the guide and creating a high-quality and complete issue 
+Thanks for following the guide and providing valuable feedback for our
-report – you are almost done. This section ensures that you have read this guide
+documentation – you are almost done. The checklist ensures that you have read
-and have worked to the best of your knowledge to provide us with every piece of
+this guide and have worked to your best knowledge to provide us with every piece
-information we need to improve our documentation.
+of information we need to improve it.
 
 __We'll take it from here.__

docs/contributing/requesting-a-change.md

@@ -1,9 +1,9 @@
-# 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
+documentation. With more than 20,000 users, we understand that our project
-project serves a wide range of use cases, which is why we have created the
+serves a wide range of use cases, which is why we have created the following
-following guide.
+guide.
 
 ---
 
@@ -12,7 +12,7 @@ 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.
+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
@@ -27,39 +27,46 @@ 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
+features, or to kindly influence the project's direction and vision. It is
-to note that change requests are not intended for reporting bugs, as they're
+important to note that change requests are not intended for reporting bugs, as
-missing essential information for debugging.
+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
 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 <u>search terms</u> and <u>relevant links</u>, 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:&nbsp; 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
 
@@ -87,7 +94,7 @@ 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  |
@@ -95,7 +102,7 @@ be inferred from the title.
 | :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 <small>optional</small> { #context }
 
@@ -112,12 +119,12 @@ 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
+idea is relevant to Material for MkDocs and must be implemented here and not
-in one of its dependencies:[^1]
+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.
@@ -131,7 +138,7 @@ in one of its dependencies:[^1]
     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.
+    together, please open separate change requests for each of those ideas.
 
 ---
 
@@ -144,27 +151,25 @@ before we maintainers can add it to our code base.
 > 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
 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?
 
@@ -186,19 +191,51 @@ 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 
+> __Why this might be helpful__: Illustrations and visuals can help us
-> better understand and envision your idea. Screenshots, sketches, or mockups 
+> maintainers better understand and envision your idea. Screenshots, sketches,
-> can create an additional level of detail and clarity that text alone may not 
+> or mockups can create an additional level of detail and clarity that text
-> be able to convey. Also, seeing how your idea has been implemented in other 
+> alone may not be able to convey. Also, seeing how your idea has been
-> projects can help us understand its potential impact and feasibility in 
+> implemented in other projects can help us understand its potential impact and
-> Material for MkDocs, which helps us maintainers evaluate and triage 
+> feasibility in Material for MkDocs, which helps us maintainers evaluate and
-> change requests.
+> triage change requests.
 
 ### Checklist
 
-Thanks for following the change request guide and creating a high-quality 
+Thanks for following the guide and creating a high-quality change request – you
-change request. This section ensures that you have read this guide and have
+are almost done. The checklist ensures that you have read this guide and have
-worked to the best of your knowledge to provide us with every piece of 
+worked to your best knowledge to provide us with every piece of information to
-information to review your idea for Material for MkDocs.
+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

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"

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
+    translations for the more than 60 languages it supports. If your language
-    that some translations are missing, click on the link to add them. If your
+    shows that some translations are missing, click on the link to add them. If
-    language is not in the list, click here to [add a new language].
+    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

material/extensions/emoji.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

mkdocs.yml

@@ -95,7 +95,7 @@ hooks:
   - material/overrides/hooks/shortcodes.py
   - material/overrides/hooks/translations.py
 
-# Customization
+# Additional configuration
 extra:
   annotate:
     json: [.s2]
@@ -105,8 +105,6 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/squidfunk
-    - icon: fontawesome/brands/gitter
-      link: https://gitter.im/squidfunk/mkdocs-material
     - icon: fontawesome/brands/docker
       link: https://hub.docker.com/r/squidfunk/mkdocs-material/
     - icon: fontawesome/brands/python
@@ -188,6 +186,7 @@ nav:
       - Reporting a bug: contributing/reporting-a-bug.md
       - Reporting a docs issue: contributing/reporting-a-docs-issue.md
       - Requesting a change: contributing/requesting-a-change.md
+      - Adding translations: contributing/adding-translations.md
       - Asking a question: https://github.com/squidfunk/mkdocs-material/discussions
     - Guides:
       - Creating a reproduction: guides/creating-a-reproduction.md

src/extensions/emoji.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to