mkdocs-material/docs/contributing/reporting-a-docs-issue.md

# 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.

  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues

## 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.__