# Folio

> A documentation engine that ships as one native Rust binary. One config file points Folio at the source and guides already in your repo. Open source.

## Docs
- [API Reference](https://pguijas.github.io/folio/docs/api-reference/): What the generated API reference contains, and why this site ships without one for Folio's own code.
- [Architecture](https://pguijas.github.io/folio/docs/architecture/): Folio Docs has one local build pipeline. The CLI reads configuration and parses project sources once, then emits the human site and its agent-readable mirrors. The pipeline runs inside the `folio` binary. Its implementation lives in the Rust crates under `crates/`.
- [CLI Reference](https://pguijas.github.io/folio/docs/cli/): Reference for Folio CLI commands, flags, and workflows including init, build, serve, coverage, and clean.
- [Accordion](https://pguijas.github.io/folio/docs/components/accordion/): Collapsible content sections for organizing information into expandable panels. Use Accordion for FAQs, grouped content, or any situation where you want to reduce page clutter while keeping information accessible. Unlike MethodAccordion, which is structured for API methods, Accordion supports any content.
- [BeforeAfter](https://pguijas.github.io/folio/docs/components/before-after/): Show two related code snippets side by side. It works well for migration notes, config changes, and generated output comparisons.
- [BrowserFrame](https://pguijas.github.io/folio/docs/components/browser-frame/): Browser window chrome around any content: three dots, a mono URL bar, and an optional right-aligned status label. Use it to frame live embeds — roadmap miniatures, rendered components, page excerpts — as the page they ship on, instead of pasting a screenshot.
- [BuildArtifact](https://pguijas.github.io/folio/docs/components/build-artifact/): Summarize the files, directories, and generated routes produced by a Folio command.
- [Callout](https://pguijas.github.io/folio/docs/components/callout/): Highlighted message blocks for notes, warnings, tips, and other important information. Each type has its own icon; the colors come from the theme tokens below.
- [Checklist](https://pguijas.github.io/folio/docs/components/checklist/): A readiness list with explicit states. Use it for prerequisites, deployment checks, and release gates.
- [ClassOverview](https://pguijas.github.io/folio/docs/components/class-overview/): A card displaying a class with its name, base classes, decorators, and description. Every Python and JavaScript class on a generated API page opens with one, and the page writes the class docstring below the card rather than in `description`. You can also use it by hand for class documentation you write yourself.
- [Code Blocks](https://pguijas.github.io/folio/docs/components/code-blocks/): Fenced code blocks with syntax highlighting, line highlighting, line numbers, filenames, and word highlighting — powered by Shiki and rehype-pretty-code.
- [CodeGroup](https://pguijas.github.io/folio/docs/components/code-group/): Tabbed code blocks for showing the same concept in multiple languages or multiple variants of a command. Tabs are automatically labeled from the language of each code block, or you can provide explicit labels.
- [CommandGrid](https://pguijas.github.io/folio/docs/components/command-grid/): A compact command overview for CLI-heavy pages. Use `CommandGrid` with one or more `CommandCard` children.
- [CompareMatrix](https://pguijas.github.io/folio/docs/components/compare-matrix/): A comparison matrix with check / dash / partial cells and a highlighted "us" column. Use it where the honest answer is a grid, not three paragraphs of prose.
- [ConfigPanel](https://pguijas.github.io/folio/docs/components/config-panel/): Pair a YAML example with short field notes. Use it when a configuration snippet needs explanation but a full reference table would interrupt the guide.
- [Page Actions](https://pguijas.github.io/folio/docs/components/copy-page-button/): Folio renders a compact `Ask AI` page-actions button above every documentation page. It is meant for source-heavy docs: copy the current page, or send the current page context to ChatGPT without adding extra setup.
- [DeprecationNotice](https://pguijas.github.io/folio/docs/components/deprecation-notice/): A styled banner indicating that a class, function, or module is deprecated. Displays a red "Deprecated" badge with version information and guidance on what to use instead. Generated API pages do not write this component: a docstring's `Deprecated:` section or a JSDoc `@deprecated` tag renders as a **Deprecated:** paragraph. Use it by hand in the pages you write.
- [DocPreview](https://pguijas.github.io/folio/docs/components/doc-preview/): Use `DocPreview` when a guide needs to show a generated documentation route or a small generated example instead of describing the result with another code block. It renders a responsive iframe with a short caption, a source view with a collapsible file drawer for the focused source file, a line-numbered code preview, and direct links to the page and source file.
- [ExampleTabs](https://pguijas.github.io/folio/docs/components/example-tabs/): Tabbed panels for showing multiple code examples for the same concept, such as basic vs. advanced usage or different input formats. Each tab displays its code as a plain, unhighlighted block. For highlighted tabs, use CodeGroup with fenced code blocks.
- [FeatureCard and CardGrid](https://pguijas.github.io/folio/docs/components/feature-cards/): Cards for feature overviews, landing pages, and link grids. `FeatureCard` renders a single card with a named icon, title, description, and optional link. `CardGrid` arranges multiple cards in a responsive grid layout.
- [FileTree](https://pguijas.github.io/folio/docs/components/file-tree/): A visual file and folder tree for showing project structures, directory layouts, and file hierarchies. Parses an indented text string into a tree with folder/file icons, connectors, and proper nesting.
- [HookMap](https://pguijas.github.io/folio/docs/components/hook-map/): Visualize an extension lifecycle with stage names, hook names, and short descriptions.
- [Components](https://pguijas.github.io/folio/docs/components/): Reusable MDX components for Folio documentation pages, including callouts, tabs, previews, diagrams, and API reference helpers.
- [Kbd](https://pguijas.github.io/folio/docs/components/kbd/): A key the reader presses, drawn as a small keycap inside the sentence. Use it for shortcuts and key names. A bare `<kbd>` tag written in a page draws the same way.
- [Marker](https://pguijas.github.io/folio/docs/components/marker/): A labelled divider: a short line of small text between two dashed rules. Use it to break a long guide into parts ("Advanced", "Since 0.4", "Optional") without adding a heading to the table of contents.
- [Math (LaTeX)](https://pguijas.github.io/folio/docs/components/math/): Inline and display math rendering via KaTeX. Use `$` for inline expressions and `$$` for centered display equations. Math support is enabled by default — no configuration needed.
- [Mermaid](https://pguijas.github.io/folio/docs/components/mermaid/): Renders Mermaid diagrams as SVG directly in the browser. Supports flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, and all other Mermaid diagram types. Automatically switches between light and dark themes to match the site.
- [MethodAccordion](https://pguijas.github.io/folio/docs/components/method-accordion/): Expandable accordion panels for documenting class methods. Each method shows its name and signature in the header, with the full description revealed on click. Async methods display an "async" badge. Generated API pages do not write this component, since they give each method a heading of its own; use it by hand in the pages you write.
- [ParamTable](https://pguijas.github.io/folio/docs/components/param-table/): A structured table for displaying function or method parameters with name, type, default value, and description columns. Every Python and JavaScript function with parameters on a generated API page gets one, filled from its signature and its docstring or JSDoc; Rust functions show their signature instead. You can also use it by hand for documentation you write yourself.
- [PreviewCode](https://pguijas.github.io/folio/docs/components/preview-code/): Pair a rendered component example with its MDX source. The Code tab shows the fenced block you write beside the preview, not source read back from the rendered part, so keep the two in step by hand: nothing checks that they match. Use `PreviewCode` for component catalog examples so readers can inspect the result first and switch to the code without scrolling through a duplicated section.
- [PullQuote](https://pguijas.github.io/folio/docs/components/pull-quote/): A high-emphasis statement block for the one sentence the page exists to deliver — verdicts, theses, the line you want quoted back.
- [StatStrip](https://pguijas.github.io/folio/docs/components/stat-strip/): A row of big numbers with labels — the fastest way to make scale legible. Values are strings, so units and symbols render exactly as written.
- [Steps](https://pguijas.github.io/folio/docs/components/steps/): Numbered step-by-step instructions with a vertical timeline. Steps are numbered automatically using CSS counters — you do not provide numbers manually. Use Steps for tutorials, setup guides, and any sequential process.
- [Swot](https://pguijas.github.io/folio/docs/components/swot/): A four-quadrant SWOT analysis rendered as a color-coded grid: strengths, weaknesses, opportunities, and threats, each with its own accent and marker. Use it for honest product or design assessments that a bulleted list would flatten.
- [Tabs](https://pguijas.github.io/folio/docs/components/tabs/): Generic tabbed content panels for organizing alternative content views. Unlike CodeGroup (which is code-only), Tabs supports any content including text, tables, images, and nested components.
- [Term](https://pguijas.github.io/folio/docs/components/term/): A word or API name with its definition one hover away. The term keeps its place in the sentence, marked by a dotted underline, and the definition appears in a small card above it.
- [TerminalSession](https://pguijas.github.io/folio/docs/components/terminal-session/): Render a command with prompt context, optional output, and a compact status marker. Most guide command snippets should use plain fenced `bash` blocks. Reserve `TerminalSession` for cases where prompt context, exact output, or status state matters to the reader.
- [Theme picker](https://pguijas.github.io/folio/docs/components/theme-configurator/): The theme picker lets readers choose how the site looks. A preset owns color tokens, document rhythm, code block treatment, borders, radius defaults, typography defaults, and its own controls; the picker groups related presets into families, shows complete color-and-style variants as swatches, and offers manual controls in Customize.
- [Timeline](https://pguijas.github.io/folio/docs/components/timeline/): Vertical timeline for changelogs, version history, or sequential events. Each item shows a date, title, optional badge, and description. Badges like `"new"` and `"breaking"` have special styling.
- [TypeBadge](https://pguijas.github.io/folio/docs/components/type-badge/): A small inline badge for displaying a type annotation. Renders as a styled badge with monospace font. When an `href` is provided, the badge becomes a link to the type's documentation page. Every type in a generated parameter table is one.
- [Configuration](https://pguijas.github.io/folio/docs/configuration/): Configure Folio source inputs, project metadata, theme options, custom templates, search, LLM files, and deployment settings in docs.yaml.
- [CI/CD](https://pguijas.github.io/folio/docs/deployment/ci-cd/): Automate Folio documentation deployment, pull request checks, branch previews, and coverage gates.
- [GitHub Pages](https://pguijas.github.io/folio/docs/deployment/github-pages/): Deploy Folio docs to GitHub Pages, including base path inference, production deploys, and branch previews.
- [Deployment](https://pguijas.github.io/folio/docs/deployment/): Deploy Folio's static _site artifact to static hosts, GitHub Pages, CI/CD workflows, or self-hosted infrastructure.
- [Static Hosts](https://pguijas.github.io/folio/docs/deployment/static-hosts/): Deploy Folio's _site artifact to Vercel, Netlify, or self-hosted static infrastructure.
- [Developer Guide](https://pguijas.github.io/folio/docs/developing/): Build, test, and run the folio binary from a checkout of the Folio repository.
- [Writing Doc Comments](https://pguijas.github.io/folio/docs/docstrings/): Write Python docstrings, JSDoc comments and Rust doc comments that Folio turns into clear API reference pages.
- [Overview](https://pguijas.github.io/folio/docs/): The documentation engine that turns source and Markdown into a static site.
- [Installation](https://pguijas.github.io/folio/docs/installation/): Install Folio with one command, verify Node.js, and prepare the CLI for local documentation builds.
- [Languages](https://pguijas.github.io/folio/docs/languages/): Source language support, configuration, and limits for Python, JavaScript, and Rust.
- [Migrating from Sphinx](https://pguijas.github.io/folio/docs/migration/): Move a Sphinx project's guides and API documentation to Folio, configure sources, and verify the generated site.
- [Writing Plugins](https://pguijas.github.io/folio/docs/plugins/authoring/): *Extend the build pipeline with custom components, data, views, and hooks.*
- [Plugin Catalog](https://pguijas.github.io/folio/docs/plugins/catalog/): *Every integration in the Folio binary, in one place.*
- [Plugins](https://pguijas.github.io/folio/docs/plugins/): *One extension point for everything Folio builds: components, data, pages, and views.*
- [Landing Page](https://pguijas.github.io/folio/docs/plugins/landing/): *Configure the optional homepage that appears before the documentation app.*
- [OpenAPI](https://pguijas.github.io/folio/docs/plugins/openapi/): *Turn an OpenAPI spec into an endpoint index page in your docs.*
- [Roadmap](https://pguijas.github.io/folio/docs/plugins/roadmap/): The built-in roadmap integration renders source-defined phases as a release timeline. The view below reads the same data as the standalone `/roadmap/` route, which is optional: `routes.public: true` turns it on.
- [Trust & Safety](https://pguijas.github.io/folio/docs/plugins/trust/): *What a plugin can do on your machine, what Folio guarantees, and where those guarantees stop.*
- [Quick Start](https://pguijas.github.io/folio/docs/quickstart/): Generate and preview documentation for an existing project.
- [Custom Templates](https://pguijas.github.io/folio/docs/theming/custom-templates/): Give expert users full control over the generated documentation frontend with a project-owned Next/Nextra template.
- [Theming](https://pguijas.github.io/folio/docs/theming/): Understand Folio's theming model, from bundled theme personalization to theme packages and full custom templates.
- [Personalization](https://pguijas.github.io/folio/docs/theming/personalization/): Configure Folio's bundled docs theme with presets, project tokens, variants, header branding, logo, favicon, and dark mode.
- [Theme Packages](https://pguijas.github.io/folio/docs/theming/theme-packages/): Use theme.package to overlay project-owned theme files on top of Folio's bundled template.
- [Troubleshooting](https://pguijas.github.io/folio/docs/troubleshooting/): The errors and warnings a Folio build prints, what each one means, and the page that fixes it.
- [Why Folio](https://pguijas.github.io/folio/docs/why-folio/): *The questions that decide whether Folio is for you — answered honestly.*