Upstream Issues Fixed in MkDocs NG
MkDocs NG is a maintained fork of mkdocs/mkdocs, which is no longer under
active development. Beyond keeping up with new Python releases and
dependencies, the fork resolves long-standing issues that were reported
upstream but never fixed there.
This page tracks notable upstream issues that are already resolved in MkDocs
NG. If you are affected by one of them, upgrading is a one-line change — the
package name on PyPI is mkdocs-ng, while the mkdocs command and all
configuration stay the same:
Configuration
| Upstream issue |
Symptom |
Fixed in |
| #2624 |
INHERIT accepted a single parent file, so splitting a configuration into several files required chaining them one after another. It now accepts a list of files. |
1.9.0 (#107) |
Development server
| Upstream issue |
Symptom |
Fixed in |
| #4032, #4014, #4055, #4081 |
With click>=8.2, mkdocs serve stopped watching for file changes, live reload only worked when --livereload was passed explicitly (often misdiagnosed as a WSL problem), and use_directory_urls was overridden. |
1.7.0 (#4), 1.7.3 (#60) |
| #2519 |
Editor temporary files (vim swap files, ~ backups, Emacs auto-save) triggered pointless rebuilds. |
1.7.3 (#55) |
| #3496 |
mkdocs serve failed when port 8000 was already in use, for example by another mkdocs serve. It now serves on the next free port (up to 8010) and says so. |
1.11.0 |
| #4001 |
Edge-case markup such as <<>> crashed the build with AssertionError from Python's html.parser (seen on Python 3.13.5+). |
1.7.3 (#51) |
Built-in themes
| Upstream issue |
Symptom |
Fixed in |
| #2171 |
Built-in themes loaded resources from CDNs, sharing visitor data with third parties and breaking offline use. highlight.js is now bundled locally and the themes contain no CDN references. |
1.8.0 (#75) |
| #3630 |
The long-dead Universal Analytics (analytics.js) snippet was hardcoded into the themes. It is removed; use analytics.gtag (GA4) or override the analytics template block. |
1.8.0 (#84) |
| #4045 |
Disabling highlightjs broke switching between light and dark mode in the mkdocs theme. |
1.7.1 (#39) |
Markdown
| Upstream issue |
Symptom |
Fixed in |
| #3772 |
Loading your own Markdown extension from the project needed PYTHONPATH set by hand or a package to install. The new markdown_extensions_path setting names directories to load them from. |
1.11.0 |
| #3914 |
Links to other sites couldn't be told apart from internal links in the HTML, so themes couldn't mark them. They now get rel="external". |
1.11.0 |
| #3997 |
GitHub-style alerts (> [!NOTE], > [!WARNING] and so on) showed up as a quote starting with [!NOTE]. They now render as admonitions. |
1.11.0 |
Search
| Upstream issue |
Symptom |
Fixed in |
| #4167 |
Searching for words that happen to be English stop words — while, if, for, from and many more — returned no results, even though they are meaningful keywords in technical documentation. Stop words are now indexed by default; a stop_words plugin option restores the old behavior. |
1.8.0 (#80) |
| #4106 |
In browsers without Web Worker support, search replaced the page's global window.postMessage function, breaking other scripts that rely on it. The fallback now leaves it alone (and no longer depends on jQuery or on the site being served from the domain root). |
1.9.0 (#106) |
Navigation
| Upstream issue |
Symptom |
Fixed in |
| #3450 |
The project's root directory couldn't be the docs_dir, so a small project couldn't keep its Markdown files next to mkdocs.yml. docs_dir: . now works; the config file and the site_dir are left out of the site. |
1.11.0 |
| #3710 |
When the same page was listed more than once in nav under different titles, every entry showed the title of the first one. Each entry now keeps its own title. |
1.9.0 (#103) |
| #4026 |
A nav entry that links to a section of a page (page.md#anchor or page/#anchor) was reported as "not found in the documentation files", failing strict builds; the page.md#anchor form also produced a broken link. Both forms now work without a warning. |
1.9.0 (#104) |
Validation
| Upstream issue |
Symptom |
Fixed in |
| #3690 |
Anchor validation reported false positives for anchors generated late by Markdown extensions, e.g. pymdownx.tabbed with combine_header_slug. |
1.7.1 (#34) |
| #3696 |
Using a deprecated configuration option — including deprecated options of plugins — emitted a WARNING, so strict builds failed although the option still worked or was harmless. Deprecation notices are now logged at INFO level. |
1.9.0 (#102) |
| #3703 |
The "does not contain an anchor" warning gave no hint when the only problem was letter case; it now suggests the correct anchor (did you mean '#conflicts'?). |
1.8.0 (#83) |
| #3952 |
Links with a text fragment (page.md#:~:text=some%20words) were reported as pointing to a missing anchor. The text fragment is now ignored; only an anchor before it is checked. |
1.11.0 |
| #4126 |
mkdocs build --quiet --strict exited successfully even when there were warnings, because --quiet stopped warnings from being counted. Warnings are now still counted in strict mode; only their output is silenced. |
1.9.0 (#101) |
Plugins
| Upstream issue |
Symptom |
Fixed in |
| #3709 |
on_page_context got no access to the Jinja environment that renders the page, so plugins couldn't add filters or globals for one page. Handlers that take an env keyword now receive it; others are called as before. |
1.11.0 |
Python API
| Upstream issue |
Symptom |
Fixed in |
| #1240 |
No stable programmatic API — running MkDocs from Python code required subprocess calls or private imports. MkDocs NG provides mkdocs.build() and mkdocs.serve(). |
1.8.0 (#76) |
Output for LLMs
| Upstream issue |
Symptom |
Fixed in |
| #3973 |
No way to publish the documentation's Markdown for LLMs and coding agents; converting the HTML back to Markdown loses precision. The built-in llms_txt plugin publishes each page's Markdown and an llms.txt index. |
1.9.0 (#105) |
Also worth knowing
- Python 3.13, 3.14, and 3.15 are fully supported and tested, while
upstream's last release predates them.
- Found another upstream issue you'd like to see fixed here? Please
open an issue.
