Global themes

Share a consistent visual identity across multiple documentation sites.

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.

Set up a global theme

Export a theme from your control repository

From the repository that defines your canonical branding, export the theme:

$ 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

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.

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

Reference the theme from a child repository

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

docs.yml

1 global-theme: my-theme

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 over branding fields in the child repository’s docs.yml while the child retains control of its content and structure. In a child repo, only edit fields owned by the child repository — any local changes you make to theme-owned fields are overwritten on publish when the theme is merged in.

Field	Owner	Description
`logo`	Theme	Brand logo images and link
`favicon`	Theme	Browser tab icon
`background-image`	Theme	Page background
`colors`	Theme	Accent and background colors
`typography`	Theme	Body, heading, and code fonts
`layout`	Theme	Sidebar width, content width, tab and searchbar placement
`theme`	Theme	Light/dark mode default
`settings`	Theme	Display settings
`integrations`	Theme	Analytics and tracking
`css`	Theme	Custom stylesheets
`js`	Theme	Custom scripts
`header`	Theme	Custom header component
`footer`	Theme	Custom footer component
`navbar-links`	Theme	Top navigation links
`footer-links`	Theme	Footer navigation links
`ai-search`	Theme	AI search configuration
`announcement`	Theme	Announcement banner
`metadata`	Theme	SEO metadata
`navigation`	Child repository	Tabs, sections, pages
`apis`	Child repository	API references
`redirects`	Child repository	Redirects
`versions`	Child repository	Versions
`instances`	Child repository	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

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