ProperDocs is a static site generator built specifically for project documentation. The sources are plain Markdown files, a single YAML file (properdocs.yml) holds the configuration and the navigation, and one command renders the result to static HTML. It fits a README that has outgrown itself: an API reference, a user guide, an internal handbook or a product manual that you want to keep in git next to the code and publish as a fast, self-contained site.

Authoring and building

• Content lives in Markdown files; the page order, navigation and theme are declared in one YAML configuration file.
• A small command set: properdocs new scaffolds a project, properdocs serve runs a live development server, properdocs build writes the HTML, properdocs gh-deploy publishes to GitHub Pages and properdocs get-deps reports the PyPI packages your configured plugins need.
• The built-in development server reloads the site and the browser whenever a file changes, so you write Markdown and watch the rendered page.
• Strict mode (--strict) aborts a build on any warning, which makes broken internal links and malformed pages fail a pipeline instead of shipping.
• --clean and --dirty control whether the output directory is wiped between builds; --use-directory-urls switches between clean URLs and page.html paths.

Themes, plugins and extensions

• Two official themes, mkdocs and readthedocs, plus third-party themes and plugins catalogued in the ProperDocs Catalog.
• Themes can be customised and localised; a theme inherits its parent theme’s translations and can override any of them.
• Markdown extensions and plugins extend what the renderer understands, and are enabled from the same configuration file.
• The standard theme renders a site-wide search box in the header, alongside previous/next page links, a light/dark/auto theme switch and an “edit this page” link to the source repository.

Deployment

• Output is completely static HTML, hostable on GitHub Pages, Amazon S3 or any web server; the docs site for the project’s own documentation is built with it.
• Distributed as a Python package on PyPI (the published release declares Python 3.9 or newer) and installed with pip, so it runs on Linux, macOS and Windows.
• Actively developed, BSD-2-Clause licensed, with source and issue tracker on GitHub.

Alternatives

• Docusaurus — a React-based documentation site generator with versioned docs and a blog.
• Raneto — a Markdown knowledge base that serves pages straight from files on disk.