Deployment

Folio builds a static site into _site/. Deploy that folder to any static host. The internal .build/ workspace is only a cache and should not be committed or used as the public artifact.

Deployment has one artifact and several delivery paths:

Path	Use when
Static hosts	You want Vercel, Netlify, or a static web server to build or serve `_site/`.
GitHub Pages	You want production docs and optional PR previews hosted by GitHub Pages.
CI/CD	You want GitHub Actions or another pipeline to build, check, and publish docs automatically.

Static Hosts

Deploy _site/ to Vercel, Netlify, or a small self-hosted static server.

GitHub Pages

Configure base paths, Pages artifacts, production deploys, and branch previews.

CI/CD

Automate deployment, branch previews, pull request checks, and coverage gates.

Build Once

With Folio installed, run the build from your project root:


folio build --clean

The _site/ directory contains HTML, assets, Pagefind search data, llms.txt, llms-full.txt, and the Markdown mirrors and authoring contract under _folio/.

flowchart LR
  Source["Source code and Markdown"] --> Build["folio build --clean"]
  Build --> Site["_site/ static artifact"]
  Site --> Host["Static host"]
  Site --> Pages["GitHub Pages"]
  Site --> Pipeline["CI/CD publish job"]

Base Paths

Most hosts serve docs at the root. Use a base path when the generated site is published under a subpath such as /my-repo.

Base path priority is:

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

project.url is metadata only. It feeds sitemap and canonical URLs, but it does not control local routing or static asset paths.

Choose a Strategy

Use Static Hosts for Vercel, Netlify, Docker, Caddy, Nginx, or any static file server.
Use GitHub Pages when the public artifact is a GitHub Pages site and you need Pages-specific base path behavior.
Use CI/CD when deployment should happen automatically on pushes, releases, pull requests, or scheduled workflows.