2023-09-21 14:53:33 +02:00
# Bug reports
2022-12-31 18:28:19 +01:00
Material for MkDocs is an actively maintained project that we constantly strive
2023-01-01 17:21:59 +01:00
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
2023-04-04 14:58:40 +02:00
public [issue tracker], following this guide.
2022-12-31 18:28:19 +01:00
[issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
## Before creating an issue
2023-01-29 19:14:23 +01:00
With more than 20,000 users, issues are created every other day. The maintainers
2022-12-31 18:28:19 +01:00
of this project are trying very hard to keep the number of open issues down by
2023-01-01 17:21:59 +01:00
fixing bugs as fast as possible. By following this guide, you will know exactly
what information we need to help you quickly.
2022-12-31 18:28:19 +01:00
2023-09-21 14:53:33 +02:00
__But first, please do the following things before creating an issue.__
2022-12-31 18:28:19 +01:00
### Upgrade to latest version
2023-01-02 14:03:01 +01:00
Chances are that the bug you discovered was already fixed in a subsequent
2023-01-01 17:21:59 +01:00
version. Thus, before reporting an issue, ensure that you're running the
2022-12-31 18:28:19 +01:00
[latest version] of Material for MkDocs. Please consult our [upgrade guide] to
learn how to upgrade to the latest version.
!!! warning "Bug fixes are not backported"
2023-01-01 17:21:59 +01:00
Please understand that only bugs that occur in the latest version of
2023-01-02 14:03:01 +01:00
Material for MkDocs will be addressed. Also, to reduce duplicate efforts,
fixes cannot be backported to earlier versions.
2022-12-31 18:28:19 +01:00
### Remove customizations
2023-01-01 17:21:59 +01:00
If you're using [customizations] like [additional CSS], [JavaScript], or
2022-12-31 18:28:19 +01:00
[theme extension], please remove them from `mkdocs.yml` before reporting a bug.
2023-01-01 17:21:59 +01:00
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` :
2022-12-31 18:28:19 +01:00
- [`theme.custom_dir`][theme.custom_dir]
2023-09-21 14:53:33 +02:00
- [`hooks`][hooks]
2022-12-31 18:28:19 +01:00
- [`extra_css`][extra_css]
- [`extra_javascript`][extra_javascript]
2023-01-01 17:21:59 +01:00
If, after removing those settings, the bug is gone, the bug is likely caused by
2022-12-31 18:28:19 +01:00
your customizations. A good idea is to add them back gradually to narrow down
2023-01-01 17:21:59 +01:00
the root cause of the problem. If you did a major version upgrade, make sure you
adjusted all partials you have overridden.
2022-12-31 18:28:19 +01:00
!!! warning "Customizations mentioned in our documentation"
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
2023-04-04 14:58:40 +02:00
our documentation explicitly mentions], you are, of course, encouraged to
2022-12-31 18:28:19 +01:00
report it.
2023-01-01 17:21:59 +01:00
__Don't be shy to ask on our [discussion board] for help if you run into
problems.__
2022-12-31 18:28:19 +01:00
[latest version]: ../changelog/index.md
[upgrade guide]: ../upgrade.md
[Customizations]: ../customization.md
[additional CSS]: ../customization.md#additional-css
[JavaScript]: ../customization.md#additional-javascript
[theme extension]: ../customization.md#extending-the-theme
[theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
2023-09-21 14:53:33 +02:00
[hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
2022-12-31 18:28:19 +01:00
[extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
[extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
2023-04-04 14:58:40 +02:00
[discussion board]: https://github.com/squidfunk/mkdocs-material/issues
2022-12-31 18:28:19 +01:00
[StackOverflow]: https://stackoverflow.com
[that our documentation explicitly mentions]: ?q="extends+base"
### Search for solutions
2023-01-01 17:21:59 +01:00
At this stage, we know that the problem persists in the latest version and is
2023-01-02 14:03:01 +01:00
not caused by any of your customizations. However, the problem might result from
2023-04-04 14:58:40 +02:00
a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml` .
2023-01-01 17:21:59 +01:00
2023-01-02 14:03:01 +01:00
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
another already reported or closed issue or discussion, you can save time for
2023-01-01 17:21:59 +01:00
us and yourself by doing some research:
2023-01-02 14:03:01 +01:00
1. [Search our documentation] and look for the relevant sections that could
be related to your problem. If found, make sure that you configured
2023-01-01 17:21:59 +01:00
everything correctly.[^1]
[^1]:
When adding lines to `mkdocs.yml` , make sure you are preserving the
2023-01-02 14:03:01 +01:00
indentation as mentioned in the documentation since YAML is a
2023-01-01 17:21:59 +01:00
whitespace-sensitive language. Many reported issues turn out to be
configuration errors.
2023-01-02 14:03:01 +01:00
1. [Search our issue tracker][issue tracker], as another user might already
2023-01-01 17:21:59 +01:00
have reported the same problem, and there might even be a known workaround
or fix for it. Thus, no need to create a new issue.
2023-01-02 14:03:01 +01:00
2. [Search our discussion board][discussion board] to learn if other users
are struggling with similar problems and work together with our great
community towards a solution. Many problems are solved here.
2023-01-01 17:21:59 +01:00
__Keep track of all < u > search terms< / u > and < u > relevant links< / u > , you'll need
them in the bug report.__[^2]
2022-12-31 18:28:19 +01:00
2023-01-01 17:21:59 +01:00
[^2]:
We might be using terminology in our documentation different from yours,
2023-04-04 14:58:40 +02:00
but we mean the same. When you include the search terms and related links
2023-01-01 17:21:59 +01:00
in your bug report, you help us to adjust and improve the documentation.
---
At this point, when you still haven't found a solution to your problem, we
2023-01-02 14:03:01 +01:00
encourage you to create an issue because it's now very likely that you
stumbled over something we don't know yet. Read the following section to learn
2023-01-01 17:21:59 +01:00
how to create a complete and helpful bug report.
[Search our documentation]: ?q=
2022-12-31 18:28:19 +01:00
## Issue template
2023-01-29 19:14:23 +01:00
We have created a new issue template to make the bug reporting process as simple
2023-09-21 14:53:33 +02:00
as possible and more efficient for our community and us. It is the result of
2023-01-02 14:03:01 +01:00
our experience answering and fixing more than 1,600 issues (and counting) and
2022-12-31 18:28:19 +01:00
consists of the following parts:
- [Title]
- [Context] < small > optional</ small >
2023-04-04 14:58:40 +02:00
- [Bug description]
2022-12-31 18:28:19 +01:00
- [Related links]
- [Reproduction]
- [Steps to reproduce]
- [Browser] < small > optional</ small >
- [Checklist]
[Title]: #title
[Context]: #context
2023-04-04 14:58:40 +02:00
[Bug description]: #bug -description
2022-12-31 18:28:19 +01:00
[Related links]: #related -links
[Reproduction]: #reproduction
[Steps to reproduce]: #steps -to-reproduce
[Browser]: #browser
[Checklist]: #checklist
### Title
A good title is short and descriptive. It should be a one-sentence executive
summary of the issue, so the impact and severity of the bug you want to report
can be inferred from the title.
| <!-- --> | Example |
2023-09-14 19:09:18 +02:00
| -------- | -------- |
2023-01-01 17:21:59 +01:00
| :material-check:{ style="color: #4DB6AC " } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
2022-12-31 18:28:19 +01:00
| :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
2023-09-21 14:53:33 +02:00
| :material-close:{ style="color: #EF5350 " } __Useless__ | Help
2022-12-31 18:28:19 +01:00
### Context <small>optional</small> { #context }
2023-01-02 14:03:01 +01:00
Before describing the bug, you can provide additional context for us to
2023-04-04 14:58:40 +02:00
understand what you were trying to achieve. Explain the circumstances
2023-01-01 17:21:59 +01:00
in which you're using Material for MkDocs, and what you _think_ might be
relevant. Don't write about the bug here.
2022-12-31 18:28:19 +01:00
> __Why this might be helpful__: some errors only manifest in specific settings,
2023-01-02 14:03:01 +01:00
> environments or edge cases, for example, when your documentation contains
2022-12-31 18:28:19 +01:00
> thousands of documents.
2023-04-04 14:58:40 +02:00
### Bug description
2022-12-31 18:28:19 +01:00
2023-04-04 14:58:40 +02:00
Now, to the bug you want to report. Provide a clear, focused, specific, and
2022-12-31 18:28:19 +01:00
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
2023-01-01 17:35:34 +01:00
dependencies.[^3] Adhere to the following principles:
[^3]:
Sometimes, users report bugs on our [issue tracker] that are caused by one
of our upstream dependencies, including [MkDocs], [Python Markdown],
[Python Markdown Extensions] or third-party plugins. A good rule of thumb is
2023-01-02 14:03:01 +01:00
to change the [`theme.name`][theme.name] to `mkdocs` or `readthedocs` and
2023-01-01 17:35:34 +01:00
check if the problem persists. If it does, the problem is likely not
related to Material for MkDocs and should be reported upstream. When in
doubt, use our [discussion board] to ask for help.
2022-12-31 18:28:19 +01:00
- __Explain the <u>what</u>, not the <u>how</u>__ – don't explain
[how to reproduce the bug][Steps to reproduce] here, we're getting there.
Focus on articulating the problem and its impact as clearly as possible.
- __Keep it short and concise__ – if the bug can be precisely explained in one
2023-01-01 17:21:59 +01:00
or two sentences, perfect. Don't inflate it – maintainers and future users
2023-01-02 14:03:01 +01:00
will be grateful for having to read less.
2022-12-31 18:28:19 +01:00
2023-04-04 14:58:40 +02:00
- __One bug at a time__ – if you encounter several unrelated bugs, please
2023-01-01 17:21:59 +01:00
create separate issues for them. Don't report them in the same issue, as
this makes attribution difficult.
2022-12-31 18:28:19 +01:00
---
2023-01-01 17:21:59 +01:00
:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix
2023-01-02 14:03:01 +01:00
the bug, you can help other users temporarily mitigate the problem before
2023-01-01 17:21:59 +01:00
we maintainers can fix the bug in our code base.
2022-12-31 18:28:19 +01:00
2023-01-02 14:03:01 +01:00
> __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
2022-12-31 18:28:19 +01:00
> for triage and prioritization.
2023-01-01 17:35:34 +01:00
[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
2022-12-31 18:28:19 +01:00
### Related links
2023-01-01 17:21:59 +01:00
Of course, prior to reporting a bug, you have read our documentation and
[could not find a working solution][search for solutions]. Please share links
to all sections of our documentation that might be relevant to the bug, as it
helps us gradually improve it.
2022-12-31 18:28:19 +01:00
Additionally, since you have searched our [issue tracker] and [discussion board]
before reporting an issue, and have possibly found several issues or
discussions, include those as well. Every link to an issue or discussion creates
2023-01-01 17:21:59 +01:00
a backlink, guiding us maintainers and other users in the future.
---
:material-run-fast: __Stretch goal__ – if you also include the search terms you
used when [searching for a solution][search for solutions] to your problem, you
make it easier for us maintainers to improve the documentation.
2022-12-31 18:28:19 +01:00
> __Why we need this__: related links help us better understand what you were
> trying to achieve and whether sections of our documentation need to be
2023-01-02 14:03:01 +01:00
> adjusted, extended, or overhauled.
2022-12-31 18:28:19 +01:00
2023-01-01 17:21:59 +01:00
[search for solutions]: #search -for-solutions
2022-12-31 18:28:19 +01:00
### Reproduction
2023-01-01 17:21:59 +01:00
A minimal reproduction is at the heart of every well-written bug report, as
2023-09-14 19:09:18 +02:00
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.
2023-01-01 17:21:59 +01:00
2023-04-04 14:58:40 +02:00
[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
2023-01-01 17:21:59 +01:00
---
2023-09-14 19:09:18 +02:00
After you have created the reproduction, you should have a `.zip` file, ideally
not larger than 1 MB. Just drag and drop the `.zip` file into this field, which
will automatically upload it to GitHub.
2023-01-01 17:21:59 +01:00
2023-04-04 14:58:40 +02:00
> __Why we need this__: if an issue contains no minimal reproduction or just
2023-01-02 14:03:01 +01:00
> 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
2023-01-01 17:21:59 +01:00
> inspect the bug, let alone fix it.
!!! warning "Don't share links to repositories"
2023-01-02 14:03:01 +01:00
While we know that it is a good practice among developers to include a link
2023-01-01 17:21:59 +01:00
to a repository with the bug report, we currently don't support those in our
2023-04-04 14:58:40 +02:00
process. The reason is that the reproduction, which is automatically
2023-01-01 17:21:59 +01:00
produced by the [built-in info plugin] contains all of the necessary
environment information that is often forgotten to be included.
2023-09-14 19:09:18 +02:00
2023-01-01 17:21:59 +01:00
Additionally, there are many non-technical users of Material for MkDocs that
have trouble creating repositories.
2023-01-29 19:14:23 +01:00
[Create reproduction]: ../guides/creating-a-reproduction.md
2023-09-21 14:53:33 +02:00
[built-in info plugin]: ../plugins/info.md
2022-12-31 18:28:19 +01:00
### Steps to reproduce
2023-04-04 14:58:40 +02:00
At this point, you provided us with enough information to understand the bug
2023-09-21 14:53:33 +02:00
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
2023-01-01 17:21:59 +01:00
the bug in action.
2023-09-21 14:53:33 +02:00
Thus, please list the specific steps we should follow when running your
2023-01-02 14:03:01 +01:00
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
2023-04-04 14:58:40 +02:00
five-year-old, and focus on continuity.
2023-01-01 17:21:59 +01:00
> __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
> specific conditions.
2022-12-31 18:28:19 +01:00
### Browser <small>optional</small> { #browser }
2023-04-04 14:58:40 +02:00
If you're reporting a bug that only occurs in one or more _specific_ browsers,
2023-01-01 17:21:59 +01:00
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.
2022-12-31 18:28:19 +01:00
2023-09-21 14:53:33 +02:00
---
: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.
2022-12-31 18:28:19 +01:00
2023-01-01 17:21:59 +01:00
> __Why we need this__: some bugs only occur in specific browsers or versions.
2023-01-02 14:03:01 +01:00
> Since now, almost all browsers are evergreen, we usually don't need to know the
2023-01-01 17:21:59 +01:00
> version in which it occurs, but we might ask for it later. When in doubt, add
> the browser version as the first step in the field above.
2022-12-31 18:28:19 +01:00
2023-01-01 17:21:59 +01:00
[previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write
[building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site
2022-12-31 18:28:19 +01:00
2023-01-01 17:21:59 +01:00
### Checklist
2022-12-31 18:28:19 +01:00
2023-01-02 14:03:01 +01:00
Thanks for following the guide and creating a high-quality and complete bug
2023-04-04 14:58:40 +02:00
report – you are almost done. The checklist ensures that you have read this guide
2023-01-01 17:21:59 +01:00
and have worked to your best knowledge to provide us with everything we need to
know to help you.
2022-12-31 18:28:19 +01:00
2023-01-01 17:21:59 +01:00
__We'll take it from here.__