Install & Compatibility
Where this runs
tested against v1.6.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
build
✓ from properdocs.commands import build
ProperDocs is primarily a CLI tool. Programmatic usage mirrors MkDocs' internal structure for building documentation.
serve
✓ from properdocs.commands import serve
For starting the development server programmatically.
Initialize a new documentation project, navigate into its directory, and serve it locally to preview changes. Access your documentation at http://127.0.0.1:8000/ by default.
# Create a new ProperDocs project
properdocs new my-docs
# Change into the project directory
cd my-docs
# Start the development server and preview your site
properdocs serve
properdocs --version
Debug
Known issues
breakingProperDocs was forked from MkDocs 1.x. Configuration files now prefer `properdocs.yml` over `mkdocs.yml`, though `mkdocs.yml` is still supported as a fallback. Plugins and themes developed for MkDocs 1.x are generally compatible but ensure no direct `mkdocs` package dependencies.fixRename your configuration file from `mkdocs.yml` to `properdocs.yml`. Ensure `mkdocs` is not a direct dependency in plugins/themes, prefer `properdocs`.
affects: >=1.6.5
breakingThe previously built-in 'mkdocs' and 'readthedocs' themes are no longer included by default to make the package lightweight. Installing ProperDocs alone will result in no default theme, and a warning will be issued if no theme is specified.fixExplicitly install desired themes, e.g., `pip install mkdocs-themes readthedocs-themes`, and specify your theme in `properdocs.yml` (e.g., `theme: mkdocs`).
affects: >=1.6.5
gotchaThe environment variable used to suppress the warning about 'MkDocs 2.0' incompatibilities has changed.fixUpdate `NO_MKDOCS_2_WARNING=true` to `DISABLE_MKDOCS_2_WARNING=true` in your environment or CI/CD pipelines to silence the warning.
affects: >=1.6.7
breakingProperDocs is a continuation of MkDocs 1.x due to concerns about backward-incompatible changes in an anticipated 'MkDocs 2.0'. Relying on `pip install mkdocs` for future projects may lead to unexpected breakages with existing themes, plugins, and configurations.fixSwitch to `pip install properdocs` and use `properdocs build`/`properdocs serve` to ensure continued compatibility with the MkDocs 1.x ecosystem. Consider `properdocs` as the stable path for existing MkDocs setups.
affects: All versions, relative to future MkDocs 2.0
Upgrade
Version history
1.6.7latest on PyPI · released Mar 20, 2026
Audit
Dependencies
clickrequiredCommand-line interface toolkit.
coloramarequiredCross-platform colored terminal text.
ghp-importrequiredFor deploying to GitHub Pages.
importlib-metadatarequiredRead metadata from Python packages.
jinja2requiredTemplating engine for themes.
markdownrequiredMarkdown parsing.
markupsaferequiredString escaping for Jinja2.
packagingrequiredCore utilities for Python package management.
pathspecrequiredUtility library for gitignore-style path matching.
platformdirsrequiredDetermining appropriate platform-specific directories.
pyyamlrequiredYAML parsing for configuration files.
pyyaml-env-tagrequiredYAML environment variable tag support.
watchdogrequiredFile system event monitoring for auto-reloading during `serve`.
babeloptionalInternationalization utilities.
Resources
No resource links recorded.