diff --git a/.github/ISSUE_TEMPLATE/04-add-a-translation.yml b/.github/ISSUE_TEMPLATE/04-add-a-translation.yml
index a49acf395..e7322b93c 100644
--- a/.github/ISSUE_TEMPLATE/04-add-a-translation.yml
+++ b/.github/ISSUE_TEMPLATE/04-add-a-translation.yml
@@ -7,17 +7,21 @@ body:
- type: markdown
attributes:
- value: >-
- **Important**: Before creating a new translation, please make sure that
- Material for MkDocs does not already include support for your language.
- Please check the list of all [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language)
- and help us by adding missing translations.
+ value: |-
+ **Important**: Before creating a new translation, please check if
+ Material for MkDocs already supports your language. Review the list of
+ [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language),
+ 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",
@@ -63,19 +67,30 @@ 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
- requirements.
+ Please ensure that your translation fulfills the following 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
- - label: I assure that the translations are accurate to my best knowledge.
+ - label: I have assured that, to the best of my knowledge, the translations are accurate.
required: true
- 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).
-
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9bcb6bcef..dbf07b96e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,112 +1,59 @@
# Contributing
-Interested in contributing to the Material for MkDocs? Have a question? Want to
-report a bug? Before you do, please read the following guidelines.
+Material for MkDocs is an actively maintained and constantly improved project
+that serves a diverse user base with varying backgrounds and needs. In order to
+effectively address the needs of all our users, evaluatgit e 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 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.
-### Got a question or problem?
+## How to contribute
-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].
+Selecting the appropriate contribution template is essential to maintain the
+organization, searchability, and ease of use of this knowledge base. In this
+section of our documentation, we outline the available options and their
+respective procedures.
+ [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?
+### Creating an issue
-You can request a new feature by submitting an issue to our GitHub Repository.
-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:
+- #### [Report a bug][report a bug]
-* For a **major feature**, first open an issue and outline your proposal so
- 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.
+ __Something is not working?__ Report a bug in Material for MkDocs by creating an issue with a reproduction
-* **Small features and bugs** can be crafted and directly submitted as a Pull
- Request. However, there is no guarantee that your feature will make it into
- the `master`, as it's always a matter of opinion whether if benefits the
- overall functionality of the project.
+- #### [Report a docs issue][report a docs issue]
-### Missing translations?
+ __Missing information in our docs?__ Report missing information or potential inconsistencies in our documentation
-Material for MkDocs supports 50+ languages with the help of community
-contributions. When new features are added, sometimes, new translations are
-necessary as well. It's impossible for the maintainers of the project to update
-all translations (we just don't speak 50+ 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:
+- #### [Request a change][request a change]
-1. Fork the repository.
+ __Want to submit an idea?__ Propose a change or feature request or suggest an improvement
-2. Open up the [translation file for your language] as well as the
- [English translations], as they are always up-to-date. Compare them
- 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:
+- #### [Ask a question][ask a question]
- - `search.config.lang`
- - `search.config.pipeline`
- - `search.config.separator`
+ __Have a question or need help?__ Ask a question on our discussion board and get in touch with our community
-3. Create a PR (see below) with your changes.
+### Contributing to this project
- [translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
- [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+- #### [Add a translation](https://github.com/squidfunk/mkdocs-material/adding-a-translation)
+
+ __Missing support for your language?__ Add missing translations for a new or supported language
-## Submission guidelines
+- #### [Create a pull request](https://github.com/squidfunk/mkdocs-material/creating-a-pull-request)
+
+ __Want to create a pull request?__ Learn how to create a comprehensive pull request (PR)
-### Submitting an issue
-
-Before you submit an issue, please search the issue tracker, maybe an issue for
-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
-need to reproduce and confirm it. In order to reproduce bugs, we will
-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
-reproduction scenario, so if we don't hear back from you, we may close the issue.
-
-### Submitting a Pull Request (PR)
-
-Search GitHub for an open or closed PR that relates to your submission. You
-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
+ [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
diff --git a/docs/contributing/adding-a-translation.md b/docs/contributing/adding-a-translation.md
new file mode 100644
index 000000000..b3741e0fd
--- /dev/null
+++ b/docs/contributing/adding-a-translation.md
@@ -0,0 +1,236 @@
+# Adding a translation
+
+We can't believe it ourselves but with the help of community contribution,
+Material for MkDocs already supports 50+ languages. As you can imagine, it's
+impossible for us maintainers to keep all languages up-to-date (we just don't
+speak 50+ languages). That's why we need the help of our international community
+to help us add new or update translations, as new feature releases sometimes
+require new translations.
+
+If you would like to help us to make Material for MkDocs more globally
+accessible and have noticed a missing translation in your language or want to
+add a new one. In that case, we have simplified the contributing process for you.
+Just follow the few steps of the guide below.
+
+## Before adding a translation
+
+Given the constant expansion of our project and the frequent translation updates,
+it is essential to check the following things before submitting a translation
+contribution.
+
+### List of supported languages
+
+Chances are your language is already supported by Material for MkDocs. To check
+if your language is supported or needs improvements and updates, we would advise
+you to check the [list of supported languages].
+
+[:material-earth-plus: Search for your language][Search for your language]{ .md-button .md-button--primary }
+
+ [list of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
+ [Search for your language]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
+
+In case your language is already supported, you can add **missing translations**,
+displayed below each language. If your language is not on the list of supported
+languages, you can contribute translations by opening a new issue and
+[adding a translation] by following the guide below.
+
+> __Please note,__ that we use region designators in conjunction with regions,
+> and cluster all languages using language designators with regions. Language
+> region designators consist of codes that represent countries and follow the
+> [ISO 3166-1 standard], which employs two-letter capitalized codes. If you need
+> to specify a particular dialect, please utilize this system by hyphenating a
+> language designator with a region designator. For instance, to specify the
+> British English, use the "en" language designator and indicate the locale as
+> "en-GB."
+
+ [Adding a translation]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
+ [ISO 3166-1 standard]: https://lingohub.com/developers/supported-locales/language-designators-with-regions
+
+### Issue tracker
+
+Our issue tracker might already contain an open issue with a contribution with
+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.
+
+[:octicons-issue-opened-24: Search our issue tracker][Search our issue tracker]{ .md-button .md-button--primary }
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [search our issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+### Update supported languages
+
+Have you noticed that other users haven't yet updated your language? You are
+welcome to contribute and add any missing translations by clicking the link
+provided underneath each language in the [list of supported languages]. This
+link will direct you to a new issue template that is pre-filled with all the
+necessary information. Any fields that can be adjusted will be highlighted for
+your convenience.
+
+[:material-translate-variant: Add missing translations][Update your translations]{ .md-button .md-button--primary }
+
+ [List of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
+ [Update your translations]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
+
+---
+
+At this point, when you have made sure that Material for MkDocs doesn't already
+support your language you can add translations for it by following the issue
+template.
+
+## Issue template
+
+We have created a new issue template to make contributing translations for new
+languages as simple as possible. It is the result of our experience with 50+
+language contributions and updates over the last couple of years. We recently
+simplified the language contribution process, and the new template consists of the
+following parts:
+
+- [Title]
+- [Translations]
+- [Country flag] optional
+- [Checklist]
+
+ [Title]: #title
+ [Translations]: #translations
+ [Country flag]: #country-flag
+ [Checklist]: #checklist
+
+### Title
+
+Translation issue titles are simple. When adding a new language, the first part
+of the title with "Add translations for..." is already pre-filled in the
+template, and you need to replace the three dots with your language name. If
+adding missing translations for a language from the [list of supported languages],
+the title is already set with no need for adjustment.
+
+| | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
+| :material-close:{ style="color: #EF5350" } __Generic__ | German
+
+ [List of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
+
+### Translations
+
+With the preliminary work done, you can now add all missing translations for
+your language. Each label on the right side containing the `⬅️ icon` is missing
+a translation. To ensure the accuracy of your translation, consider double-checking
+the context of the words by looking at the [English version].
+
+After adding the translation, remove the `⬅️ icon` from each translated line. If
+you don't know how to translate specific fields, simply leave them for other
+contributors to complete.
+
+[English version]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+
+#### Translation context
+
+TO DO MARTIN - explain the translation context
+.
+.
+
+
+### Country flag
+
+Congratulations on contributing translations for a new language! To make it
+easier for you and others to find the language in our list of supported
+languages, please select the best-fitting flag for your language from our
+documentation's [Icons, Emojis site] by entering the command `flag` in the
+search field.
+
+!!! warning "Icon limitation by Twemoji"
+
+ Please note that only icons provided by Twemoji can be used. If your flag is
+ not available on the list on the [Icons, Emojis site], please choose an
+ alternative.
+
+> __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 Temoji, it is best that you provide us with an alternative instead of us
+> choosing one for you.
+
+ [Icons, Emojis site]: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality and complete
+translation issue – 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 integrate your contribution to Material for MkDocs.
+
+__We'll take it from here.__
+
+---
+
+## Authors credits
+
+Authors who submit a translation using the template above will be
+__credited as co-authors__ in commits for Material for MkDocs. To list your
+account as a co-author without knowing or revealing your email address, we will
+use your GitHub-provided no-reply email, following
+[GitHub's recommended workaround] to protect your privacy. This way, your
+commit will count as a contribution without opening a pull request.
+
+ [GitHub's recommended workaround]: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors
+
+## Contributing via pull request
+
+If you want to contribute missing translations by creating a pull request to be
+listed as the sole author of the commit, you can open a PR after submitting the
+translation issue. Ensure you thoroughly read the pull request guide below to
+prevent breaking functionality in the translation file.
+
+1. Fill out a [translation issue] according to the guide and submit it in the
+ [issue tracker].
+
+2. Tick the box for the last point in the "Before submitting..." section.
+ - [x] __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).
+
+3. Fork the Material for MkDocs repository, set up a [development environment]
+and create a separate git branch on which you make all your changes.
+
+4. Please review all [existing language files] in the repository and search for
+your language. If a file for your language already exists, please use it for
+your edits or create a new file if your language is not listed by copying one of
+the existing files.
+
+5. Add the missing translations for your language to the best of your knowledge
+ and save the changes.
+
+ !!! warning "Important"
+ Only add the translations that are different from the defaults. For
+ example, if your language is left-to-right, don't add the `direction`
+ translation, as English is also left-to-right. The following
+ translations are for technical purposes, and __should not be updated__.
+ If they're missing from your language, it's for a good reason:
+
+ - `search.config.lang`
+ - `search.config.pipeline`
+ - `search.config.separator`
+
+6. Open the [English translations] file and compare your translations with the
+ up-to-date English translations file.
+
+7. 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.
+
+8. 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.
+
+9. After your PR is merged, you can safely delete your branch and pull the
+changes from the main (upstream) repository.
+
+ [translation issue]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
+ [existing language files]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
+ [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+ [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
+
+__After your PR was merged by us maintainers, you can start using the new language.__
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 4c3ed1064..36f9f0b44 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -1,18 +1,32 @@
# 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.
+that serves 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,
+we maintainers need to put in a lot of work.
+
+Our community is pretty big and includes many active users who open new
+discussions or issues multiple times a day, filling the [issue tracker] or the
+[discussion board] with a lot of valuable knowledge. As such, we consider our
+issue tracker and discussion board to be a knowledge base that is an important
+addition to our [documentation], and brings value to both new and experienced
+users of Material for MkDocs.
## 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.
+We've invested time and effort into making our [issue tracker] and [discussion board]
+as user-friendly as possible. We understand that reporting bugs,
+requesting features, and engaging with our community can be challenging, so
+we've optimized our templates and added guidelines to improve all overall
+interaction within this project.
+
+Our goal is to ensure that our platform is __well-structured__, __easy to navigate__,
+and __searchable__, so you can find what you need quickly and efficiently. We've
+also optimized our templates to help us understand your needs better, so we can
+provide you with faster and more effective support. In this documentation
+section, we'll give you an overview of each process and guide you to the
+detailed subpages.
- [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
### Creating an issue
@@ -22,7 +36,7 @@ the documentation explains each process.
---
- 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]
@@ -38,7 +52,7 @@ the documentation explains each process.
---
- 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]
@@ -46,13 +60,147 @@ the documentation explains each process.
---
- 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]
+
+
+### Contributing to this project
+
+
+
+- :material-translate-variant:{ .lg .middle } __Missing support for your language?__
+
+ ---
+
+ Add missing translations for a new or supported language
+
+ [:octicons-arrow-right-24: Add a translation](https://github.com/squidfunk/mkdocs-material/adding-a-translation)
+
+- :material-source-pull:{ .lg .middle } __Want to create a pull request?__
+
+ ---
+
+ Learn how to create a comprehensive pull request (PR)
+
+ [:octicons-arrow-right-24: Create a pull request](https://github.com/squidfunk/mkdocs-material/creating-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
+
+---
+
+!!! warning "Issues, discussions, and comments are permanent"
+
+ Please note that everything you write is permanent and will remain
+ for everyone to read in this project forever. Therefore, be nice, follow
+ our contribution guidelines, and comply with our Code of Conduct.
+
+---
+
+## Before contributing
+
+Before interacting within this project, please take a moment to consider the
+following questions. By doing so, you can ensure that you are using the correct
+issue template or provide all necessary information when interacting with the
+community:
+
+### Before submitting an issue, review:
+
+- Am I using the right issue template for my [request], [report], or [contribution]?
+- Have I checked if a similar issue or request has already been submitted?
+- Did I fill out every field as requested?
+- Did I provide all additional information others might need to comprehend my request?
+
+ [request]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=&template=03-request-a-change.yml
+ [report]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=&template=01-report-a-bug.yml
+ [contribution]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
+
+### Before asking a question, reconsider:
+
+- Is there an open discussion on the topic of my request?
+- Does my question fit the direction of the discussion, or should I open a new discussion?
+- Is my topic a question for the discussion boards, or is it a bug report or idea request that requires a new issue?
+- Did I provide the community with all the necessary information to comprehend my question?
+- Have I checked if my question has been answered before?
+
+### Before leaving a comment, rethink:
+
+- Is my comment directly related to the topic of this page, e.g., blog post or discussion?
+- Is it a comment or a request?
+- Should I use the discussion board for my request or comment instead?
+- Does my comment add value to the conversation?
+- Is my comment respectful and constructive?
+
+---
+
+## Code of Conduct (CoC)
+
+With a large community like ours, it's essential to follow the rules of our
+[Code of Conduct] and value the standards of acceptable behavior. Please take a
+moment to read through our [Code of Conduct], which can always be found
+in full on our documentation. Please pay particular attention to our key values
+and keep them in mind when participating in any interactions within this project.
+
+### Our key values
+
+:material-handshake: Treat the community and the maintainers with respect
+
+:material-comment-text-multiple: Use welcoming, inclusive, and respectful language
+
+:material-account-group: Embrace and understand different viewpoints and experiences
+
+:material-checkbox-multiple-marked-circle: Accept decisions from the maintainers, even if things are not going your way
+
+:material-heart-multiple: Focus on what's best for the community and show empathy towards other community members
+
+---
+
+## Rights and responsibilities
+
+As maintainers, we reserve the right and have the responsibility to close,
+remove, reject, or edit contributions, such as issues, 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 information that is crucial to us when reviewing and
+responding to issues. Each field in our issue templates has been thoughtfully
+curated, requesting only the necessary information to understand your report or
+request. Therefore, it is mandatory for you to fill out every field as requested
+to the best of your knowledge without questioning the issue template. Trust us,
+we need this information because it ensures that every user and project
+maintainer, regardless of experience, can understand the content and severity of
+your report or request.
+
+> __Please note that we reserve the right to close issues__ missing essential
+> information, such as minimal reproductions, or that do not comply with
+> the quality standards and requirements stated in the issue template. Issues
+> can be reopened once the missing information has been provided.
+
+
+### CoC violations
+
+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
+strive to create a positive and supportive environment and consider any
+inappropriate, threatening, offensive, or harmful behavior violating our Code of
+Conduct. We take such violations seriously and will take appropriate action in
+response.
+
+> __Please note__ that we __reserve the right and have the responsibility to remove, edit, or reject any contributions__,
+> including comments, commits, and issues, that violate our Code of Conduct. We
+> may also temporarily or permanently ban users found to be violating of the CoC
+> from contributing to or interacting in the project.
+
+ [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/
+ [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
+
diff --git a/docs/contributing/reporting-a-bug.md b/docs/contributing/reporting-a-bug.md
index acb6a933d..b02e40182 100644
--- a/docs/contributing/reporting-a-bug.md
+++ b/docs/contributing/reporting-a-bug.md
@@ -1,15 +1,15 @@
-# Reporting a bug
+# Bug reporting
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
## Before creating an issue
-With more than 20,000 users, issues are created every other day. The maintainers
+With more than 20.000 users, issues are created every other day. The maintainers
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.
@@ -50,7 +50,7 @@ adjusted all partials you have overridden.
A handful of the features Material for MkDocs offers can only be implemented
with customizations. If you find a bug in any of the customizations [that
- our documentation explicitly mentions], you are of course encouraged to
+ our documentation explicitly mentions], you are, of course, encouraged to
report it.
__Don't be shy to ask on our [discussion board] for help if you run into
@@ -66,7 +66,7 @@ problems.__
[theme.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"
@@ -74,7 +74,7 @@ problems.__
At this stage, we know that the problem persists in the latest version and is
not caused by any of your customizations. However, the problem might result from
-a small typo or a syntactical error in a configuration file, e.g. `mkdocs.yml`.
+a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml`.
Now, before you go through the trouble of creating a bug report that is answered
and closed right away with a link to the relevant documentation section or
@@ -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.
---
@@ -118,14 +118,14 @@ 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
+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
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
@@ -157,7 +157,7 @@ can be inferred from the title.
### 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,9 +165,9 @@ 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
+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
that should be reported to Material for MkDocs, and not to one of its
dependencies.[^3] Adhere to the following principles:
@@ -189,7 +189,7 @@ dependencies.[^3] Adhere to the following principles:
or two sentences, perfect. Don't inflate it – maintainers and future users
will be grateful for having to read less.
-- __One bug at a time__ – if you encountered several unrelated bugs, please
+- __One bug at a time__ – if you encounter several unrelated bugs, please
create separate issues for them. Don't report them in the same issue, as
this makes attribution difficult.
@@ -239,7 +239,7 @@ it allows us maintainers to quickly recreate the necessary conditions to inspect
the bug and 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 }
---
@@ -247,7 +247,7 @@ After you have created the reproduction, you should have a .zip file, ideally no
larger than 1 MB. Just drag and drop the .zip file into this field, which will
automatically upload it to GitHub.
-> __Why we need this__: if an issue contains no minimal reproduction, or just
+> __Why we need this__: if an issue contains no minimal reproduction or just
> a link to a repository with thousands of files, the maintainers would need to
> invest a lot of time into trying to recreate the right conditions to even
> inspect the bug, let alone fix it.
@@ -256,27 +256,27 @@ 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.
Additionally, there are many non-technical users of Material for MkDocs that
have trouble creating repositories.
- [Create reproduction]: ../guides/creating-a-reproduction.md
- [built-in info plugin]: ../guides/creating-a-reproduction.md#creating-a-zip-file
+ [Create reproduction]: reproduction.md
+ [built-in info plugin]: reproduction.md#creating-a-zip-file
### Steps to reproduce
-At this point, you provided us with enough information to understand the bug,
-and you gave us a reproduction that we can run and inspect. However, when we
+At this point, you provided us with enough information to understand the bug
+and 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
the bug in action.
Next, 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.
+five-year-old, and focus on continuity.
> __Why we need this__: we must know how to navigate your reproduction in order
> to observe the bug, as some bugs only occur at certain viewports or in
@@ -284,10 +284,12 @@ 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.
+[previewing] or [building] your site. Moreover, to verify that a browser
+extension is not the source of the bug, test if the issue persists when
+switching to incognito mode.
> __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
@@ -300,15 +302,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 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 ce6cf853c..985265205 100644
--- a/docs/contributing/reporting-a-docs-issue.md
+++ b/docs/contributing/reporting-a-docs-issue.md
@@ -1,42 +1,30 @@
-# Reporting a docs issue
+# Documentation issue reporting
-In the past 7 years, our documentation has grown to more than 60 pages. With a
-site being this large, inconsistencies can occur. If you found an inconsistency
-or see room for clarification or improvement, please submit an issue to
-our public [issue tracker] by following this guide.
+The documentation for Material for MkDocs is spread across more than 60 pages
+and covers information about its features, configurations, and everything you
+need to take advantage of Material for MkDocs' full capabilities. If you have
+found an inconsistency, an issue, or see room for improvement in the
+documentation, please submit an issue to our public [issue tracker] by following
+this guide.
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
-## Issue template
+## Documentation 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:
-
-- [Title]
-- [Description]
-- [Related links]
-- [Proposed change] optional
-- [Checklist]
-
- [reproduction]: ../guides/creating-a-reproduction.md
- [Title]: #title
- [Description]: #description
- [Related links]: #related-links
- [Proposed change]: #proposed-change
- [Checklist]: #checklist
+Reporting something in the documentation differs from reporting a bug in the code.
+Please thoroughly read the following guide before creating a new documentation
+issue.
### Title
-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.
+An excellent documentation issue title should be a short, one-sentence
+description of the issue and contain all relevant information and, in particular
+keywords – to simplify the search in the 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-check:{ style="color: #4DB6AC" } __Clear__ | wrong feature flag code.action
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
### Description
@@ -44,46 +32,45 @@ the issue tracker.
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:
+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.
+ precisely explained in one or two sentences, perfect.
-- __One issue at a time__ – if you encountered several unrelated inconsistencies,
- please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
+- __One issue at a time__ – if you encounter multiple unrelated inconsistencies
+ or issues on different documentation sites, please create separate issues.
+ Don't report multiple issues in one issue report, which makes identifying
+ them 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__: for us to understand the issue you have found or the
+> clarification of the documentation needs, we ask for a description and
+> explanation of the serenity.
-### Related links
+### Links to the documentation
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)
-where possible, as it simplifies discovery.
+we now ask you to share the link to this specific documentation section. Make
+sure you link to the sub-pages and anchor the headings directly.
-> __Why we need this__: providing the links to the documentation help us
+> __Why we need this__: providing the link to the documentation helps us
> understand which sections of our documentation need to be adjusted, extended,
-> or overhauled.
+> or overhauled.
-### Proposed change optional { #proposed-change }
+### Improvement proposals
-Now that you have provided us with the description and links to the
-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.
+Now that you have provided us with the description and link to the
+documentation, you can help us, maintainers, and the community by proposing an
+improvement. This can be a suggestion, a fix, or a temporary workaround.
> __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.
+> who encounter the same issue, since it will offer them a temporary solution
+> until 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 your best knowledge to provide us with every piece of
-information we need to improve our documentation.
+Thanks for following the documentation issue reporting guide and creating a
+high-quality documentation issue report. 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 the Material for MkDocs documentation.
__We'll take it from here.__
diff --git a/docs/contributing/requesting-a-change.md b/docs/contributing/requesting-a-change.md
index cf4ba03f8..a3a1ab18f 100644
--- a/docs/contributing/requesting-a-change.md
+++ b/docs/contributing/requesting-a-change.md
@@ -1,6 +1,6 @@
# Requesting a change
-Material for MkDocs is a powerful tool to create beautiful and functional
+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.
@@ -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 the community.
This guide is our best effort to explain the criteria and reasoning behind our
decisions when evaluating change requests and considering them for
@@ -22,7 +22,7 @@ implementation.
## Before creating an issue
-Before you invest your time to fill out and submit a change request, we kindly
+Before you invest your time in filling out and submit a change request, we kindly
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.
@@ -33,7 +33,7 @@ __Please find answers to the following questions before creating an issue.__
### It's not a bug, it's a feature
-Change requests are intended for suggesting minor adjustments, ideas for new
+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.
@@ -58,15 +58,14 @@ that benefits a large number of users.
[:octicons-comment-discussion-16: Start a discussion][Start a discussion]{ .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
that your idea meets our requirements, you are invited to create a change
-request. The following guide will walk you through all necessary steps to help
-you submit a comprehensive and useful issue:
+request. The following guide will walk you through all the necessary steps to
+help you submit a comprehensive and useful issue:
- [Title]
- [Context] optional
@@ -105,22 +104,15 @@ in which you're using Material for MkDocs, and what you _think_ might be
relevant. Don't write about the change request here.
> __Why this might be helpful__: some ideas might only benefit specific
-> settings, environments or edge cases, for example, when your documentation
+> settings, environments, or edge cases, for example, when your documentation
> contains thousands of documents. With a little context, change requests
> can be prioritized more accurately.
### 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]
-
- [^1]:
- Sometimes, users suggest ideas on our [issue tracker] that concern one of
- our upstream dependencies, including [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 bigger impact.
+idea is relevant to Material for MkDocs and must be implemented here and not
+in one of its dependencies:
- __Explain the what, not the why__ – don't explain
[the benefits of your idea][Use cases] here, we're getting there.
@@ -131,24 +123,19 @@ 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.
---
:material-run-fast: __Stretch goal__ – if you have a customization or another
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.
+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
> 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
@@ -164,7 +151,7 @@ the link to the discussion as well.
### 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 not only benefit 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?
@@ -197,8 +184,66 @@ it and describing how it was implemented and incorporated.
### 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
+change request. 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.__
+
+---
+
+## Your change request was rejected?
+
+We're sorry that your change request didn't make the cut. We understand it can
+be frustrating when your ideas don't get accepted. We want you to know that as
+project maintainers, we have to weigh the community's needs as a whole, and
+sometimes that means making tough decisions. We always try to consider many
+factors when evaluating change requests, and we'll explain the reasoning behind
+our decisions whenever we can. If you're unsure why your request was turned
+down, please ask for clarification.
+
+### Common reasons
+
+To provide you with some insight as to why your idea may have been rejected,
+it's possible that it didn't align with the project's goals and direction or
+the available resources. Here are a few common reasons for rejections:
+
+> __Your idea may not...__
+
+> - match the overall tone or vision of this project
+> - be compatible with existing features, themes, or plugins
+> - be useful to the majority of users
+> - be user-friendly for authors
+> - be implemented in an accessible way
+> - be implemented with reasonable effort
+> - be implemented using the [principle of progressive enhancement]
+> - be implemented to work on all screen sizes
+> - be implemented to work on all modern browsers
+
+
+We highly value and appreciate every idea and contribution you bring to the
+table, and we encourage you to keep sharing them with us. Some of these ideas
+might even be implemented by us! However, we want to remind you that you also
+have the power to implement your ideas on your own by customizing the theme. If
+you're unsure about how to realize your ideas or want to know if someone has
+already found a solution, feel free to visit our [discussion board] - it's the
+perfect place for you!
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [principle of progressive enhancement]: https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement?retiredLocale=de
+
+### Dependencies
+
+Occasionally, users propose ideas on our [issue tracker] that concern one of our
+upstream [dependencies], such as [MkDocs], [Python Markdown],
+[Python Markdown Extensions] or third-party plugins. In such cases, it's
+worthwhile to consider whether your idea could benefit other themes as well. If
+so, you might want to consider submitting a change request upstream to have a
+greater impact.
+
+ [dependencies]: https://squidfunk.github.io/mkdocs-material/setup/dependencies/image-processing/
+ [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
+ [dependencies]: #dependencies
diff --git a/mkdocs.yml b/mkdocs.yml
index c120475fb..e6b757c3d 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -175,6 +175,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 a translation: contributing/adding-a-translation.md
- Asking a question: https://github.com/squidfunk/mkdocs-material/discussions
- Guides:
- Creating a reproduction: guides/creating-a-reproduction.md