mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Martin Donath
GitHub
commit
207c69905b
@ -51,7 +51,7 @@ body:
|
||||
description: >-
|
||||
Please explain how your idea will work from an author's and user's
|
||||
perspective. Elaborate on how the change would positively impact not only
|
||||
you but the community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
|
||||
you but our community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
|
||||
of the project.
|
||||
[More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#use-cases)
|
||||
validations:
|
||||
|
||||
@ -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",
|
||||
@ -76,13 +80,25 @@ body:
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: country-flag
|
||||
attributes:
|
||||
label: Country flag icon
|
||||
description: >-
|
||||
Please add the flag of the country when adding a new language. Select
|
||||
it on our [Icons, Emojis site](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
|
||||
by entering `flag` in the search field. If your flag is not provided by
|
||||
Twemoji, please choose the closest matching flag.
|
||||
[More](https://squidfunk.github.io/mkdocs-material/contributing/adding-a-translation/#country-flag)
|
||||
placeholder: |-
|
||||
Post the flag of the country here.
|
||||
|
||||
- type: checkboxes
|
||||
id: checklist
|
||||
attributes:
|
||||
label: Before submitting
|
||||
description: >-
|
||||
Please ensure that your translation fulfills the following
|
||||
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
|
||||
@ -91,4 +107,3 @@ body:
|
||||
- label: >-
|
||||
__Optional__: I want to integrate this translation myself and create a
|
||||
pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).
|
||||
|
||||
4
.github/ISSUE_TEMPLATE/config.yml
vendored
4
.github/ISSUE_TEMPLATE/config.yml
vendored
@ -22,4 +22,6 @@ blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Ask a question
|
||||
url: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
about: Have a question or need help? Connect with the community on our discussion board
|
||||
about: >
|
||||
Have a question or need help? Connect with our community on the
|
||||
discussion board
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
In the interest of fostering an open and welcoming environment, we as
|
||||
contributors and maintainers pledge to making participation in our project and
|
||||
our community a harassment-free experience for everyone, regardless of age, body
|
||||
size, disability, ethnicity, gender identity and expression, level of experience,
|
||||
size, disability, ethnicity, gender identity and expression, level of experience,
|
||||
nationality, personal appearance, race, religion, or sexual identity and
|
||||
orientation.
|
||||
|
||||
@ -16,7 +16,7 @@ Examples of behavior that contributes to creating a positive environment include
|
||||
* Using welcoming and inclusive language
|
||||
* Being respectful of differing viewpoints and experiences
|
||||
* Gracefully accepting constructive criticism
|
||||
* Focusing on what is best for the community
|
||||
* Focusing on what is best for our community
|
||||
* Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
@ -36,7 +36,7 @@ Project maintainers are responsible for clarifying the standards of acceptable
|
||||
behavior and are expected to take appropriate and fair corrective action in
|
||||
response to any instances of unacceptable behavior.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject
|
||||
comments, commits, code, wiki edits, issues, and other contributions that are
|
||||
not aligned to this Code of Conduct, or to ban temporarily or permanently any
|
||||
contributor for other behaviors that they deem inappropriate, threatening,
|
||||
@ -45,21 +45,21 @@ offensive, or harmful.
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces
|
||||
when an individual is representing the project or its community. Examples of
|
||||
when an individual is representing the project or its community. Examples of
|
||||
representing a project or community include using an official project e-mail
|
||||
address, posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event. Representation of a project may be
|
||||
address, posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event. Representation of a project may be
|
||||
further defined and clarified by project maintainers.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported by contacting the project team at
|
||||
https://gitter.im/squidfunk/mkdocs-material. The project team will review and
|
||||
investigate all complaints, and will respond in a way that it deems appropriate
|
||||
to the circumstances. The project team is obligated to maintain confidentiality
|
||||
with regard to the reporter of an incident. Further details of specific
|
||||
enforcement policies may be posted separately.
|
||||
reported by contacting the project team privately at hello@squidfunk.com. The
|
||||
project team will review and investigate all complaints, and will respond in a
|
||||
way that it deems appropriate to the circumstances. The project team is
|
||||
obligated to maintain confidentiality with regard to the reporter of an
|
||||
incident. Further details of specific enforcement policies may be posted
|
||||
separately.
|
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good
|
||||
faith may face temporary or permanent repercussions as determined by other
|
||||
|
||||
131
CONTRIBUTING.md
131
CONTRIBUTING.md
@ -1,112 +1,61 @@
|
||||
# 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, evaluate change requests, and
|
||||
fix bugs, we maintainers need to put in a lot of work. We have devoted
|
||||
significant effort to creating better templates for our issue tracker,
|
||||
optimizing the processes for our users to report bugs, request features or
|
||||
changes, contribute to the project, or exchange with our community.
|
||||
|
||||
## Submission context
|
||||
|
||||
### Got a question or problem?
|
||||
|
||||
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].
|
||||
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.
|
||||
|
||||
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
[submission guidelines]: #submission-guidelines
|
||||
[documentation]: https://squidfunk.github.io/mkdocs-material/
|
||||
|
||||
### Missing a feature?
|
||||
## How to contribute
|
||||
|
||||
You can request a new feature by submitting an issue to our GitHub Repository.
|
||||
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:
|
||||
### Creating an issue
|
||||
|
||||
* 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.
|
||||
- #### [Report a bug]
|
||||
|
||||
* **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.
|
||||
__Something is not working?__ Report a bug in Material for MkDocs by
|
||||
creating an issue with a reproduction
|
||||
|
||||
### Missing translations?
|
||||
- #### [Report a docs issue]
|
||||
|
||||
Material for MkDocs supports 60+ 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 60+ languages), so we have to rely on
|
||||
our contributors to update translations incrementally. This process is pretty
|
||||
simple, so if you find a translation missing in your language, follow these
|
||||
guidelines:
|
||||
__Missing information in our docs?__ Report missing information or
|
||||
potential inconsistencies in our documentation
|
||||
|
||||
1. Fork the repository.
|
||||
- #### [Request a change]
|
||||
|
||||
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:
|
||||
__Want to submit an idea?__ Propose a change, feature request, or
|
||||
suggest an improvement
|
||||
|
||||
- `search.config.lang`
|
||||
- `search.config.pipeline`
|
||||
- `search.config.separator`
|
||||
- #### [Ask a question]
|
||||
|
||||
3. Create a PR (see below) with your changes.
|
||||
__Have a question or need help?__ Ask a question on our [discussion board]
|
||||
and get in touch with our community
|
||||
|
||||
[translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
|
||||
[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
|
||||
### Contributing
|
||||
|
||||
## Submission guidelines
|
||||
- #### [Add a translation]
|
||||
|
||||
### Submitting an issue
|
||||
__Missing support for your language?__ Add missing translations for a new
|
||||
or already supported language
|
||||
|
||||
Before you submit an issue, please search the issue tracker, maybe an issue for
|
||||
your problem already exists, and the discussion might inform you of workarounds
|
||||
readily available.
|
||||
- #### [Create a pull request]
|
||||
|
||||
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.
|
||||
__Want to create a pull request?__ Learn how to create a comprehensive
|
||||
and useful pull request (PR)s
|
||||
|
||||
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
|
||||
[Add a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
|
||||
[Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
|
||||
|
||||
16
README.md
16
README.md
@ -17,19 +17,15 @@
|
||||
alt="Build"
|
||||
/></a>
|
||||
<a href="https://pypistats.org/packages/mkdocs-material"><img
|
||||
src="https://img.shields.io/pypi/dm/mkdocs-material.svg"
|
||||
src="https://img.shields.io/pypi/dm/mkdocs-material.svg"
|
||||
alt="Downloads"
|
||||
/></a>
|
||||
<a href="https://gitter.im/squidfunk/mkdocs-material"><img
|
||||
src="https://badges.gitter.im/squidfunk/mkdocs-material.svg"
|
||||
alt="Chat on Gitter"
|
||||
/></a>
|
||||
<a href="https://pypi.org/project/mkdocs-material"><img
|
||||
src="https://img.shields.io/pypi/v/mkdocs-material.svg"
|
||||
<a href="https://pypi.org/project/mkdocs-material"><img
|
||||
src="https://img.shields.io/pypi/v/mkdocs-material.svg"
|
||||
alt="Python Package Index"
|
||||
/></a>
|
||||
<a href="https://hub.docker.com/r/squidfunk/mkdocs-material/"><img
|
||||
src="https://img.shields.io/docker/pulls/squidfunk/mkdocs-material"
|
||||
<a href="https://hub.docker.com/r/squidfunk/mkdocs-material/"><img
|
||||
src="https://img.shields.io/docker/pulls/squidfunk/mkdocs-material"
|
||||
alt="Docker Pulls"
|
||||
/></a>
|
||||
</p>
|
||||
@ -48,7 +44,7 @@
|
||||
|
||||
<p align="center">
|
||||
<em>
|
||||
Check out the demo –
|
||||
Check out the demo –
|
||||
<a
|
||||
href="https://squidfunk.github.io/mkdocs-material/"
|
||||
>squidfunk.github.io/mkdocs-material</a>.
|
||||
|
||||
125
docs/contributing/adding-translations.md
Normal file
125
docs/contributing/adding-translations.md
Normal file
@ -0,0 +1,125 @@
|
||||
# Translations
|
||||
|
||||
It's unbelievable – with the help of international community contributions,
|
||||
Material for MkDocs has been translated into 60+ languages. As you can imagine,
|
||||
it's impossible for us maintainers to keep all languages up-to-date, and new
|
||||
features sometimes require new translations.
|
||||
|
||||
If you would like to help us to make Material for MkDocs even more globally
|
||||
accessible and have noticed a missing translation in your language, or would
|
||||
like to add a new language, you can help us by following the steps of the guide
|
||||
below.
|
||||
|
||||
## Before creating an issue
|
||||
|
||||
Translations change frequently, which is why we want to make sure that you don't
|
||||
invest your time in duplicating work. Before adding translations, please check
|
||||
the following things:
|
||||
|
||||
### Check language availability
|
||||
|
||||
With more than 60 languages, the chances are good that your language is already
|
||||
supported by Material for MkDocs. You can check if your language is available,
|
||||
or needs improvements or additional translations by inspecting the list of
|
||||
[supported languages]:
|
||||
|
||||
- __Your language is already supported__ – in this case, you can check if there
|
||||
are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
|
||||
|
||||
- __Your language is missing__ – in that case, you can help us add support
|
||||
for your language to Material for MkDocs! Read on, to learn how to do this.
|
||||
|
||||
[supported languages]: ../setup/changing-the-language.md#site-language
|
||||
|
||||
### Search our issue tracker
|
||||
|
||||
Another user might have already created an issue supplying the missing
|
||||
translations for your language that still needs to be integrated by us
|
||||
maintainers. To avoid investing your time in duplicated work, please search the
|
||||
[issue tracker] beforehand.
|
||||
|
||||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
|
||||
---
|
||||
|
||||
At this point, when you have made sure that Material for MkDocs doesn't already
|
||||
support your language, you can add new translations for it by following the
|
||||
issue template.
|
||||
|
||||
## Issue template
|
||||
|
||||
We have created an issue template that makes contributing translations as simple
|
||||
as possible. It is the result of our experience with 60+ language contributions
|
||||
and updates over the last couple of years, and consists of the following parts:
|
||||
|
||||
- [Title]
|
||||
- [Translations]
|
||||
- [Country flag] <small>optional</small>
|
||||
- [Checklist]
|
||||
|
||||
[Title]: #title
|
||||
[Translations]: #translations
|
||||
[Country flag]: #country-flag
|
||||
[Checklist]: #checklist
|
||||
|
||||
### Title
|
||||
|
||||
When you update an already existing language, you can just leave the title as it
|
||||
is. Adding support for a new language, replace the `...` in the pre-filled title
|
||||
with the name of your language.
|
||||
|
||||
| <!-- --> | Example |
|
||||
| -------- | -------- |
|
||||
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
|
||||
| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
|
||||
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
|
||||
|
||||
### Translations
|
||||
|
||||
If a translation contains an :arrow_left: icon on the right side, it is missing.
|
||||
You can translate this line and remove the :arrow_left: icon. If you don't know
|
||||
how to translate specific lines, simply leave them for other contributors to
|
||||
complete. To ensure the accuracy of your translation, consider double-checking the
|
||||
context of the words by looking at our [English translations].
|
||||
|
||||
[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
|
||||
|
||||
### Country flag <small>optional</small> { #country-flag }
|
||||
|
||||
For a better overview, our list of [supported languages] includes country flags
|
||||
next to the language names. You can help us select a flag for your language by
|
||||
adding the shortcode for the country flag to this field. Go to our
|
||||
[emoji search] and enter `flag` to find all available shortcodes.
|
||||
|
||||
!!! question "What if my flag is not available?"
|
||||
|
||||
[Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
|
||||
such as states, provinces, or regions, are not supported. If you're adding
|
||||
translations for a subdivision, please choose the most appropriate available
|
||||
flag.
|
||||
|
||||
[Twemoji]: https://twemoji.twitter.com/
|
||||
[emoji search]: ../reference/icons-emojis.md#search
|
||||
|
||||
> __Why this might be helpful__: adding a country flag next to the country name
|
||||
> can be helpful for you and for others to find the language in the list of
|
||||
> supported languages faster and easier. If your country's flag is not supported
|
||||
> by [Twemoji], you can help us choose an alternative.
|
||||
|
||||
### Checklist
|
||||
|
||||
Thanks for following the guide and helping us to add new translations to Material
|
||||
for MkDocs – you are almost done. The checklist ensures that you have read this
|
||||
guide and have worked to your best knowledge to provide us with everything we need
|
||||
to integrate your contribution.
|
||||
|
||||
__We'll take it from here.__
|
||||
|
||||
---
|
||||
|
||||
## Attribution
|
||||
|
||||
If you submit a translation using the template above, you will be __credited as
|
||||
a co-author__ in the commit, so you don't need to open a pull request. You have
|
||||
done a significant contribution to the project, making Material for MkDocs
|
||||
accessible to more people around the world. Thank you!
|
||||
@ -1,58 +1,202 @@
|
||||
# Contributing
|
||||
|
||||
Material for MkDocs is an actively maintained and constantly improved project
|
||||
that caters to a diverse user base with varying backgrounds and needs. In order
|
||||
to effectively address the needs of all our users, evaluate requests, and fix
|
||||
bugs, a lot of work from us maintainers is required.
|
||||
Material for MkDocs is an actively maintained and constantly evolving project
|
||||
serving a diverse user base with versatile backgrounds and needs. In order to
|
||||
efficiently address the requirements of all our users, evaluate change requests,
|
||||
and fix bugs, we put in a lot of work.
|
||||
|
||||
## How to contribute
|
||||
|
||||
We have invested quite a lot of time in creating better templates for our
|
||||
[issue tracker], optimizing the processes for our users to report bugs, request
|
||||
features or changes, contribute to the project, or exchange with our community.
|
||||
This section of the documentation explains each process.
|
||||
Our ever-growing community includes many active users, who open new
|
||||
issues and discussions several times a day, evolving our [issue tracker] and
|
||||
[discussion board] into a knowledge base – an important addition to
|
||||
our [documentation] – yielding value to both new and experienced users.
|
||||
|
||||
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
[documentation]: https://squidfunk.github.io/mkdocs-material/
|
||||
|
||||
## How you can contribute
|
||||
|
||||
We understand that reporting bugs, raising change requests, as well as engaging
|
||||
in discussions can be time-consuming, which is why we've carefully optimized our
|
||||
issue templates and defined guidelines to improve the overall interaction
|
||||
within the project. We've invested a lot of time and effort into making our
|
||||
[issue tracker] and [discussion board] as efficient as possible.
|
||||
|
||||
Our goal is to ensure that our documentation, as well as issue tracker and
|
||||
discussion board, are __well-structured__, __easy to navigate__, and
|
||||
__searchable__, so you can find what you need quickly and efficiently. Thus,
|
||||
when you follow our guidelines, we can help you much faster.
|
||||
|
||||
In this section, we guide your through our processes.
|
||||
|
||||
### Creating an issue
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-bug:{ .lg .middle } __Something is not working?__
|
||||
- :material-bug-outline:
|
||||
__Something is not working?__
|
||||
|
||||
---
|
||||
|
||||
Report a bug in Material for MkDocs by creating an issue and a reproduction
|
||||
Report a bug in Material for MkDocs by creating an issue with a
|
||||
reproduction
|
||||
|
||||
---
|
||||
|
||||
[:octicons-arrow-right-24: Report a bug][report a bug]
|
||||
|
||||
- :material-file-document:{ .lg .middle } __Missing information in our docs?__
|
||||
- :material-file-document-remove-outline:
|
||||
__Missing information in our docs?__
|
||||
|
||||
---
|
||||
|
||||
Report missing information or potential inconsistencies in our documentation
|
||||
Report missing information or potential inconsistencies in our
|
||||
documentation
|
||||
|
||||
---
|
||||
|
||||
[:octicons-arrow-right-24: Report a docs issue][report a docs issue]
|
||||
|
||||
- :material-lightbulb-on:{ .lg .middle } __Want to submit an idea?__
|
||||
- :material-lightbulb-on-20:
|
||||
__Want to submit an idea?__
|
||||
|
||||
---
|
||||
|
||||
Propose a change or feature request or suggest an improvement
|
||||
Propose a change, feature request, or suggest an improvement
|
||||
|
||||
---
|
||||
|
||||
[:octicons-arrow-right-24: Request a change][request a change]
|
||||
|
||||
- :material-chat-question:{ .lg .middle } __Have a question or need help?__
|
||||
- :material-account-question-outline:
|
||||
__Have a question or need help?__
|
||||
|
||||
---
|
||||
|
||||
Ask questions on our discussion board and get in touch with our community
|
||||
Ask a question on our [discussion board] and get in touch with our
|
||||
community
|
||||
|
||||
[:octicons-arrow-right-24: Ask a question][ask a question]
|
||||
---
|
||||
|
||||
[:octicons-arrow-right-24: Ask a question][discussion board]
|
||||
|
||||
</div>
|
||||
|
||||
### Contributing
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-translate:
|
||||
__Missing support for your language?__
|
||||
|
||||
---
|
||||
|
||||
Add or improve translations for a new or already supported language
|
||||
|
||||
---
|
||||
|
||||
[:octicons-arrow-right-24: Add a translation][add a translation]
|
||||
|
||||
- :material-source-pull:
|
||||
__Want to create a pull request?__
|
||||
|
||||
---
|
||||
|
||||
Learn how to create a comprehensive and useful pull request (PR)
|
||||
|
||||
---
|
||||
|
||||
[:octicons-arrow-right-24: Create a pull request][create a pull request]
|
||||
|
||||
</div>
|
||||
|
||||
[report a bug]: reporting-a-bug.md
|
||||
[report a docs issue]: reporting-a-docs-issue.md
|
||||
[request a change]: requesting-a-change.md
|
||||
[ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
[add a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
|
||||
[create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
|
||||
|
||||
## Checklist
|
||||
|
||||
Before interacting within the project, please take a moment to consider the
|
||||
following questions. By doing so, you can ensure that you are using the correct
|
||||
issue template and that you provide all necessary information when interacting
|
||||
with our community.
|
||||
|
||||
!!! warning "Issues, discussions, and comments are forever"
|
||||
|
||||
Please note that everything you write is permanent and will remain
|
||||
for everyone to read – forever. Therefore, please always be nice and
|
||||
constructive, follow our contribution guidelines, and comply with our
|
||||
[Code of Conduct].
|
||||
|
||||
### Before creating an issue
|
||||
|
||||
- Are you using the appropriate issue template, or is there another issue
|
||||
template that better fits the context of your request?
|
||||
|
||||
- Have you checked if a similar bug report or change request has already been
|
||||
created, or have you stumbled upon something that might be related?
|
||||
|
||||
- Did your fill out every field as requested and did you provide all additional
|
||||
information we maintainers need to comprehend your request?
|
||||
|
||||
### Before asking a question
|
||||
|
||||
- Is the topic a question for our [discussion board], or is it a bug report or
|
||||
change request that should better be raised on our [issue tracker]?
|
||||
|
||||
- Is there an open discussion on the topic of your request? If the answer is yes,
|
||||
does your question match the direction of the discussion, or should you open a
|
||||
new discussion?
|
||||
|
||||
- Did your provide our community with all the necessary information to
|
||||
understand your question and help you quickly, or can you make it easier to
|
||||
help you?
|
||||
|
||||
### Before commenting
|
||||
|
||||
- Is your comment relevant to the topic of the current page, post, issue, or
|
||||
discussion, or is it a better idea to create a new issue or discussion?
|
||||
|
||||
- Does your comment add value to the conversation? Is it constructive and
|
||||
respectful to our community and us maintainers? Could you just use a
|
||||
[:octicons-smiley-16: reaction][reaction] instead?
|
||||
|
||||
[Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
|
||||
[reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
|
||||
|
||||
## Rights and responsibilities
|
||||
|
||||
As maintainers, we reserve the right and have the responsibility to close,
|
||||
remove, reject, or edit contributions, such as issues, discussions, comments,
|
||||
or commits, that do not align with our contribution guidelines and our
|
||||
[Code of Conduct].
|
||||
|
||||
### Incomplete issues
|
||||
|
||||
We have invested significant time in reviewing our contribution process and
|
||||
carefully assessed the essential requirements when reviewing and responding to
|
||||
issues. Each field in our issue templates has been thoughtfully curated, helping
|
||||
us to understand your matter.
|
||||
|
||||
__Therefore, it is mandatory to fill out every field as requested__ to the best
|
||||
of your knowledge. We need all of this information because it ensures that every
|
||||
user and maintainer, regardless of their experience, can understand the content
|
||||
and severity of your bug report or change request.
|
||||
|
||||
__We reserve the right to close issues missing essential information__, such as
|
||||
but not limited to [minimal reproductions], or that do not comply with the
|
||||
quality standards and requirements stated in our issue templates. Issues
|
||||
can be reopened once the missing information has been provided.
|
||||
|
||||
[minimal reproductions]: ../guides/creating-a-reproduction.md
|
||||
|
||||
### Code of Conduct
|
||||
|
||||
As stated in our [Code of Conduct], we expect all members of our community to
|
||||
treat each other with respect, and use inclusive and welcoming language. We
|
||||
always strive to create a positive and supportive environment and do not accept
|
||||
inappropriate, offensive, or harmful behavior.
|
||||
|
||||
We take violations seriously and will take appropriate action in response.
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
# Reporting a bug
|
||||
# Bug reports
|
||||
|
||||
Material for MkDocs is an actively maintained project that we constantly strive
|
||||
to improve. With a project of this size and complexity, bugs may occur. If you
|
||||
think you have discovered a bug, you can help us by submitting an issue in our
|
||||
public [issue tracker] by following this guide.
|
||||
public [issue tracker], following this guide.
|
||||
|
||||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
|
||||
@ -14,7 +14,7 @@ of this project are trying very hard to keep the number of open issues down by
|
||||
fixing bugs as fast as possible. By following this guide, you will know exactly
|
||||
what information we need to help you quickly.
|
||||
|
||||
__But first, please try the following things before creating an issue.__
|
||||
__But first, please do the following things before creating an issue.__
|
||||
|
||||
### Upgrade to latest version
|
||||
|
||||
@ -37,7 +37,7 @@ We can't offer official support for bugs that might hide in your overrides, so
|
||||
make sure to omit the following settings from `mkdocs.yml`:
|
||||
|
||||
- [`theme.custom_dir`][theme.custom_dir]
|
||||
- [`theme.hooks`][theme.hooks]
|
||||
- [`hooks`][hooks]
|
||||
- [`extra_css`][extra_css]
|
||||
- [`extra_javascript`][extra_javascript]
|
||||
|
||||
@ -63,10 +63,10 @@ problems.__
|
||||
[JavaScript]: ../customization.md#additional-javascript
|
||||
[theme extension]: ../customization.md#extending-the-theme
|
||||
[theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
|
||||
[theme.hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
|
||||
[hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
|
||||
[extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
|
||||
[extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
|
||||
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
[discussion board]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
[StackOverflow]: https://stackoverflow.com
|
||||
[that our documentation explicitly mentions]: ?q="extends+base"
|
||||
|
||||
@ -104,7 +104,7 @@ them in the bug report.__[^2]
|
||||
|
||||
[^2]:
|
||||
We might be using terminology in our documentation different from yours,
|
||||
but mean the same. When you include the search terms and related links
|
||||
but we mean the same. When you include the search terms and related links
|
||||
in your bug report, you help us to adjust and improve the documentation.
|
||||
|
||||
---
|
||||
@ -119,13 +119,13 @@ how to create a complete and helpful bug report.
|
||||
## Issue template
|
||||
|
||||
We have created a new issue template to make the bug reporting process as simple
|
||||
as possible and more efficient for the community and us. It is the result of
|
||||
as possible and more efficient for our community and us. It is the result of
|
||||
our experience answering and fixing more than 1,600 issues (and counting) and
|
||||
consists of the following parts:
|
||||
|
||||
- [Title]
|
||||
- [Context] <small>optional</small>
|
||||
- [Description]
|
||||
- [Bug description]
|
||||
- [Related links]
|
||||
- [Reproduction]
|
||||
- [Steps to reproduce]
|
||||
@ -134,7 +134,7 @@ consists of the following parts:
|
||||
|
||||
[Title]: #title
|
||||
[Context]: #context
|
||||
[Description]: #description
|
||||
[Bug description]: #bug-description
|
||||
[Related links]: #related-links
|
||||
[Reproduction]: #reproduction
|
||||
[Steps to reproduce]: #steps-to-reproduce
|
||||
@ -152,12 +152,12 @@ can be inferred from the title.
|
||||
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
|
||||
| :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
|
||||
| :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
|
||||
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
|
||||
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
|
||||
|
||||
### Context <small>optional</small> { #context }
|
||||
|
||||
Before describing the bug, you can provide additional context for us to
|
||||
understand what you are trying to achieve. Explain the circumstances
|
||||
understand what you were trying to achieve. Explain the circumstances
|
||||
in which you're using Material for MkDocs, and what you _think_ might be
|
||||
relevant. Don't write about the bug here.
|
||||
|
||||
@ -165,7 +165,7 @@ relevant. Don't write about the bug here.
|
||||
> environments or edge cases, for example, when your documentation contains
|
||||
> thousands of documents.
|
||||
|
||||
### Description
|
||||
### Bug description
|
||||
|
||||
Now, to the bug you want to report. Provide a clear, focused, specific, and
|
||||
concise summary of the bug you encountered. Explain why you think this is a bug
|
||||
@ -239,7 +239,7 @@ it allows us maintainers to instantly recreate the necessary conditions to
|
||||
inspect the bug to quickly find its root cause. It's a proven fact that issues
|
||||
with concise and small reproductions can be fixed much faster.
|
||||
|
||||
[:material-bug: Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
|
||||
[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
|
||||
|
||||
---
|
||||
|
||||
@ -256,7 +256,7 @@ will automatically upload it to GitHub.
|
||||
|
||||
While we know that it is a good practice among developers to include a link
|
||||
to a repository with the bug report, we currently don't support those in our
|
||||
process. The reason is that the reproduction which is automatically
|
||||
process. The reason is that the reproduction, which is automatically
|
||||
produced by the [built-in info plugin] contains all of the necessary
|
||||
environment information that is often forgotten to be included.
|
||||
|
||||
@ -264,16 +264,16 @@ will automatically upload it to GitHub.
|
||||
have trouble creating repositories.
|
||||
|
||||
[Create reproduction]: ../guides/creating-a-reproduction.md
|
||||
[built-in info plugin]: ../guides/creating-a-reproduction.md#creating-a-zip-file
|
||||
[built-in info plugin]: ../plugins/info.md
|
||||
|
||||
### Steps to reproduce
|
||||
|
||||
At this point, you provided us with enough information to understand the bug,
|
||||
and you gave us a reproduction that we could run and inspect. However, when we
|
||||
run your reproduction, it might not be immediately apparent how we can see
|
||||
At this point, you provided us with enough information to understand the bug
|
||||
and provided us with a reproduction that we could run and inspect. However, when
|
||||
we run your reproduction, it might not be immediately apparent how we can see
|
||||
the bug in action.
|
||||
|
||||
Next, please list the specific steps we should follow when running your
|
||||
Thus, please list the specific steps we should follow when running your
|
||||
reproduction to observe the bug. Keep the steps short and concise, and make sure
|
||||
not to leave anything out. Use simple language as you would explain it to a
|
||||
five-year-old, and focus on continuity.
|
||||
@ -284,11 +284,17 @@ five-year-old, and focus on continuity.
|
||||
|
||||
### Browser <small>optional</small> { #browser }
|
||||
|
||||
If you're reporting a bug that only happens in one or more _specific_ browsers,
|
||||
If you're reporting a bug that only occurs in one or more _specific_ browsers,
|
||||
we need to know which browsers are affected. This field is optional, as it is
|
||||
only relevant when the bug you are reporting does not involve a crash when
|
||||
[previewing] or [building] your site.
|
||||
|
||||
---
|
||||
|
||||
:material-incognito: __Incognito mode__ – Please verify that a the bug is
|
||||
not caused by a browser extension. Switch to incognito mode and try to reproduce
|
||||
the bug. If it's gone, it's caused by an extension.
|
||||
|
||||
> __Why we need this__: some bugs only occur in specific browsers or versions.
|
||||
> Since now, almost all browsers are evergreen, we usually don't need to know the
|
||||
> version in which it occurs, but we might ask for it later. When in doubt, add
|
||||
@ -300,15 +306,8 @@ only relevant when the bug you are reporting does not involve a crash when
|
||||
### Checklist
|
||||
|
||||
Thanks for following the guide and creating a high-quality and complete bug
|
||||
report – you are almost done. This section ensures that you have read this guide
|
||||
and have worked to the best of your knowledge to provide us with everything we
|
||||
need to know to help you.
|
||||
report – you are almost done. The checklist ensures that you have read this guide
|
||||
and have worked to your best knowledge to provide us with everything we need to
|
||||
know to help you.
|
||||
|
||||
__We'll take it from here.__
|
||||
|
||||
## Incomplete issues
|
||||
|
||||
Please understand that we reserve the right to close incomplete issues which
|
||||
do not contain minimal reproductions or do not adhere to the quality standards
|
||||
and requirements mentioned in this document. Issues can be reopened when the
|
||||
missing information has been provided.
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
# Reporting a docs issue
|
||||
# Documentation issues
|
||||
|
||||
In the past seven years, our documentation has grown to more than 60 pages. With
|
||||
a site being this large, inconsistencies can occur. If you find an inconsistency
|
||||
or see room for clarification or improvement, please submit an issue to
|
||||
our public [issue tracker] by following this guide.
|
||||
Our documentation is composed of more than 80 pages and includes extensive
|
||||
information on features, configurations, customizations, and much more. If you
|
||||
have found an inconsistency or see room for improvement, please follow this
|
||||
guide to submit an issue on our [issue tracker].
|
||||
|
||||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
|
||||
## Issue template
|
||||
|
||||
Reporting a documentation issue is usually less involved than reporting a bug,
|
||||
as we don't need a [reproduction]. Please thoroughly read the following guide
|
||||
before creating a new documentation issue, and provide the following information
|
||||
as part of the issue:
|
||||
as we don't need a [reproduction]. Please thoroughly read this guide before
|
||||
creating a new documentation issue, and provide the following information as
|
||||
part of the issue:
|
||||
|
||||
- [Title]
|
||||
- [Description]
|
||||
@ -31,43 +31,45 @@ as part of the issue:
|
||||
|
||||
A good title should be a short, one-sentence description of the issue, contain
|
||||
all relevant information and, in particular, keywords to simplify the search in
|
||||
the issue tracker.
|
||||
our issue tracker.
|
||||
|
||||
| <!-- --> | Example |
|
||||
| -------- | -------- |
|
||||
| -------- | -------- |
|
||||
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
|
||||
| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
|
||||
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
|
||||
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
|
||||
|
||||
### Description
|
||||
|
||||
Provide a clear and concise summary of the inconsistency or issue you
|
||||
encountered in the documentation or the documentation section that needs
|
||||
improvement. Explain why you think the documentation should be adjusted and
|
||||
Provide a clear and concise summary of the inconsistency or issue you
|
||||
encountered in the documentation or the documentation section that needs
|
||||
improvement. Explain why you think the documentation should be adjusted and
|
||||
describe the severity of the issue:
|
||||
|
||||
- __Keep it short and concise__ – if the inconsistency or issue can be
|
||||
precisely explained in one or two sentences, perfect. Maintainers and
|
||||
future users will be grateful for having to read less.
|
||||
- __Keep it short and concise__ – if the inconsistency or issue can be
|
||||
precisely explained in one or two sentences, perfect. Maintainers and future
|
||||
users will be grateful for having to read less.
|
||||
|
||||
- __One issue at a time__ – if you encounter several unrelated inconsistencies,
|
||||
please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
|
||||
please create separate issues for them. Don't report them in the same issue
|
||||
– it makes attribution difficult.
|
||||
|
||||
> __Why we need this__: in order for us to understand the problem, we need a
|
||||
> clear description of it and quantify its impact, which is essential for triage
|
||||
> and prioritization.
|
||||
> __Why we need this__: describing the problem clearly and concisely is a
|
||||
> prerequisite for improving our documentation – we need to understand what's
|
||||
> wrong, so we can fix it.
|
||||
|
||||
### Related links
|
||||
|
||||
After you described the documentation section that needs to be adjusted above,
|
||||
After you described the documentation section that needs to be adjusted above,
|
||||
we now ask you to share the link to this specific documentation section and
|
||||
other possibly related sections. Make sure to use anchor links (permanent links)
|
||||
other possibly related sections. Make sure to use anchor links (permanent links)
|
||||
where possible, as it simplifies discovery.
|
||||
|
||||
> __Why we need this__: providing the links to the documentation help us
|
||||
> understand which sections of our documentation need to be adjusted, extended,
|
||||
> __Why we need this__: providing the links to the documentation help us
|
||||
> understand which sections of our documentation need to be adjusted, extended,
|
||||
> or overhauled.
|
||||
|
||||
|
||||
### Proposed change <small>optional</small> { #proposed-change }
|
||||
|
||||
Now that you have provided us with the description and links to the
|
||||
@ -75,15 +77,15 @@ documentation sections, you can help us, maintainers, and the community by
|
||||
proposing an improvement. You can sketch out rough ideas or write a concrete
|
||||
proposal. This field is optional but very helpful.
|
||||
|
||||
> __Why we need this__: improvement proposal can be beneficial for other users
|
||||
> who encounter the same issue, as they offer solutions before we maintainers
|
||||
> can update the documentation.
|
||||
> __Why we need this__: an improvement proposal can be beneficial for other
|
||||
> users who encounter the same issue, as they offer solutions before we
|
||||
> maintainers can update the documentation.
|
||||
|
||||
### Checklist
|
||||
|
||||
Thanks for following the guide and creating a high-quality and complete issue
|
||||
report – you are almost done. This section ensures that you have read this guide
|
||||
and have worked to the best of your knowledge to provide us with every piece of
|
||||
information we need to improve our documentation.
|
||||
Thanks for following the guide and providing valuable feedback for our
|
||||
documentation – you are almost done. The checklist ensures that you have read
|
||||
this guide and have worked to your best knowledge to provide us with every piece
|
||||
of information we need to improve it.
|
||||
|
||||
__We'll take it from here.__
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
# Requesting a change
|
||||
# Change requests
|
||||
|
||||
Material for MkDocs is a powerful tool for creating beautiful and functional
|
||||
project documentation. With more than 20,000 users, we understand that our
|
||||
project serves a wide range of use cases, which is why we have created the
|
||||
following guide.
|
||||
documentation. With more than 20,000 users, we understand that our project
|
||||
serves a wide range of use cases, which is why we have created the following
|
||||
guide.
|
||||
|
||||
---
|
||||
|
||||
Put yourself in our shoes – with a project of this size, it can be challenging
|
||||
to maintain existing functionality while constantly adding new features at the
|
||||
same time. We highly value every idea or contribution from our community, and
|
||||
we kindly ask you to take the time to read the following guidelines before
|
||||
submitting your change request in our public [issue tracker]. This will help us
|
||||
better understand the proposed change and how it will benefit the community.
|
||||
we kindly ask you to take the time to read the following guidelines before
|
||||
submitting your change request in our public [issue tracker]. This will help us
|
||||
better understand the proposed change and how it will benefit our community.
|
||||
|
||||
This guide is our best effort to explain the criteria and reasoning behind our
|
||||
decisions when evaluating change requests and considering them for
|
||||
implementation.
|
||||
implementation.
|
||||
|
||||
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
|
||||
@ -27,45 +27,52 @@ ask you to do some preliminary work by answering some questions to determine if
|
||||
your idea is a good fit for Material for MkDocs and matches the project's
|
||||
[philosophy] and tone.
|
||||
|
||||
__Please find answers to the following questions before creating an issue.__
|
||||
__Please do the following things before creating an issue.__
|
||||
|
||||
[philosophy]: ../philosophy.md
|
||||
|
||||
### It's not a bug, it's a feature
|
||||
|
||||
Change requests are intended to suggest minor adjustments, ideas for new
|
||||
features, or to influence the project's direction and vision. It is important
|
||||
to note that change requests are not intended for reporting bugs, as they're
|
||||
missing essential information for debugging.
|
||||
features, or to kindly influence the project's direction and vision. It is
|
||||
important to note that change requests are not intended for reporting bugs, as
|
||||
they're missing essential information for debugging.
|
||||
|
||||
If you want to report a bug, please refer to our [bug reporting guide] instead.
|
||||
|
||||
[bug reporting guide]: reporting-a-bug.md
|
||||
|
||||
### Source of inspiration
|
||||
### Look for sources of inspiration
|
||||
|
||||
If you have seen your idea implemented in another static site generator or
|
||||
theme, make sure to collect enough information on its implementation before
|
||||
submitting, as this allows us to evaluate potential fit more quickly. Explain
|
||||
what you like and dislike about the implementation.
|
||||
|
||||
### Benefit for the community
|
||||
### Connect with our community
|
||||
|
||||
Our [discussion board] is the best place to connect with our community. When
|
||||
evaluating new ideas, it's essential to seek input from other users and consider
|
||||
Our [discussion board] is the best place to connect with our community. When
|
||||
evaluating new ideas, it's essential to seek input from other users and consider
|
||||
alternative viewpoints. This approach helps to implement new features in a way
|
||||
that benefits a large number of users.
|
||||
|
||||
[:octicons-comment-discussion-16: Start a discussion][Start a discussion]{ .md-button .md-button--primary }
|
||||
__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
|
||||
them in the change request.__[^1]
|
||||
|
||||
[^1]:
|
||||
We might be using terminology in our documentation different from yours,
|
||||
but we mean the same. When you include the search terms and related links
|
||||
in your change request, you help us to adjust and improve the documentation.
|
||||
|
||||
[:octicons-comment-discussion-16: Start a discussion][discussion board]{ .md-button .md-button--primary }
|
||||
|
||||
[discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
[Start a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
|
||||
## Issue template
|
||||
|
||||
Now that you have taken the time to do the necessary preliminary work and ensure
|
||||
Now that you have taken the time to do the necessary preliminary work and ensure
|
||||
that your idea meets our requirements, you are invited to create a change
|
||||
request. The following guide will walk you through all the necessary steps to
|
||||
request. The following guide will walk you through all the necessary steps to
|
||||
help you submit a comprehensive and useful issue:
|
||||
|
||||
- [Title]
|
||||
@ -87,15 +94,15 @@ help you submit a comprehensive and useful issue:
|
||||
### Title
|
||||
|
||||
A good title is short and descriptive. It should be a one-sentence executive
|
||||
summary of the idea, so the potential impact and benefit for the community can
|
||||
summary of the idea, so the potential impact and benefit for our community can
|
||||
be inferred from the title.
|
||||
|
||||
| <!-- --> | Example |
|
||||
| -------- | -------- |
|
||||
| -------- | -------- |
|
||||
| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
|
||||
| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
|
||||
| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
|
||||
| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
|
||||
| :material-close:{ style="color: #EF5350" } __Useless__ | Help
|
||||
|
||||
### Context <small>optional</small> { #context }
|
||||
|
||||
@ -111,13 +118,13 @@ relevant. Don't write about the change request here.
|
||||
|
||||
### Description
|
||||
|
||||
Next, provide a detailed and clear description of your idea. Explain why your
|
||||
idea is relevant to Material for MkDocs and must be implemented here, and not
|
||||
in one of its dependencies:[^1]
|
||||
Next, provide a detailed and clear description of your idea. Explain why your
|
||||
idea is relevant to Material for MkDocs and must be implemented here and not
|
||||
in one of its dependencies:[^2]
|
||||
|
||||
[^1]:
|
||||
[^2]:
|
||||
Sometimes, users suggest ideas on our [issue tracker] that concern one of
|
||||
our upstream dependencies, including [MkDocs], [Python Markdown],
|
||||
our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
|
||||
[Python Markdown Extensions] or third-party plugins. It's a good idea to
|
||||
think about whether your idea is beneficial to other themes, upstreaming
|
||||
change requests for a bigger impact.
|
||||
@ -126,12 +133,12 @@ in one of its dependencies:[^1]
|
||||
[the benefits of your idea][Use cases] here, we're getting there.
|
||||
Focus on describing the proposed change request as precisely as possible.
|
||||
|
||||
- __Keep it short and concise__ – be brief and to the point when describing
|
||||
- __Keep it short and concise__ – be brief and to the point when describing
|
||||
your idea, there is no need to over-describe it. Maintainers and future
|
||||
users will be grateful for having to read less.
|
||||
|
||||
- __One idea at a time__ – if you have multiple ideas that don't belong
|
||||
together, please open separate change requests for each of those ideas.
|
||||
- __One idea at a time__ – if you have multiple ideas that don't belong
|
||||
together, please open separate change requests for each of those ideas.
|
||||
|
||||
---
|
||||
|
||||
@ -140,65 +147,95 @@ way to add the proposed change, you can help other users by sharing it here
|
||||
before we maintainers can add it to our code base.
|
||||
|
||||
> __Why we need this__: To understand and evaluate your proposed change, we
|
||||
> need to have a clear understanding of your idea. By providing a detailed and
|
||||
> need to have a clear understanding of your idea. By providing a detailed and
|
||||
> precise description, you can help save you and us time spent discussing
|
||||
> further clarification of your idea in the comments.
|
||||
|
||||
[MkDocs]: https://www.mkdocs.org
|
||||
[Python Markdown]: https://python-markdown.github.io/extensions/
|
||||
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
|
||||
[theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
|
||||
|
||||
### Related links
|
||||
|
||||
Please provide any relevant links to issues, discussions, or documentation
|
||||
Please provide any relevant links to issues, discussions, or documentation
|
||||
sections related to your change request. If you (or someone else) already
|
||||
discussed this idea with the community on our discussion board, please include
|
||||
discussed this idea with our community on our discussion board, please include
|
||||
the link to the discussion as well.
|
||||
|
||||
> __Why we need this__: Related links help us gain a comprehensive
|
||||
> understanding of your change request by providing additional context.
|
||||
> Additionally, linking to previous issues and discussions allows us
|
||||
> to quickly evaluate the feedback and input already provided by the community.
|
||||
> to quickly evaluate the feedback and input already provided by our community.
|
||||
|
||||
### Use cases
|
||||
|
||||
Explain how your change request would work from an author's and user's
|
||||
perspective – what's the expected impact, and why does it benefit not only you
|
||||
perspective – what's the expected impact, and why does it not only benefit you,
|
||||
but other users? How many of them? Furthermore, would it potentially break
|
||||
existing functionality?
|
||||
|
||||
> __Why we need this__: Understanding the use cases and benefits of an idea is
|
||||
> crucial in evaluating its potential impact and usefulness for the project and
|
||||
> its users. This information helps us to understand the expected value of the
|
||||
> __Why we need this__: Understanding the use cases and benefits of an idea is
|
||||
> crucial in evaluating its potential impact and usefulness for the project and
|
||||
> its users. This information helps us to understand the expected value of the
|
||||
> idea and how it aligns with the goals of the project.
|
||||
|
||||
### Visuals <small>optional</small> { #visuals }
|
||||
|
||||
We now have a clear and detailed description of your idea, including information
|
||||
on its potential use cases and relevant links for context. If you have any
|
||||
visuals, such as sketches, screenshots, mockups, or external assets, you may
|
||||
We now have a clear and detailed description of your idea, including information
|
||||
on its potential use cases and relevant links for context. If you have any
|
||||
visuals, such as sketches, screenshots, mockups, or external assets, you may
|
||||
present them in this section.
|
||||
|
||||
__You can drag and drop the files here or include links to external assets.__
|
||||
|
||||
Additionally, if you have seen this change, feature, or improvement used in
|
||||
other static site generators or themes, please provide an example by showcasing
|
||||
Additionally, if you have seen this change, feature, or improvement used in
|
||||
other static site generators or themes, please provide an example by showcasing
|
||||
it and describing how it was implemented and incorporated.
|
||||
|
||||
> __Why we need this__: Illustrations and visuals can help us maintainers
|
||||
> better understand and envision your idea. Screenshots, sketches, or mockups
|
||||
> can create an additional level of detail and clarity that text alone may not
|
||||
> be able to convey. Also, seeing how your idea has been implemented in other
|
||||
> projects can help us understand its potential impact and feasibility in
|
||||
> Material for MkDocs, which helps us maintainers evaluate and triage
|
||||
> change requests.
|
||||
> __Why this might be helpful__: Illustrations and visuals can help us
|
||||
> maintainers better understand and envision your idea. Screenshots, sketches,
|
||||
> or mockups can create an additional level of detail and clarity that text
|
||||
> alone may not be able to convey. Also, seeing how your idea has been
|
||||
> implemented in other projects can help us understand its potential impact and
|
||||
> feasibility in Material for MkDocs, which helps us maintainers evaluate and
|
||||
> triage change requests.
|
||||
|
||||
### Checklist
|
||||
|
||||
Thanks for following the change request guide and creating a high-quality
|
||||
change request. This section ensures that you have read this guide and have
|
||||
worked to the best of your knowledge to provide us with every piece of
|
||||
information to review your idea for Material for MkDocs.
|
||||
Thanks for following the guide and creating a high-quality change request – you
|
||||
are almost done. The checklist ensures that you have read this guide and have
|
||||
worked to your best knowledge to provide us with every piece of information to
|
||||
review your idea for Material for MkDocs.
|
||||
|
||||
__We'll take it from here.__
|
||||
|
||||
---
|
||||
|
||||
## Rejected requests
|
||||
|
||||
__Your change request got rejected? We're sorry for that.__ We understand it can
|
||||
be frustrating when your ideas don't get accepted, but as the maintainers of a
|
||||
very popular project, we always need to consider the needs of our entire
|
||||
community, sometimes forcing us to make tough decisions.
|
||||
|
||||
We always have to consider and balance many factors when evaluating change
|
||||
requests, and we explain the reasoning behind our decisions whenever we can.
|
||||
If you're unsure why your change request was rejected, please don't hesitate
|
||||
to ask for clarification.
|
||||
|
||||
The following principles (in no particular order) form the basis for our
|
||||
decisions:
|
||||
|
||||
- [ ] Alignment with vision and tone of the project
|
||||
- [ ] Compatibility with existing features and plugins
|
||||
- [ ] Compatibility with all screen sizes and browsers
|
||||
- [ ] Effort of implementation and maintenance
|
||||
- [ ] Usefulness to the majority of users
|
||||
- [ ] Simplicity and ease of use
|
||||
- [ ] Accessibility
|
||||
|
||||
But that's not the end of your idea – you can always implement it on your own
|
||||
via [customization]. If you're unsure about how to do that or want to know if
|
||||
someone has already done it, feel free to get in touch with our community on
|
||||
the [discussion board].
|
||||
|
||||
[customization]: ../customization.md
|
||||
|
||||
@ -93,7 +93,7 @@
|
||||
]
|
||||
},
|
||||
"external-community": {
|
||||
"description": "External plugins, schema provided by the community",
|
||||
"description": "External plugins, schema provided by our community",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/schema.json"
|
||||
|
||||
@ -37,9 +37,9 @@ the default slug function works. Consider using a [Unicode-aware slug function].
|
||||
!!! tip "Translations missing? Help us out, it takes only 5 minutes"
|
||||
|
||||
Material for MkDocs relies on outside contributions for adding and updating
|
||||
translations for the almost 60 languages it supports. If your language shows
|
||||
that some translations are missing, click on the link to add them. If your
|
||||
language is not in the list, click here to [add a new language].
|
||||
translations for the more than 60 languages it supports. If your language
|
||||
shows that some translations are missing, click on the link to add them. If
|
||||
your language is not in the list, click here to [add a new language].
|
||||
|
||||
[single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
|
||||
[language selector]: #site-language-selector
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Copyright (c) 2023 Martin Donath <martin.donath@squidfunk.com>
|
||||
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
|
||||
|
||||
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
# of this software and associated documentation files (the "Software"), to
|
||||
|
||||
@ -95,7 +95,7 @@ hooks:
|
||||
- material/overrides/hooks/shortcodes.py
|
||||
- material/overrides/hooks/translations.py
|
||||
|
||||
# Customization
|
||||
# Additional configuration
|
||||
extra:
|
||||
annotate:
|
||||
json: [.s2]
|
||||
@ -105,8 +105,6 @@ extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/squidfunk
|
||||
- icon: fontawesome/brands/gitter
|
||||
link: https://gitter.im/squidfunk/mkdocs-material
|
||||
- icon: fontawesome/brands/docker
|
||||
link: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
- icon: fontawesome/brands/python
|
||||
@ -188,6 +186,7 @@ nav:
|
||||
- Reporting a bug: contributing/reporting-a-bug.md
|
||||
- Reporting a docs issue: contributing/reporting-a-docs-issue.md
|
||||
- Requesting a change: contributing/requesting-a-change.md
|
||||
- Adding translations: contributing/adding-translations.md
|
||||
- Asking a question: https://github.com/squidfunk/mkdocs-material/discussions
|
||||
- Guides:
|
||||
- Creating a reproduction: guides/creating-a-reproduction.md
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Copyright (c) 2023 Martin Donath <martin.donath@squidfunk.com>
|
||||
# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
|
||||
|
||||
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
# of this software and associated documentation files (the "Software"), to
|
||||
|
||||
Loading…
Reference in New Issue
Block a user