Configuration

Global themes

Share a consistent visual identity across multiple documentation sites.
View as MarkdownOpen in Claude

Global themes let a single “control” repository define the shared visual identity (logo, colors, fonts, layout, CSS, JS, and more) for your organization’s documentation. Child repositories reference the theme by name and inherit those settings automatically when they publish.

This is useful when your organization maintains multiple documentation sites that should share the same branding.

How it works

1

Export a theme from your control repository

From the repository that defines your canonical branding, run:

$fern docs theme export

This reads the theme-eligible fields from your docs.yml and produces a theme.yml file along with copies of any local assets (logos, fonts, CSS, JS) in a fern/theme/ directory.

Use --output to specify a different directory:

$fern docs theme export --output ./my-theme
2

Upload the theme

Upload the exported theme to Fern’s registry:

$fern docs theme upload --name my-theme

This uploads the theme configuration and all referenced file assets. If you omit --name, the theme is saved as default.

3

Confirm the upload

List all themes for your organization:

$fern docs theme list

Use --json for machine-readable output that includes updatedAt timestamps:

$fern docs theme list --json
4

Reference the theme from a child repository

In a child repository’s docs.yml, add:

docs.yml
1global-theme: my-theme
5

Publish as normal

Run the standard publish command from the child repository:

$fern generate --docs

The CLI fetches the named theme from Fern’s registry, downloads any file assets, merges the theme into the local docs.yml configuration, and publishes the merged result. No extra steps are needed.

What the theme controls

When a global theme is applied, the theme’s values take precedence for branding fields while the child repository retains control of its content and structure.

Owned by the theme (control repository)

  • logo - brand logo images and link
  • favicon - browser tab icon
  • background-image - page background
  • colors - accent and background colors
  • typography - body, heading, and code fonts
  • layout - sidebar width, content width, tab and searchbar placement
  • theme - light/dark mode default
  • settings - display settings
  • integrations - analytics and tracking
  • css - custom stylesheets
  • js - custom scripts
  • header - custom header component
  • footer - custom footer component
  • navbar-links - top navigation links
  • footer-links - footer navigation links
  • ai-search - AI search configuration
  • announcement - announcement banner
  • metadata - SEO metadata

Owned by the child repository

  • navigation - tabs, sections, pages
  • apis - API references
  • redirects
  • versions
  • instances - domain and URL

Updating a theme

To update a theme, make changes to the control repository’s docs.yml, re-export, and re-upload with the same name. The next time a child repository publishes, it picks up the updated theme automatically.

$fern docs theme export
$fern docs theme upload --name my-theme