ProperDocs

1.6.7 · active · verified Tue Apr 14

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.

Warnings

breaking 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.
Fix: Rename your configuration file from `mkdocs.yml` to `properdocs.yml`. Ensure `mkdocs` is not a direct dependency in plugins/themes, prefer `properdocs`.
breaking 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.
Fix: Explicitly install desired themes, e.g., `pip install mkdocs-themes readthedocs-themes`, and specify your theme in `properdocs.yml` (e.g., `theme: mkdocs`).
gotcha The environment variable used to suppress the warning about 'MkDocs 2.0' incompatibilities has changed.
Fix: Update `NO_MKDOCS_2_WARNING=true` to `DISABLE_MKDOCS_2_WARNING=true` in your environment or CI/CD pipelines to silence the warning.
breaking 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.
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.

Install

pip install properdocs Install ProperDocs
pip install properdocs mkdocs-themes readthedocs-themes Install with common themes (recommended)

Imports

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.

Quickstart

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

view raw JSON →