14 KiB
Bug reporting
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, following this guide.
Before creating an issue
With more than 20.000 users, issues are created every other day. The maintainers 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.
Upgrade to latest version
Chances are that the bug you discovered was already fixed in a subsequent version. Thus, before reporting an issue, ensure that you're running the 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"
Please understand that only bugs that occur in the latest version of
Material for MkDocs will be addressed. Also, to reduce duplicate efforts,
fixes cannot be backported to earlier versions.
Remove customizations
If you're using customizations like additional CSS, JavaScript, or
theme extension, please remove them from mkdocs.yml before reporting a bug.
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:
If, after removing those settings, the bug is gone, the bug is likely caused by your customizations. A good idea is to add them back gradually to narrow down the root cause of the problem. If you did a major version upgrade, make sure you adjusted all partials you have overridden.
!!! 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
our documentation explicitly mentions], you are of course encouraged to
report it.
Don't be shy to ask on our discussion board for help if you run into problems.
Search for solutions
At this stage, we know that the problem persists in the latest version and is
not caused by any of your customizations. However, the problem might result from
a small typo or a syntactical error in a configuration file, e.g. mkdocs.yml.
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 us and yourself by doing some research:
- Search our documentation and look for the relevant sections that could be related to your problem. If found, make sure that you configured everything correctly.1
-
Search our issue tracker, as another user might already 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.
-
Search our 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.
Keep track of all search terms and relevant links, you'll need them in the bug report.2
At this point, when you still haven't found a solution to your problem, we 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 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 our experience answering and fixing more than 1,600 issues (and counting) and consists of the following parts:
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 | |
|---|---|
| :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 |
Context optional
Before describing the bug, you can provide additional context for us to 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.
Why this might be helpful: some errors only manifest in specific settings, environments or edge cases, for example, when your documentation contains thousands of documents.
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 that should be reported to Material for MkDocs, and not to one of its dependencies.3 Adhere to the following principles:
-
Explain the what, not the how – don't explain how to reproduce the bug 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 or two sentences, perfect. Don't inflate it – maintainers and future users will be grateful for having to read less.
-
One bug at a time – if you encountered several unrelated bugs, please create separate issues for them. Don't report them in the same issue, as this makes attribution difficult.
:material-run-fast: Stretch goal – if you found a workaround or a way to fix the bug, you can help other users temporarily mitigate the problem before we maintainers can fix the bug in our code base.
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
Of course, prior to reporting a bug, you have read our documentation and could not find a working solution. Please share links to all sections of our documentation that might be relevant to the bug, as it helps us gradually improve it.
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 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 to your problem, you make it easier for us maintainers to improve the documentation.
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 adjusted, extended, or overhauled.
Reproduction
A minimal reproduction is at the heart of every well-written bug report, as it allows us maintainers to quickly recreate the necessary conditions to inspect the bug and 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 reproduction{ .md-button .md-button--primary }
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.
Why we need this: if an issue contains no minimal reproduction, or just 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 inspect the bug, let alone fix it.
!!! warning "Don't share links to repositories"
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
produced by the [built-in info plugin] contains all of the necessary
environment information that is often forgotten to be included.
Additionally, there are many non-technical users of Material for MkDocs that
have trouble creating repositories.
Steps to reproduce
At this point, you provided us with enough information to understand the bug, and you gave us a reproduction that we can 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 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.
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.
Browser optional
If you're reporting a bug that only happens 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.
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 the browser version as the first step in the field above.
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 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.
-
When adding lines to
mkdocs.yml, make sure you are preserving the indentation as mentioned in the documentation since YAML is a whitespace-sensitive language. Many reported issues turn out to be configuration errors. ↩︎ -
We might be using terminology in our documentation different from yours, but 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. ↩︎
-
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 to change the
theme.nametomkdocsorreadthedocsand 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. ↩︎