folio-docs 0.1.0

A modern Python documentation generator. Sphinx alternative using Nextra + shadcn.

Folio

Modern Python documentation generator. Sphinx alternative powered by Nextra + shadcn/ui.

Documentation · GitHub

Quickstart

Folio is a Python CLI that uses a bundled Nextra/Next.js template at build time. Install it as a uv tool:

uv tool install folio-docs
folio init
folio serve

For scripted installs, download and inspect the standalone installer before running it:

curl -LsSf https://raw.githubusercontent.com/pguijas/folio/main/install.sh | less
curl -LsSf -o install-folio.sh https://raw.githubusercontent.com/pguijas/folio/main/install.sh
sh install-folio.sh

Build and serve commands require Node.js 20.19+ and pnpm 10.

Three commands. You get a full docs site with API reference, dark mode, search, and a modern component library — all generated from your Python source code and a single docs.yaml.

How it works

Folio reads your Python modules and Markdown guides, converts them into an intermediate representation, writes MDX pages into a bundled Nextra/Next.js template, installs the template's pnpm dependencies when needed, and exports a static site. The generated output includes guides, API reference pages, search data, and optional LLM files.

See it in action

Folio documents itself. The live site was generated by the tool you're looking at, from the same Markdown guides and Python source published in this repository.

What you get

• Auto API reference — Classes, functions, types, and parameters extracted via AST
• Single YAML config — one docs.yaml replaces conf.py + extensions; minimal configs are ~30 lines
• Modern UI — Dark mode, Pagefind search, responsive layout, theme configurator
• Incremental builds — SHA-256 manifest skips unchanged pages
• Rich components — Mermaid diagrams, KaTeX math, tabs, accordion, timeline, file tree
• LLM-friendly output — Generates llms.txt alongside your docs
• Static deployment — Export plain files for GitHub Pages, Vercel, Netlify, or Docker
• Sphinx migration — step-by-step migration guide from Sphinx projects

Contributing

See CONTRIBUTING.md.

License

AGPL-3.0-only — see LICENSE. Bundled third-party materials (shadcn/ui components, service logos) are covered in THIRD-PARTY-NOTICES.md.