Metadata-Version: 2.4
Name: folio-docs
Version: 0.1.0
Summary: A modern Python documentation generator. Sphinx alternative using Nextra + shadcn.
Project-URL: Homepage, https://github.com/pguijas/folio
Project-URL: Documentation, https://pguijas.github.io/folio/
Project-URL: Issues, https://github.com/pguijas/folio/issues
Project-URL: Source, https://github.com/pguijas/folio
Author: pguijas
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: docs,documentation,nextra,python,static-site-generator
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: docstring-parser>=0.16
Requires-Dist: pluggy>=1.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: readchar>=4.0.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.15.0
Requires-Dist: watchfiles>=1.0
Description-Content-Type: text/markdown

<h1 align="center">Folio</h1>

<p align="center">
  <strong>Modern Python documentation generator. Sphinx alternative powered by Nextra + shadcn/ui.</strong>
</p>

<p align="center">
  <a href="https://pguijas.github.io/folio/">Documentation</a> &middot;
  <a href="https://github.com/pguijas/folio">GitHub</a>
</p>

<p align="center">
  <a href="https://github.com/pguijas/folio/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/pguijas/folio/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
  <a href="https://pypi.org/project/folio-docs/"><img src="https://img.shields.io/pypi/v/folio-docs?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/folio-docs/"><img src="https://img.shields.io/pypi/pyversions/folio-docs?style=flat-square" alt="Python"></a>
  <a href="https://github.com/pguijas/folio/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pguijas/folio?style=flat-square" alt="License"></a>
</p>

## Quickstart

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

```bash
uv tool install folio-docs
folio init
folio serve
```

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

```bash
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](https://pguijas.github.io/folio/) 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](https://pguijas.github.io/folio/docs/migration) from Sphinx projects

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

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