OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated guides

Browse Source
This commit is contained in:
katharinalisalin 2023-04-04 14:58:40 +02:00
parent 270129abcb
commit 268c5066ba
8 changed files with 598 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
.github/ISSUE_TEMPLATE/04-add-a-translation.yml vendored
View File

@ -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).

131
CONTRIBUTING.md
View File

@ -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

236
docs/contributing/adding-a-translation.md Normal file
View File

@ -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] <small>optional</small>
- [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.__

170
docs/contributing/index.md
View File

@ -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]
</div>
### Contributing to this project
<div class="grid cards" markdown>
- :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)
</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
---
!!! 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

59
docs/contributing/reporting-a-bug.md
View File

@ -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] <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
@ -157,7 +157,7 @@ can be inferred from the title.
### 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,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:&nbsp; 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 <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.
[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.

93
docs/contributing/reporting-a-docs-issue.md
View File

@ -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] <small>optional</small>
- [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 <small>optional</small> { #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.__

97
docs/contributing/requesting-a-change.md
View File

@ -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:&nbsp; 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] <small>optional</small>
@ -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 <u>what</u>, not the <u>why</u>__ – 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

1
mkdocs.yml
View File

@ -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