# Reporting a docs issue

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.

  [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:

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

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

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

### 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. Maintainers and
    future users will be grateful for having to read less.

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

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

### Related links

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.

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

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

__We'll take it from here.__