A pure-Python static site generator for polished documentation sites — strong typography, left sidebar navigation, right table of contents, client-side full-text search, and live reload in dev mode.
- Python-only runtime — no Node or frontend build step
- TOML-based configuration — single
site.tomlcontrols everything - YAML navigation — explicit sidebar order, nested groups, top-bar links
- Front matter — YAML (
---) or TOML (+++) blocks for title, summary, draft, order, and template overrides - Pymdown-powered Markdown — Python-Markdown plus
pymdown-extensionsfor richer Markdown behavior - Syntax highlighting — Pygments-powered fenced code blocks
- Table of contents — auto-generated per page, scroll-synced right panel
- Client-side search — full-text index baked into each page at build time
- Live reload dev server — watches content and config files, pushes reload via polling
- GitHub Pages deploy — one command builds and force-pushes to
gh-pages - Theme overrides — drop custom CSS/JS or a full HTML template into
theme/
pip install static-docsgit clone https://github.com/Dev-kitx/static-docs.git
cd static-docs
uv sync --locked --extra devThe project uses uv.lock for repeatable contributor and CI installs. The static-docs command is available through uv run static-docs.
# 1. Scaffold a new project
static-docs init my-docs
# 2. Preview with live reload
static-docs preview --config my-docs/site.toml
# 3. Build for production
static-docs build --config my-docs/site.tomlThe scaffolded directory contains:
my-docs/
├── site.toml # site-wide config
├── navigation.yml # sidebar + top-bar nav
└── content/
└── index.md # home page
This repository includes a full Static Docs documentation site under docs/.
static-docs build --config docs/site.tomlThe docs source explains configuration, authoring, components, API docs generation, search, SEO, LLM files, and GitHub Actions deployment.
All commands follow the pattern:
static-docs <command> [options]
Scaffold a new project directory.
static-docs init [path]| Argument | Default | Description |
|---|---|---|
path |
. |
Directory to initialise. Created if it does not exist. |
Build the site to output_dir (configured in site.toml).
static-docs build --config <path/to/site.toml>| Flag | Default | Description |
|---|---|---|
--config |
site.toml |
Path to the site configuration file. |
Start a local dev server with live reload. Both names are equivalent.
static-docs preview --config <path/to/site.toml> [--host HOST] [--port PORT]| Flag | Default | Description |
|---|---|---|
--config |
site.toml |
Path to the site configuration file. |
--host |
127.0.0.1 |
Network interface to bind. |
--port |
8000 |
Port to listen on. |
Copy the built output to a publish destination.
static-docs publish --config <path/to/site.toml> [--destination DIR]| Flag | Default | Description |
|---|---|---|
--config |
site.toml |
Path to the site configuration file. |
--destination |
output_dir from config |
Override the target directory for this run. |
Build, add GitHub Pages artifacts (.nojekyll, 404.html), and force-push to a deploy branch.
static-docs gh-deploy --config <path/to/site.toml> [--remote REMOTE] [--branch BRANCH] [--message MSG]| Flag | Default | Description |
|---|---|---|
--config |
site.toml |
Path to the site configuration file. |
--remote |
origin |
Git remote to push to. |
--branch |
gh-pages |
Branch to force-push the output to. |
--message |
Deploy static-docs site |
Commit message for the deploy commit. |
[site]
title = "My Docs"
description = "Documentation for My Project"
base_url = "https://your-org.github.io/your-repo/"
output_dir = "dist"
[brand]
name = "My Project"
[theme]
name = "static-docs"
[nav]
file = "navigation.yml"- title: Overview
page: index.md
- title: Guides
items:
- page: docs/getting-started.md
- page: docs/configuration.md
- navigation-bar:
github:
title: GitHub
link: https://github.com/your-org/your-repo
logo: https://github.githubassets.com/favicons/favicon.svg
resources:
title: Resources
items:
- name: Release notes
link: https://example.com/releases
- issues:
title: Issues
link: https://github.com/your-org/your-repo/issuesEach nav item supports: title, page, url, items, order.
navigation-bar.githubrenders as a dedicated icon link in the top-right header.- Other
navigation-barentries render to the left of the search bar. issues.linkpopulates the "Give us feedback" link in the right-side TOC panel.
YAML (---) or TOML (+++) at the top of any .md file:
---
title: Architecture
nav_title: System Design
order: 4
summary: Explains the pipeline and page rendering model.
template: page.html
draft: false
---| Field | Description |
|---|---|
title |
Page <title> and <h1> (overrides first # heading). |
nav_title |
Shorter label used only in the sidebar. |
order |
Integer sort key within a navigation group. |
summary |
Used in <meta description> and search results. |
template |
Select an alternate template from theme/templates/. |
draft |
Set true to exclude from the build output. |
Static Docs includes one built-in docs theme:
[theme]
name = "static-docs"static-docs/
├── src/staticnest/ # package source
│ ├── cli.py # argparse entry point
│ ├── site.py # build / publish / deploy orchestration
│ ├── markdown.py # Python-Markdown/pymdown renderer
│ ├── theme.py # CSS, JS, and HTML template
│ ├── devserver.py # live-reload HTTP server
│ └── scaffold.py # init command scaffolding
├── docs/ # documentation site source
│ ├── content/
│ ├── navigation.yml
│ └── site.toml
├── tests/ # pytest test suite
├── uv.lock # locked development and CI dependencies
├── pyproject.toml
└── README.md
uv run static-docs preview --config docs/site.tomlOpen http://127.0.0.1:8000 in your browser. The server rebuilds and reloads automatically when you save a file.
uv sync --locked --extra dev
uv run pytestReleases are automated through the shared Dev-kitx release workflow and PyPI Trusted Publishing. Publishing a GitHub Release triggers the PyPI workflow automatically.
To verify a release artifact locally before publishing, maintainers can build with:
uv sync --locked --extra dev
uv buildMIT — see LICENSE.