Skip to content

Commit 5ee9b8d

Browse files
devalogdevalog
authored
docs: restructure, add cross-references to global themes documentation (#5196)
1 parent cb9f536 commit 5ee9b8d

7 files changed

Lines changed: 138 additions & 122 deletions

File tree

‎fern/docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,8 @@ redirects:
427427
destination: /learn/docs/customization/custom-react-components
428428

429429
# Docs customization
430+
- source: /learn/docs/configuration/global-themes
431+
destination: /learn/docs/customization/global-themes
430432
- source: /learn/docs/customization/custom-header-and-footer
431433
destination: /learn/docs/customization/header-and-footer
432434
- source: /learn/docs/customization/changelogs

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -825,7 +825,7 @@ hideOnThisPage: true
825825

826826
<Accordion title="fern docs theme export">
827827

828-
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`.
828+
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`.
829829

830830
<CodeBlock title="terminal">
831831
```bash
@@ -847,7 +847,7 @@ hideOnThisPage: true
847847

848848
<Accordion title="fern docs theme upload">
849849

850-
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.
850+
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.
851851

852852
<CodeBlock title="terminal">
853853
```bash
@@ -875,7 +875,7 @@ hideOnThisPage: true
875875

876876
<Accordion title="fern docs theme list">
877877

878-
Use `fern docs theme list` to list all themes uploaded for your organization.
878+
Use `fern docs theme list` to list all [themes](/learn/docs/customization/global-themes) uploaded for your organization.
879879

880880
<CodeBlock title="terminal">
881881
```bash

‎fern/products/docs/docs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,6 @@ navigation:
4242
- page: Page-level settings
4343
path: ./pages/navigation/frontmatter.mdx
4444
slug: page-level-settings
45-
- page: Global themes
46-
path: ./pages/configuration/global-themes.mdx
4745
- section: Writing content
4846
contents:
4947
- page: Markdown basics
@@ -266,6 +264,8 @@ navigation:
266264
path: ./pages/customization/custom-react-components.mdx
267265
- page: Header and footer
268266
path: ./pages/customization/custom-header-footer.mdx
267+
- page: Global themes
268+
path: ./pages/customization/global-themes.mdx
269269
- section: Localization
270270
collapsed: true
271271
availability: pre-release

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
tags: ["configuration"]
2+
tags: ["configuration", "docs.yml"]
33
---
44

55
## Global themes
66

77
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.
88

9-
<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/configuration/global-themes">Read the docs</Button>
9+
<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/customization/global-themes">Read the docs</Button>

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

Lines changed: 0 additions & 115 deletions
This file was deleted.

‎fern/products/docs/pages/customization/global-themes.mdx‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Global themes
3+
subtitle: Share a consistent visual identity across multiple documentation sites.
4+
description: Learn how to use global themes to define branding in one repository and apply it automatically across child documentation sites.
5+
---
6+
7+
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.
8+
9+
This is useful when your organization maintains multiple documentation sites that should share the same branding.
10+
11+
## Set up a global theme
12+
13+
<Steps>
14+
15+
<Step title="Export a theme from your control repository">
16+
17+
From the repository that defines your canonical branding, [export](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-export) the theme:
18+
19+
```bash
20+
fern docs theme export
21+
```
22+
23+
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.
24+
25+
Use `--output` to specify a different directory:
26+
27+
```bash
28+
fern docs theme export --output ./my-theme
29+
```
30+
31+
</Step>
32+
33+
<Step title="Upload the theme">
34+
35+
[Upload](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-upload) the exported theme to Fern's registry:
36+
37+
```bash
38+
fern docs theme upload --name my-theme
39+
```
40+
41+
This uploads the theme configuration and all referenced file assets. If you omit `--name`, the theme is saved as `default`.
42+
43+
</Step>
44+
45+
<Step title="Confirm the upload">
46+
47+
[List](/learn/cli-api-reference/cli-reference/commands#fern-docs-theme-list) all themes for your organization:
48+
49+
```bash
50+
fern docs theme list
51+
```
52+
53+
Use `--json` for machine-readable output that includes `updatedAt` timestamps:
54+
55+
```bash
56+
fern docs theme list --json
57+
```
58+
59+
</Step>
60+
61+
<Step title="Reference the theme from a child repository">
62+
63+
In a child repository's `docs.yml`, add:
64+
65+
```yaml docs.yml
66+
global-theme: my-theme
67+
```
68+
69+
</Step>
70+
71+
<Step title="Publish as normal">
72+
73+
Run the standard [publish command](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs) from the child repository:
74+
75+
```bash
76+
fern generate --docs
77+
```
78+
79+
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.
80+
81+
</Step>
82+
83+
</Steps>
84+
85+
## What the theme controls
86+
87+
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.
88+
89+
90+
<StickyTable>
91+
| Field | Owner | Description |
92+
| --- | --- | --- |
93+
| [`logo`](/learn/docs/configuration/site-level-settings#logo-configuration) | Theme | Brand logo images and link |
94+
| [`favicon`](/learn/docs/configuration/site-level-settings#favicon) | Theme | Browser tab icon |
95+
| [`background-image`](/learn/docs/configuration/site-level-settings#background-image-configuration) | Theme | Page background |
96+
| [`colors`](/learn/docs/configuration/site-level-settings#colors-configuration) | Theme | Accent and background colors |
97+
| [`typography`](/learn/docs/configuration/site-level-settings#typography-configuration) | Theme | Body, heading, and code fonts |
98+
| [`layout`](/learn/docs/configuration/site-level-settings#layout-configuration) | Theme | Sidebar width, content width, tab and searchbar placement |
99+
| [`theme`](/learn/docs/configuration/site-level-settings#theme-configuration) | Theme | Light/dark mode default |
100+
| [`settings`](/learn/docs/configuration/site-level-settings#settings-configuration) | Theme | Display settings |
101+
| [`integrations`](/learn/docs/configuration/site-level-settings#integrations-configuration) | Theme | Analytics and tracking |
102+
| [`css`](/learn/docs/customization/custom-css-js) | Theme | Custom stylesheets |
103+
| [`js`](/learn/docs/customization/custom-css-js) | Theme | Custom scripts |
104+
| [`header`](/learn/docs/configuration/site-level-settings#header) | Theme | Custom header component |
105+
| [`footer`](/learn/docs/configuration/site-level-settings#footer) | Theme | Custom footer component |
106+
| [`navbar-links`](/learn/docs/configuration/site-level-settings#navbar-links-configuration) | Theme | Top navigation links |
107+
| [`footer-links`](/learn/docs/configuration/site-level-settings#footer-links-configuration) | Theme | Footer navigation links |
108+
| [`ai-search`](/learn/docs/configuration/site-level-settings#ask-fern-configuration) | Theme | AI search configuration |
109+
| [`announcement`](/learn/docs/customization/announcement-banner) | Theme | Announcement banner |
110+
| [`metadata`](/learn/docs/configuration/site-level-settings#seo-metadata-configuration) | Theme | SEO metadata |
111+
| [`navigation`](/learn/docs/configuration/navigation) | Child repository | Tabs, sections, pages |
112+
| [`apis`](/learn/docs/api-references/overview) | Child repository | API references |
113+
| [`redirects`](/learn/docs/configuration/site-level-settings#redirects-configuration) | Child repository | Redirects |
114+
| [`versions`](/learn/docs/configuration/versions) | Child repository | Versions |
115+
| [`instances`](/learn/docs/configuration/site-level-settings#instances-configuration) | Child repository | Domain and URL |
116+
</StickyTable>
117+
118+
## Updating a theme
119+
120+
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.
121+
122+
```bash
123+
fern docs theme export
124+
fern docs theme upload --name my-theme
125+
```

‎fern/products/docs/pages/navigation/site-level-settings.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,10 @@ navbar-links:
112112
[`metadata` configuration](/learn/docs/getting-started/global-configuration#seo-metadata-configuration).
113113
</ParamField>
114114

115+
<ParamField path="global-theme" type="string" required={false} toc={true}>
116+
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.
117+
</ParamField>
118+
115119
<ParamField path="header" type="string" required={false} toc={true}>
116120
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).
117121
</ParamField>

0 commit comments

Comments
 (0)