3.3 KiB
Documentation issue reporting
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.
Documentation issue template
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
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 | wrong feature flag code.action |
| :material-close:{ style="color: #EF5350" } Unclear | Missing information |
| :material-close:{ style="color: #EF5350" } Generic | Please 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 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.
-
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: 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.
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. Make sure you link to the sub-pages and anchor the headings directly.
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.
Improvement proposals
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, since it will offer them a temporary solution until we maintainers can update the documentation.
Checklist
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.