Skip to content

Investigate properdocs replacement-warning nag pulled in by mkdocs plugins #94

Description

@olegshulyakov

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

  1. Check whether mkdocs-redirects, mkdocs-gen-files, mkdocs-section-index, mkdocs-literate-nav, mkdocs-rss-plugin changelogs mention this, and since which version.
  2. Check the properdocs PyPI page / repo for reputation, maintainers, and download stats.
  3. 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.

Activity

  1. added
    securitySecurity updates
    P3Low - cosmetic, cleanup, or nice-to-have improvement
    on Sep 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low - cosmetic, cleanup, or nice-to-have improvementsecuritySecurity updates

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions