Folio

A modern Python documentation generator that turns your source code into searchable API reference and guide pages without the complexity of Sphinx.

Get started in 30 seconds


uv add folio-docs
uv run folio init        # auto-detects your project
uv run folio serve       # live preview at localhost:4321

That’s it. Folio reads your pyproject.toml, scans your source code, and generates a full documentation site with API reference, search, and dark mode.

How it works

Folio follows a four-stage pipeline:

flowchart LR
  Source["▣ Python source (.py)"] --> Parse["⚙ Parse AST + docstrings"]
  Parse --> IRNode["◇ IR objects"]
  IRNode --> Generate["▤ Generate MDX pages"]
  Generate --> BuildSite["▥ Build Nextra static site"]

Parse — Reads Python source files via the ast module. Extracts classes, functions, type annotations, decorators, and Google-style docstrings.
IR — Converts parsed data into a clean intermediate representation (ModuleIR, ClassIR, FunctionIR) that captures everything needed for docs.
Generate — Transforms the IR into MDX pages with function signatures, parameter tables, class overviews, and formatted docstring content.
Build — Places MDX files into a Nextra site with shadcn/ui components. Produces a static site with search, dark mode, and responsive layout.

Features

Automatic API reference — Point Folio at your source directories and get complete API docs. Classes, methods, parameters, return types, decorators — all extracted and rendered automatically.

One config file — A single docs.yaml (typically under 30 lines) replaces Sphinx’s conf.py, Makefile, and requirements setup.

Modern UI — Dark mode, full-text search, responsive layout, and shadcn/ui components out of the box. No theme hunting.

Markdown + API in one site — Write tutorials and guides in Markdown alongside auto-generated API reference. Everything lives in one cohesive site.

Static deployment — Export plain files for GitHub Pages, Vercel, Netlify, or Docker without a custom server.

LLM-friendly output — Generates llms.txt and llms-full.txt following the llmstxt.org spec, so AI coding assistants can understand your library.

Sphinx migration — Includes a migration guide and an RST-to-MDX converter for common directives. Convert existing RST pages to Markdown before adding them to source.docs.

Comparison

Feature matrix comparing Folio with pdoc, Sphinx, MkDocs, Mintlify, and GitBook.
Tool	Python API	Guides	Static export	LLM friendly	Extensibility	Open source	Git + CI
Folio	Yes	Yes	Yes	Yes	Yes	Yes	Yes
pdoc	Yes	Some	Yes	No	Some	Yes	Some
Sphinx	Yes	Yes	Yes	No	Yes	Yes	Yes
MkDocs	Some	Yes	Yes	No	Yes	Yes	Yes
Mintlify	No	Yes	No	Yes	Some	No	Some
GitBook	No	Yes	No	Yes	Some	No	Some

Next steps

Installation — Prerequisites and setup
Quick Start — Build your first docs site step by step
Architecture — How the CLI, parser, generator, template, and export pipeline fit together
Configuration — Full docs.yaml reference
CLI Reference — Every command, flag, and option
Writing Docstrings — How Folio parses your code
Components — UI components available in your docs
Theming — Customize colors, fonts, and layout
Migrating from Sphinx — Step-by-step migration guide