On this page

Switching to MkDocs NG

Move an existing MkDocs site to MkDocs NG.

MkDocs NG is a maintained fork of MkDocs 1.x. It keeps the mkdocs command, mkdocs.yml, the plugin and theme APIs and import mkdocs, so switching is a package change, not a migration of your site. Your Markdown, configuration, plugins and themes stay as they are, and switching back is the same one-line change.

Try it first

To see whether your site builds with MkDocs NG before you change anything, run it once with uv. uvx installs MkDocs NG and your requirements into a throwaway environment and leaves your own environment and files alone:

uvx --from mkdocs-ng --with-requirements requirements.txt mkdocs build --strict

Point --with-requirements at the file that lists your plugins and themes, or name them with --with, for example uvx --from mkdocs-ng --with mkdocs-material mkdocs build --strict. Without them, the build fails on the first plugin or theme it can't find.

Switch

Install MkDocs NG into the environment you build your site in. You don't need to uninstall mkdocs first:
```
pip install -U mkdocs-ng
```
With uv: uv pip install -U mkdocs-ng, or uv add mkdocs-ng in a uv project.

Check that the mkdocs command now runs MkDocs NG. The path ends in mkdocs_ng/mkdocs:

$ mkdocs --version
mkdocs, version 1.10.0 from /path/to/site-packages/mkdocs_ng/mkdocs (Python 3.12)

Build your site as usual, ideally with --strict so that anything that changed shows up as an error:
```
mkdocs build --strict
```
Replace mkdocs with mkdocs-ng wherever your dependencies are listed, so CI and other machines install it too. See Updating your dependencies.

That's it. Commands such as mkdocs serve and mkdocs gh-deploy work as before.

Note

MkDocs NG 1.10.0 and newer install alongside upstream MkDocs. With MkDocs NG 1.9 and earlier, run pip uninstall mkdocs before installing it, and again after installing a plugin or theme. Upgrading to 1.10.0 fixes that, even in an environment where upstream MkDocs had already overwritten MkDocs NG.

Updating your dependencies

Plugins and themes, including Material for MkDocs, depend on the mkdocs package, so upstream MkDocs keeps getting installed next to MkDocs NG. That's expected: MkDocs NG always takes precedence, whatever the install order. Leave the upstream package installed, and list mkdocs-ng instead of mkdocs:

In requirements.txt:

mkdocs-ng
mkdocs-material

In pyproject.toml, in [project] or in a dependency group:

[project]
dependencies = ["mkdocs-ng", "mkdocs-material"]

[dependency-groups]
docs = ["mkdocs-ng", "mkdocs-material"]

With pipx, replace the app and inject your plugins and themes:

pipx uninstall mkdocs
pipx install mkdocs-ng
pipx inject mkdocs-ng mkdocs-material

With Poetry, swap the package in the group that lists it:

poetry remove --group docs mkdocs
poetry add --group docs mkdocs-ng

On Read the Docs, nothing changes in .readthedocs.yaml. Its python.install step installs the requirements file you updated above.

In a GitHub Actions workflow, or any CI script, change the package name in the install step:

- run: pip install mkdocs-ng mkdocs-material

To pin a version, pin mkdocs-ng, for example mkdocs-ng>=1.10,<2.

In a uv project you can keep upstream MkDocs from being installed at all. See Keeping upstream MkDocs out.

What changes

Nothing in your configuration needs to change. A few fixes since upstream MkDocs 1.6.1 change behavior in ways you might notice:

Python 3.10 or newer is required. Upstream MkDocs 1.6.1 supports Python 3.8 and 3.9 as well.
mkdocs build --quiet --strict fails when there are warnings. Upstream, --quiet stopped warnings from being counted, so such builds passed with broken links. Run without --quiet to see the warnings.
Deprecated options no longer fail strict builds. Their notices are logged at INFO level instead of WARNING. Removed options are still errors.
Built-in search indexes English stop words such as while, if and for, so searching for them finds results. Set the search plugin's stop_words: true for the old behavior.
The built-in themes load nothing from CDNs and no longer include the Universal Analytics (analytics.js) snippet, as Google shut that service down in 2023. The deprecated google_analytics option has no effect; use the theme's analytics.gtag option instead.
Plugins don't print the "switch to ProperDocs" warning. Plugins such as mkdocs-redirects and mkdocs-gen-files print it when run by the mkdocs command. MkDocs NG sets DISABLE_MKDOCS_2_WARNING=true unless you have set it yourself.

The release notes list every change, and Fixed Upstream Issues lists the upstream bugs that are fixed.

Plugins and themes

Plugins and themes written for MkDocs 1.x work unchanged: MkDocs NG provides the same plugin events, configuration classes and theme templates. Every change to MkDocs NG is tested by building sites with these popular plugins, themes and Markdown extensions, installed the way users install them, and the test runs again every week to catch new plugin releases:

markdown-exec, mike, mkdocs-autorefs, mkdocs-awesome-nav, mkdocs-awesome-pages-plugin, mkdocs-bibtex, mkdocs-cinder, mkdocs-click, mkdocs-encryptcontent-plugin, mkdocs-gen-files, mkdocs-git-authors-plugin, mkdocs-git-revision-date-localized-plugin, mkdocs-glightbox, mkdocs-include-markdown-plugin, mkdocs-jupyter, mkdocs-kroki-plugin, mkdocs-literate-nav, mkdocs-macros-plugin, mkdocs-markdownextradata-plugin, mkdocs-material, mkdocs-mermaid2-plugin, mkdocs-minify-plugin, mkdocs-monorepo-plugin, mkdocs-redirects, mkdocs-rss-plugin, mkdocs-static-i18n, mkdocs-swagger-ui-tag, mkdocs-techdocs-core, mkdocstrings-python, neoteroi-mkdocs, plantuml-markdown, pymdown-extensions.

The plugin catalog marks every project in this test. If a plugin or theme that works with upstream MkDocs fails with MkDocs NG, please open an issue.

Material for MkDocs

Material for MkDocs works with MkDocs NG and is part of the tests above. Its maintainers have announced that it reaches end of life on 2027-05-05, and it prints a notice saying so on every build. When you want to move on, Sumi is the theme made for MkDocs NG. It reads most Material configuration and content as-is, and its migration guide lists what carries over.

Coming from ProperDocs

ProperDocs is another fork of MkDocs 1.6 with its own properdocs command, which reads properdocs.yml and falls back to mkdocs.yml. To switch, install MkDocs NG, rename properdocs.yml to mkdocs.yml if you have one, and run mkdocs instead of properdocs. Plugins that moved to ProperDocs, such as mkdocs-redirects and mkdocs-gen-files, keep working with MkDocs NG and are part of its compatibility tests.

Coming from MkDocs 2.0 pre-releases

The upstream MkDocs 2.0 pre-releases (pip install --pre mkdocs) are a rewrite. As of 2.0.dev6 they don't read mkdocs.yml, refuse to run when one exists, and don't support plugins or themes. If one got installed, for example by pip install --pre or uv --prerelease allow, install MkDocs NG 1.10.0 or newer and the mkdocs command runs MkDocs NG again. To remove the pre-release, pin mkdocs<2 next to mkdocs-ng.

Switching back

To go back to upstream MkDocs, uninstall MkDocs NG and reinstall upstream MkDocs, which restores its mkdocs command:

pip uninstall mkdocs-ng
pip install --force-reinstall --no-deps mkdocs

Your site needs no changes, unless you started using features that upstream MkDocs doesn't have, such as the llms_txt plugin or a list of files in INHERIT.