docs: add global themes documentation page and CLI command reference (#5170)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: aditya-arolkar-swe

fern/products/cli-api-reference/pages/commands.mdx

@@ -27,6 +27,9 @@ hideOnThisPage: true
 | [`fern docs preview list`](#fern-docs-preview-list) | List all preview deployments |
 | [`fern docs preview delete`](#fern-docs-preview-delete) | Delete a preview deployment |
 | [`fern docs md check`](#fern-docs-md-check) | Validate MDX syntax in documentation files |
+| [`fern docs theme export`](#fern-docs-theme-export) | Export theme-eligible fields from `docs.yml` into a standalone directory |
+| [`fern docs theme upload`](#fern-docs-theme-upload) | Upload a theme to Fern's registry |
+| [`fern docs theme list`](#fern-docs-theme-list) | List all themes for your organization |
 
 ## SDK generation commands  
 
@@ -819,4 +822,84 @@ hideOnThisPage: true
     - `response.body` → `responses.<status>.content.*.example`
 
   </Accordion>
+
+  <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`.
+
+    <CodeBlock title="terminal">
+    ```bash
+    fern docs theme export [--output <directory>]
+    ```
+    </CodeBlock>
+
+    By default, files are written to `./fern/theme/`.
+
+    ### output
+
+    Use `--output` to specify a custom directory for the exported theme.
+
+    ```bash
+    fern docs theme export --output ./my-theme
+    ```
+
+  </Accordion>
+
+  <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.
+
+    <CodeBlock title="terminal">
+    ```bash
+    fern docs theme upload [--name <name>] [--org <org>]
+    ```
+    </CodeBlock>
+
+    ### name
+
+    Use `--name` to set the theme name. Defaults to `default`.
+
+    ```bash
+    fern docs theme upload --name my-theme
+    ```
+
+    ### org
+
+    Use `--org` to override the organization ID from `fern.config.json`.
+
+    ```bash
+    fern docs theme upload --org my-org
+    ```
+
+  </Accordion>
+
+  <Accordion title="fern docs theme list">
+
+    Use `fern docs theme list` to list all themes uploaded for your organization.
+
+    <CodeBlock title="terminal">
+    ```bash
+    fern docs theme list [--json] [--org <org>]
+    ```
+    </CodeBlock>
+
+    By default, outputs one theme name per line.
+
+    ### json
+
+    Use `--json` to output the full list as a JSON array, including `updatedAt` timestamps.
+
+    ```bash
+    fern docs theme list --json
+    ```
+
+    ### org
+
+    Use `--org` to override the organization ID from `fern.config.json`.
+
+    ```bash
+    fern docs theme list --org my-org
+    ```
+
+  </Accordion>
 </AccordionGroup>

fern/products/docs/docs.yml

@@ -42,6 +42,8 @@ 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

fern/products/docs/pages/changelog/2026-04-27.mdx

@@ -0,0 +1,9 @@
+---
+tags: ["configuration"]
+---
+
+## 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>

fern/products/docs/pages/configuration/global-themes.mdx

@@ -0,0 +1,115 @@
+---
+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.
+
+## 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
+```