What happened
During pre-0.4.0 release regression testing, mkdocs build --strict (and mkdocs serve) printed this to stderr on every run:
WARNING: MkDocs may break support for all existing plugins and themes soon!
The owner of MkDocs has completely abandoned maintenance of the project, and instead is planning
to publish a "version 2" which will not support any existing themes, plugins or even your
configuration files. ...
To avoid these risks, switch to *ProperDocs*, a continuation of MkDocs 1.x and a drop-in replacement
that supports your current MkDocs setup. Simply install it with `pip install properdocs` and build
your site with `properdocs build` instead of the MkDocs equivalents.
...
(This warning was initiated by one of the plugins that you depend on.)
What I found
- A separate PyPI package
properdocs (found 1.6.7 in the resolved environment) gets installed transitively and lists itself as Required-by for several of our real dependencies: mkdocs-gen-files, mkdocs-literate-nav, mkdocs-redirects, mkdocs-rss-plugin, mkdocs-section-index.
- The nag is not cosmetic noise from our own theme code — it's a
print() call from properdocs.replacement_warning.setup(), invoked from a try/except ImportError block that these plugins' own __init__.py/plugin.py now carry (verified in mkdocs_redirects/plugin.py).
- It only fires when running from the real
mkdocs executable, and can be silenced with DISABLE_MKDOCS_2_WARNING=true.
- It did not appear when installing the theme into a clean
uv venv for the Python-3.9 smoke test — only in the environment with the full docs plugin stack from requirements-docs.txt.
- Did not install or run
properdocs itself, and did not change any build tooling for this release — all release checks in RELEASING.md still used the documented mkdocs commands.
Why it needs a look (not urgent)
This smells like either a legitimate (if very aggressive) marketing push by a new properdocs fork coordinating with several popular MkDocs plugin maintainers, or a more concerning dependency-confusion/supply-chain move. Either way we should understand it before it affects contributors or CI:
- Is
properdocs a legitimate, maintained fork, or a low-reputation/typosquat-style package?
- Which of our pinned plugin versions first introduced the
properdocs.replacement_warning hook, and is it safe to keep floating on those plugins going forward?
- Should CI pin/avoid the affected plugin versions, or set
DISABLE_MKDOCS_2_WARNING=true explicitly so a future, less benign payload doesn't ship unnoticed?
- Is there any indication of
properdocs doing anything beyond printing the warning (e.g. during pip install)?
Suggested next steps
- Check whether
mkdocs-redirects, mkdocs-gen-files, mkdocs-section-index, mkdocs-literate-nav, mkdocs-rss-plugin changelogs mention this, and since which version.
- Check the
properdocs PyPI page / repo for reputation, maintainers, and download stats.
- Decide whether to pin affected plugins below the version that added the hook, set
DISABLE_MKDOCS_2_WARNING=true in CI/docs, and/or report concerns upstream.
Deliberately filed as post-release follow-up — does not block the 0.4.0 release.
What happened
During pre-0.4.0 release regression testing,
mkdocs build --strict(andmkdocs serve) printed this to stderr on every run:What I found
properdocs(found1.6.7in the resolved environment) gets installed transitively and lists itself asRequired-byfor several of our real dependencies:mkdocs-gen-files,mkdocs-literate-nav,mkdocs-redirects,mkdocs-rss-plugin,mkdocs-section-index.print()call fromproperdocs.replacement_warning.setup(), invoked from atry/except ImportErrorblock that these plugins' own__init__.py/plugin.pynow carry (verified inmkdocs_redirects/plugin.py).mkdocsexecutable, and can be silenced withDISABLE_MKDOCS_2_WARNING=true.uv venvfor the Python-3.9 smoke test — only in the environment with the full docs plugin stack fromrequirements-docs.txt.properdocsitself, and did not change any build tooling for this release — all release checks in RELEASING.md still used the documentedmkdocscommands.Why it needs a look (not urgent)
This smells like either a legitimate (if very aggressive) marketing push by a new
properdocsfork coordinating with several popular MkDocs plugin maintainers, or a more concerning dependency-confusion/supply-chain move. Either way we should understand it before it affects contributors or CI:properdocsa legitimate, maintained fork, or a low-reputation/typosquat-style package?properdocs.replacement_warninghook, and is it safe to keep floating on those plugins going forward?DISABLE_MKDOCS_2_WARNING=trueexplicitly so a future, less benign payload doesn't ship unnoticed?properdocsdoing anything beyond printing the warning (e.g. duringpip install)?Suggested next steps
mkdocs-redirects,mkdocs-gen-files,mkdocs-section-index,mkdocs-literate-nav,mkdocs-rss-pluginchangelogs mention this, and since which version.properdocsPyPI page / repo for reputation, maintainers, and download stats.DISABLE_MKDOCS_2_WARNING=truein CI/docs, and/or report concerns upstream.Deliberately filed as post-release follow-up — does not block the 0.4.0 release.