ProperDocs

ProperDocs is a static site generator for project documentation and a drop-in replacement for MkDocs. It converts Markdown source files into a fast, static HTML site during a build step, which you can deploy to any web host such as GitHub Pages. Project structure, theming, and plugins are configured through a single YAML file.

ProperDocs was created as a community-maintained fork after MkDocs development stalled, aiming for full compatibility with existing MkDocs projects while continuing bug fixes and incremental improvements.

What You Get

• A CLI to build and locally preview a documentation site from Markdown sources
• Drop-in compatibility with existing MkDocs projects, themes, and plugins
• A YAML-driven configuration for navigation, theming, and plugin settings
• A live-reloading development server for previewing docs as you write
• An extensible architecture supporting plugins, themes, and Python-Markdown extensions

Common Use Cases

• Publishing project and API documentation as a static site on GitHub Pages
• Migrating an abandoned MkDocs setup to a maintained drop-in replacement
• Authoring internal knowledge bases and handbooks in Markdown

Under The Hood

Architecture

ProperDocs is structured as a CLI application built on Click that dispatches build, serve, and new commands. The build pipeline loads and validates the YAML config, resolves the navigation tree, converts each Markdown page through Python-Markdown, and renders it against a Jinja2 theme template. A plugin system exposes lifecycle events that let extensions transform config, pages, and output, while the serve command wraps the build in a watchdog-based live-reload HTTP server.

Tech Stack

Python (fork of MkDocs) packaged via setup.py and pyproject.toml. Core dependencies include Click for the CLI, Jinja2 for templating, Python-Markdown for content conversion, PyYAML for configuration, and watchdog for the development server’s file watching. It ships bundled default themes and organizes optional components under a packages/ directory.

Code Quality

As a mature fork of a long-lived project, the codebase carries an established test suite under properdocs/tests spanning configuration parsing, navigation building, and rendering. It follows the upstream project’s conventions and modular structure, and the fork’s stated goal of avoiding breaking changes keeps behavior predictable and well-covered.

API Design

Developer experience mirrors MkDocs’ well-known ergonomics: a short YAML file plus a couple of CLI commands get a site running, and migration requires no code changes. Documentation lives at properdocs.org and inherits MkDocs’ extensive guides, making the learning curve gentle for anyone who has used a static site generator.