Static Docs

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.

Features

• Python-only runtime — no Node or frontend build step
• TOML-based configuration — single site.toml controls 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-extensions for 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/

Installation

From PyPI

pip install static-docs

From source (local / contributor)

git clone https://github.com/Dev-kitx/static-docs.git
cd static-docs
uv sync --locked --extra dev

The project uses uv.lock for repeatable contributor and CI installs. The static-docs command is available through uv run static-docs.

Quick start

# 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.toml

The scaffolded directory contains:

my-docs/
├── site.toml        # site-wide config
├── navigation.yml   # sidebar + top-bar nav
└── content/
    └── index.md     # home page

Project documentation

This repository includes a full Static Docs documentation site under docs/.

static-docs build --config docs/site.toml

The docs source explains configuration, authoring, components, API docs generation, search, SEO, LLM files, and GitHub Actions deployment.

CLI reference

All commands follow the pattern:

static-docs <command> [options]

init

Scaffold a new project directory.

static-docs init [path]

build

Build the site to output_dir (configured in site.toml).

static-docs build --config <path/to/site.toml>

preview / serve

Start a local dev server with live reload. Both names are equivalent.

static-docs preview --config <path/to/site.toml> [--host HOST] [--port PORT]

publish

Copy the built output to a publish destination.

static-docs publish --config <path/to/site.toml> [--destination DIR]

gh-deploy

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]

Configuration (site.toml)

[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"

Navigation (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/issues

Each nav item supports: title, page, url, items, order.

• navigation-bar.github renders as a dedicated icon link in the top-right header.
• Other navigation-bar entries render to the left of the search bar.
• issues.link populates the "Give us feedback" link in the right-side TOC panel.

Front matter

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
---

Theme

Static Docs includes one built-in docs theme:

[theme]
name = "static-docs"

Repository layout

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

Local development

Run the documentation site

uv run static-docs preview --config docs/site.toml

Open http://127.0.0.1:8000 in your browser. The server rebuilds and reloads automatically when you save a file.

Run tests

uv sync --locked --extra dev
uv run pytest

Releasing

Releases 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 build

License

MIT — see LICENSE.