---
id: properdocs
version: "1.6.7"
license: BSD-2-Clause
license_treatment: permissive
maintenance: active
---

# properdocs — Project documentation with Markdown.

License: permissive · Maintenance: active · Downloads: 2.3M/mo

## What it is and what it does

ProperDocs is a static documentation site generator built for developers who want to write project docs in Markdown and publish them as static HTML. It reads Markdown source files and a YAML configuration file, then generates a complete static website ready to deploy anywhere. The tool is designed around simplicity: one config file, standard Markdown input, and extensibility through themes and plugins rather than complex configuration.

The package depends on common Python tooling libraries—Markdown rendering, YAML parsing, file watching, and CLI handling—to provide a straightforward workflow. It targets the documentation use case specifically, with features like theme support and plugin architecture to customize output without forking the core tool.

Use it for:

- Build and maintain project documentation for open-source or internal software projects using only Markdown and YAML.
- Generate static HTML documentation sites that can be hosted on GitHub Pages, S3, or any static file server.
- Create branded documentation by applying third-party themes or writing custom themes without modifying core code.
- Set up automated documentation builds triggered by changes to Markdown source files using the file-watching capability.
- Extend documentation generation with custom Markdown extensions or plugins to handle project-specific markup needs.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

ProperDocs is a static site generator that converts Markdown documentation into HTML, configured through a single YAML file and extensible with themes and plugins.

Yes. ProperDocs is actively maintained, production-stable, has low install friction, carries no known vulnerabilities, and uses a permissive license. It is well-suited for developers building project documentation from Markdown. Install it if you need a straightforward static documentation generator; verify the plugin ecosystem and programmatic API match your workflow before committing to it for large projects.

## Install

pip install properdocs
uv add properdocs
poetry add properdocs

## Installing properdocs

Before you install: Low install friction with a pure-Python wheel and 13 runtime dependencies that are all standard tooling libraries. Active maintenance with a recent commit on 2026-07-19 and production-stable status.

License in practice: BSD-2-Clause is a permissive license that allows commercial and private use with minimal restrictions, requiring only license and copyright notice preservation.

Quickstart:

pip install properdocs

Create a docs/ folder with Markdown files and a mkdocs.yml config, then:

from properdocs import build
build('docs')

Requires Python 3.9 or later; the exact API for programmatic use should be verified against the package documentation.

Verify before relying:

- Exact programmatic API surface and whether it's intended for CLI-only use or library integration
- Performance characteristics and scalability limits for large documentation projects
- Availability and maturity of third-party themes and plugins in the stated catalog

## Package facts

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown to static html documentation, project documentation generator, static site generator markdown, yaml configured doc builder, markdown docs to website, markdown-to-html, static-site-generator, documentation

[View on SkillFed](https://skillfed.io/packages/properdocs) · [View on PyPI](https://pypi.org/project/properdocs/)