Skip to contentSkip to Content
Feedback
ThemingTheming

Theming

Folio has one theming model with three ownership levels. Start with the bundled template, move to a theme package when a project needs exact visual control, and use a custom template only when the documentation must live inside a fully project-owned frontend.

Choose an Ownership Level

LevelConfigure withUse whenWho owns the frontend
Theme personalizationtheme.preset, theme.tune, theme.tokens, theme.header, theme.variantsThe bundled Folio docs shell is right, but the brand, colors, typography, spacing, or header need tuning.Folio owns the template; your project owns safe theme data.
Theme packagetheme.packageThe docs should still use Folio’s bundled template as a base, but a project needs to override files such as layouts, CSS, the configurator, or project theme code.Folio owns generated content; the package overlays selected template files.
Custom templatetemplate.pathThe docs must run inside a product-specific Next/Nextra frontend with its own routes, dependencies, chrome, search UI, or application layout.The custom template owns the frontend workspace.
Personalize a Theme
Set presets, defaults, tokens, variants, header actions, logo, favicon, and dark mode from docs.yaml.
Build a Theme Package
Overlay files on the bundled template while Folio still injects generated content and metadata.
Use a Custom Template
Bring a full Next/Nextra frontend and consume Folio's generated MDX, metadata, and component contract.

How Folio Applies Theme Configuration

flowchart TD
  Config["docs.yaml"] --> Theme["theme.*"]
  Config --> Template["template.*"]
  Theme --> Preset["Bundled preset and safe project preset"]
  Theme --> Package{"theme.package?"}
  Package -->|No| Bundled["Bundled Folio template"]
  Package -->|Yes| Overlay["Copy package over bundled template"]
  Preset --> Bundled
  Preset --> Overlay
  Template --> Custom{"template.path?"}
  Custom -->|No| Build["Prepare generated docs workspace"]
  Custom -->|Yes| TemplateWorkspace["Copy project-owned template"]
  Bundled --> Build
  Overlay --> Build
  TemplateWorkspace --> Build
  Build --> Site["Static documentation site"]

Folio always owns the generated documentation data: parsed API pages, converted Markdown, _meta.ts, search metadata, LLM outputs, and static export. The theming choice controls how much of the presentation layer your project owns.

  1. Start with theme.preset, theme.tune, logo, and favicon.
  2. Add project tokens, header configuration, and variants if the bundled shell is still the right product experience.
  3. Move to theme.package when the project needs exact control over selected template files but still wants Folio’s bundled template as a base.
  4. Move to template.path when the documentation frontend is a product workspace, not just a styled Folio docs site.

Design Credits

Folio Pastel takes inspiration from cojeev : its organic shapes, typography, floating docs layout and motion. Thank you to Sanjay Kumar (luv-jeri)  for designing it and sharing cojeev-ui  as open source.

The theme picker reference describes the adaptations. The retained licenses and source attribution are in THIRD-PARTY-NOTICES.md.

  • Configuration documents the complete docs.yaml shape.
  • Theme picker documents the theme picker, built-in preset controls, and the underlying preset TypeScript contract.
  • Components lists the MDX components that generated docs and custom templates may need to expose.
Page ActionsTheme Packages