fern-api · aditya-arolkar-swe · Apr 28, 2026 · Apr 28, 2026
@@ -427,6 +427,8 @@ redirects:
     destination: /learn/docs/customization/custom-react-components
 
   # Docs customization
+  - source: /learn/docs/configuration/global-themes
+    destination: /learn/docs/customization/global-themes
   - source: /learn/docs/customization/custom-header-and-footer
     destination: /learn/docs/customization/header-and-footer
   - source: /learn/docs/customization/changelogs

@@ -825,7 +825,7 @@ hideOnThisPage: true
 
   <Accordion title="fern docs theme export">
 
-    Use `fern docs theme export` to extract the theme-eligible fields from your `docs.yml` into a standalone directory. The exported `theme.yml` and its assets can then be uploaded with `fern docs theme upload`.
+    Use `fern docs theme export` to extract the [theme-eligible fields](/learn/docs/customization/global-themes) from your `docs.yml` into a standalone directory. The exported `theme.yml` and its assets can then be uploaded with `fern docs theme upload`.
 
     <CodeBlock title="terminal">
     ```bash
@@ -847,7 +847,7 @@ hideOnThisPage: true
 
   <Accordion title="fern docs theme upload">
 
-    Use `fern docs theme upload` to upload a theme to Fern's registry. The command reads `theme.yml` from `./fern/theme/` and uploads it along with any referenced file assets.
+    Use `fern docs theme upload` to upload a [theme](/learn/docs/customization/global-themes) to Fern's registry. The command reads `theme.yml` from `./fern/theme/` and uploads it along with any referenced file assets.
 
     <CodeBlock title="terminal">
     ```bash
@@ -875,7 +875,7 @@ hideOnThisPage: true
 
   <Accordion title="fern docs theme list">
 
-    Use `fern docs theme list` to list all themes uploaded for your organization.
+    Use `fern docs theme list` to list all [themes](/learn/docs/customization/global-themes) uploaded for your organization.
 
     <CodeBlock title="terminal">
     ```bash

@@ -42,8 +42,6 @@ navigation:
       - page: Page-level settings
         path: ./pages/navigation/frontmatter.mdx
         slug: page-level-settings
-      - page: Global themes
-        path: ./pages/configuration/global-themes.mdx
   - section: Writing content
     contents:
       - page: Markdown basics
@@ -266,6 +264,8 @@ navigation:
         path: ./pages/customization/custom-react-components.mdx
       - page: Header and footer
         path: ./pages/customization/custom-header-footer.mdx
+      - page: Global themes
+        path: ./pages/customization/global-themes.mdx
   - section: Localization
     collapsed: true
     availability: pre-release

@@ -1,9 +1,9 @@
 ---
-tags: ["configuration"]
+tags: ["configuration", "docs.yml"]
 ---
 
 ## Global themes
 
 Define your documentation branding in a single control repository and share it across multiple sites. Use the `fern docs theme` CLI commands to export, upload, and manage themes, then reference a theme by name in any child repository's `docs.yml` with the `global-theme` property.
 
-<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/global-themes">Read the docs</Button>
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/customization/global-themes">Read the docs</Button>
@@ -0,0 +1,125 @@
+---
+title: Global themes
+subtitle: Share a consistent visual identity across multiple documentation sites.
+description: 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.
+
+## Set up a global theme
+
+<Steps>
+
+<Step title="Export a theme from your control repository">
+
+From the repository that defines your canonical branding, [export](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-export) the theme:
+
+```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
+```
+
+</Step>
+
+<Step title="Upload the theme">
+
+[Upload](/learn/cli-api-reference/cli-reference/commands#fern-docs-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`.
+
+</Step>
+
+<Step title="Confirm the upload">
+
+[List](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-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
+```
+
+</Step>
+
+<Step title="Reference the theme from a child repository">
+
+In a child repository's `docs.yml`, add:
+
+```yaml docs.yml
+global-theme: my-theme
+```
+
+</Step>
+
+<Step title="Publish as normal">
+
+Run the standard [publish command](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs) 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.
+
+</Step>
+
+</Steps>
+
+## 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.
+
+
+<StickyTable>
+| Field | Owner | Description |
+| --- | --- | --- |
+| [`logo`](/learn/docs/configuration/site-level-settings#logo-configuration) | Theme | Brand logo images and link |
+| [`favicon`](/learn/docs/configuration/site-level-settings#favicon) | Theme | Browser tab icon |
+| [`background-image`](/learn/docs/configuration/site-level-settings#background-image-configuration) | Theme | Page background |
+| [`colors`](/learn/docs/configuration/site-level-settings#colors-configuration) | Theme | Accent and background colors |
+| [`typography`](/learn/docs/configuration/site-level-settings#typography-configuration) | Theme | Body, heading, and code fonts |
+| [`layout`](/learn/docs/configuration/site-level-settings#layout-configuration) | Theme | Sidebar width, content width, tab and searchbar placement |
+| [`theme`](/learn/docs/configuration/site-level-settings#theme-configuration) | Theme | Light/dark mode default |
+| [`settings`](/learn/docs/configuration/site-level-settings#settings-configuration) | Theme | Display settings |
+| [`integrations`](/learn/docs/configuration/site-level-settings#integrations-configuration) | Theme | Analytics and tracking |
+| [`css`](/learn/docs/customization/custom-css-js) | Theme | Custom stylesheets |
+| [`js`](/learn/docs/customization/custom-css-js) | Theme | Custom scripts |
+| [`header`](/learn/docs/configuration/site-level-settings#header) | Theme | Custom header component |
+| [`footer`](/learn/docs/configuration/site-level-settings#footer) | Theme | Custom footer component |
+| [`navbar-links`](/learn/docs/configuration/site-level-settings#navbar-links-configuration) | Theme | Top navigation links |
+| [`footer-links`](/learn/docs/configuration/site-level-settings#footer-links-configuration) | Theme | Footer navigation links |
+| [`ai-search`](/learn/docs/configuration/site-level-settings#ask-fern-configuration) | Theme | AI search configuration |
+| [`announcement`](/learn/docs/customization/announcement-banner) | Theme | Announcement banner |
+| [`metadata`](/learn/docs/configuration/site-level-settings#seo-metadata-configuration) | Theme | SEO metadata |
+| [`navigation`](/learn/docs/configuration/navigation) | Child repository | Tabs, sections, pages |
+| [`apis`](/learn/docs/api-references/overview) | Child repository | API references |
+| [`redirects`](/learn/docs/configuration/site-level-settings#redirects-configuration) | Child repository | Redirects |
+| [`versions`](/learn/docs/configuration/versions) | Child repository | Versions |
+| [`instances`](/learn/docs/configuration/site-level-settings#instances-configuration) | Child repository | Domain and URL |
+</StickyTable>
+
+## 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
+```
@@ -112,6 +112,10 @@ navbar-links:
   [`metadata` configuration](/learn/docs/getting-started/global-configuration#seo-metadata-configuration).
 </ParamField>
 
+<ParamField path="global-theme" type="string" required={false} toc={true}>
+  The name of a [global theme](/learn/docs/customization/global-themes) to apply to this site. The CLI fetches the named theme from Fern's registry at publish time and merges its branding fields (logo, colors, fonts, layout, CSS, JS, and more) into the local `docs.yml`. Use this to share a consistent visual identity across multiple documentation sites.
+</ParamField>
+
 <ParamField path="header" type="string" required={false} toc={true}>
   Path to a custom React component file (TSX or JSX) to replace Fern's default header. The component must have a default export. Learn more about [custom header and footer components](/learn/docs/customization/header-and-footer).
 </ParamField>