{"id":14823,"library":"properdocs","title":"ProperDocs","description":"ProperDocs is a fast, simple, and extensible static site generator geared towards building project documentation using Markdown source files and a single YAML configuration file. It is a direct continuation of MkDocs 1.x, aiming for full compatibility with existing MkDocs themes and plugins while addressing maintenance concerns of the original project. The current version is 1.6.7, with an active release cadence.","status":"active","version":"1.6.7","language":"en","source_language":"en","source_url":"https://github.com/properdocs/properdocs","tags":["documentation","markdown","static site generator","mkdocs","cli"],"install":[{"cmd":"pip install properdocs","lang":"bash","label":"Install ProperDocs"},{"cmd":"pip install properdocs mkdocs-themes readthedocs-themes","lang":"bash","label":"Install with common themes (recommended)"}],"dependencies":[{"reason":"Command-line interface toolkit.","package":"click"},{"reason":"Cross-platform colored terminal text.","package":"colorama"},{"reason":"For deploying to GitHub Pages.","package":"ghp-import"},{"reason":"Read metadata from Python packages.","package":"importlib-metadata"},{"reason":"Templating engine for themes.","package":"jinja2"},{"reason":"Markdown parsing.","package":"markdown"},{"reason":"String escaping for Jinja2.","package":"markupsafe"},{"reason":"Core utilities for Python package management.","package":"packaging"},{"reason":"Utility library for gitignore-style path matching.","package":"pathspec"},{"reason":"Determining appropriate platform-specific directories.","package":"platformdirs"},{"reason":"YAML parsing for configuration files.","package":"pyyaml"},{"reason":"YAML environment variable tag support.","package":"pyyaml-env-tag"},{"reason":"File system event monitoring for auto-reloading during `serve`.","package":"watchdog"},{"reason":"Internationalization utilities.","package":"babel","optional":true}],"imports":[{"note":"ProperDocs is primarily a CLI tool. Programmatic usage mirrors MkDocs' internal structure for building documentation.","symbol":"build","correct":"from properdocs.commands import build"},{"note":"For starting the development server programmatically.","symbol":"serve","correct":"from properdocs.commands import serve"}],"quickstart":{"code":"# Create a new ProperDocs project\nproperdocs new my-docs\n\n# Change into the project directory\ncd my-docs\n\n# Start the development server and preview your site\nproperdocs serve","lang":"bash","description":"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."},"warnings":[{"fix":"Rename your configuration file from `mkdocs.yml` to `properdocs.yml`. Ensure `mkdocs` is not a direct dependency in plugins/themes, prefer `properdocs`.","message":"ProperDocs 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.","severity":"breaking","affected_versions":">=1.6.5"},{"fix":"Explicitly install desired themes, e.g., `pip install mkdocs-themes readthedocs-themes`, and specify your theme in `properdocs.yml` (e.g., `theme: mkdocs`).","message":"The 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.","severity":"breaking","affected_versions":">=1.6.5"},{"fix":"Update `NO_MKDOCS_2_WARNING=true` to `DISABLE_MKDOCS_2_WARNING=true` in your environment or CI/CD pipelines to silence the warning.","message":"The environment variable used to suppress the warning about 'MkDocs 2.0' incompatibilities has changed.","severity":"gotcha","affected_versions":">=1.6.7"},{"fix":"Switch 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.","message":"ProperDocs 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.","severity":"breaking","affected_versions":"All versions, relative to future MkDocs 2.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[],"ecosystem":"pypi"}