Configuration

Complete reference for every option in your docs.yaml file.

Quick Start

Start with the project name and at least one source input. Folio needs Python source paths or Markdown docs to generate pages:

project:
  name: "my-library"
 
source:
  python:
    paths:
      - "src/my_library"
  docs:
    - "docs"

This scans your Python package and Markdown guides, outputs to _site/, and enables dark mode.

Full Reference

Here is every available section and field.

project

Project metadata shown in the navbar, page titles, and generated output.

project:
  name: "my-library"
  version: "2.0.0"
  repo: "https://github.com/org/my-library"
  repo_ref: "main"

source

Controls where folio looks for source code and documentation files.

deploy

Controls deployment-specific path handling. Most sites can omit this section. Use it when the static site is published under a subpath such as /my-repo.

Base path priority is:

1. FOLIO_BASE_PATH environment variable.
2. deploy.base_path in docs.yaml.
3. GitHub Pages inference when deploy.provider: "github-pages" or FOLIO_DEPLOY_PROVIDER=github-pages is active in GitHub Actions.
4. No base path.

folio serve stays rooted at / unless FOLIO_BASE_PATH is explicitly set.

deploy:
  provider: "github-pages"

For custom domains or reverse proxies, set the base path explicitly:

deploy:
  base_path: "/"

source.python

The python key can be either a mapping (recommended) or a simple list of paths.

Mapping form (recommended):

source:
  python:
    paths:
      - "src/my_library"
    exclude:
      - "**/test_*.py"
      - "src/my_library/_internal/"
    docstring_style: "numpy"

List form (shorthand):

You can also pass a plain list of paths. In this case, no exclude patterns are applied:

source:
  python:
    - "src/my_library"
    - "src/my_library_utils"

source.docs

source:
  docs:
    - "docs/"

.rst files are migration inputs, not build inputs. Convert them to Markdown before placing them in source.docs; Folio warns when .rst files are present in a docs source directory.

output

output: "build/docs"

Folio keeps an incremental manifest in .build/. The manifest includes source hashes plus config, template, and generator fingerprints, so changing docs.yaml or the generator invalidates stale generated pages automatically.

theme

Controls the visual appearance of the generated documentation site.

theme:
  preset: "organic-editorial"
  dark_mode: true
  logo: "docs/assets/logo.svg"
  favicon: "docs/assets/favicon.ico"

search

Controls the built-in full-text search powered by Pagefind . Search is enabled by default, appears in the docs navbar, and opens with Cmd+K on macOS or Ctrl+K on Windows/Linux.

search:
  enabled: true
  placeholder: "Search documentation..."

To disable search completely:

search:
  enabled: false

nav

An ordered list of strings defining the top-level navigation sections. The order here determines the order in the navbar. "API Reference" is typically generated automatically from your Python sources.

nav:
  - "Introduction"
  - "Getting Started"
  - "API Reference"
  - "Changelog"

llm

Controls generation of llms.txt  files for AI consumption.

llm:
  generate_llms_txt: true
  generate_llms_full_txt: false

Path Resolution

In CLI commands, relative paths in docs.yaml are resolved from the active project directory. When you run folio build /path/to/project or folio build --project-dir /path/to/project, that directory becomes the base for config paths. If you call load_config() directly, file plugin paths are resolved from the directory containing the config file.

For example, given this structure:

my-project/
  docs.yaml
  src/
    my_lib/
      __init__.py
  docs/
    index.md

The config source.python.paths: ["src/my_lib"] resolves to /path/to/my-project/src/my_lib.

Config Validation

folio validates your config file and warns about issues:

• Unknown top-level keys produce a warning listing the unrecognized keys. Core top-level keys are: project, source, output, theme, nav, llm, search, and deploy.

• Missing or empty project.name produces a warning and defaults to "Untitled".

• Missing config file raises a FileNotFoundError with the path that was expected.

• MVP-disabled features are excluded from public docs, API reference, search, sitemap, and LLM output until the feature is ready to publish as beta.

These are warnings, not errors — the build will still proceed with defaults where possible.

Common Patterns

Monorepo Setup

When your Python package lives in a subdirectory of a larger repository:

project:
  name: "my-service"
  repo: "https://github.com/org/monorepo"
 
source:
  python:
    paths:
      - "packages/my-service/src/my_service"
    exclude:
      - "**/test_*.py"
      - "**/conftest.py"
  docs:
    - "packages/my-service/docs/"
 
output: "packages/my-service/_site"

Excluding Test Files

Keep test files out of your API reference:

source:
  python:
    paths:
      - "src/"
    exclude:
      - "**/test_*.py"
      - "**/tests/"
      - "**/conftest.py"
      - "src/my_lib/_fixtures/"

Custom Output Directory

Write the built site to a specific location for CI/CD deployment:

output: "build/site"

Multiple Python Source Directories

Document code spread across multiple directories:

source:
  python:
    paths:
      - "src/core"
      - "src/plugins"
      - "src/utils"

Minimal Docs-Only Site

If you just want to serve Markdown documentation without Python API reference:

project:
  name: "My Docs"
 
source:
  docs:
    - "docs/"
 
nav:
  - "Guide"
  - "FAQ"