> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/docs/configuration/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI0Y2FlZWYxNC0zNjQ5LTQ4MDctYTQyMy0xNWJkOTEwNGYxNDkiLCJleHAiOjE3NzczNTkwNjEsImlhdCI6MTc3NzM1ODc2MX0.2WXG1AcE7bS1yw6yjhygmsPDddoFFcF4rMdSVGOBXik
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# Global themes

> Learn how to use global themes to define branding in one repository and apply it automatically across child 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.

## How it works

<Steps>
  ### Export a theme from your control repository

  From the repository that defines your canonical branding, run:

  ```bash
  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:

  ```bash
  fern docs theme export --output ./my-theme
  ```

  ### Upload the theme

  Upload the exported theme to Fern's registry:

  ```bash
  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:

  ```bash
  fern docs theme list
  ```

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

  ```bash
  fern docs theme list --json
  ```

  ### Reference the theme from a child repository

  In a child repository's `docs.yml`, add:

  ```yaml docs.yml
  global-theme: my-theme
  ```

  ### Publish as normal

  Run the standard publish command from the child repository:

  ```bash
  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.
</Steps>

## 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.

```bash
fern docs theme export
fern docs theme upload --name my-theme
```