Organization themes
Save one look — a preset plus your appearance settings — and share it across every project in your organization, with versions you can follow or pin.
An organization theme is a saved, named look your organization's projects
can share: a preset, appearance settings and
themeOverrides. Change the theme once, and every project that follows it
picks up the change on its next build.
Use a theme in a project
Set theme in syntext.json to @<organization slug>/<theme slug>:
| Value | Behaviour |
|---|---|
"@acme/brand" | Follows the latest version. A new version reaches the site on its next build |
"@acme/brand@3" | Pinned to version 3. New versions don't change the site until you change the number |
Using an organization theme opts the site in to doc engine v2.
The site's own appearance and themeOverrides still apply on top of the
theme, so a project can adjust one thing without leaving it — see
Precedence.
Every build logs the version it used:
A project can only use its own organization's themes. A reference to another organization's theme, to a theme that doesn't exist, or to a version that doesn't exist never fails the build: the build log explains the problem and the site renders with the preset.
You can also pick a theme in the appearance editor: the Preset section and the preset gallery list your organization's themes, with Follow new versions or Pin to a version.
The theme library
Organization themes — open it with the Organization themes button on Settings › Appearance — lists every theme with its version, its preset, when it was last updated, and how many projects use it.
@acme/<slug>)."@acme/brand" value for syntext.json.appearance and
themeOverrides.Versions and projects
Every change to a theme's preset, appearance or overrides creates a new, immutable version; renaming a theme doesn't. Open a theme to see:
Compare two looks
Organization themes › Compare puts two looks side by side. Each side is an organization theme, one version of a theme, or a project's current look. Both previews show the same page and mode and scroll together; a project's side renders its own pages, as of its last publish. Below them, What differs lists every setting that is not the same — preset, accent per mode, fonts, size, density, corners, page width, header, navigation, sidebar folding, table of contents, callouts, code blocks, steps, cards, default mode, the reader's mode switch, illustrations, logo and overridden tokens. Switch between Only differences and All settings.
From a comparison an admin can Restore an older version of a theme, apply
a theme to the project it is compared with, or swap the sides. The address of
the page holds both sides (?a=brand&b=brand@2, or project:<id>), so a
comparison can be shared as a link.
Apply a theme to many projects
Open a theme and choose Apply to projects. Pick the projects, then choose:
Each project then gets its own pull request, commit or hosted save and its own result row. A failure shows its reason with Retry, or Retry as PR when a direct commit was refused. Stop after current stops before the next batch; keep the page open until every project has a result. Projects with an open pull request keep their old theme until it is merged. Members see the page read-only.
The same is available from the API:
Apply Organization Theme sets theme
on up to 50 projects per call, each following the latest version or
pinned to one. Every project gets its own pull request, commit or hosted
save — exactly what publishing from that project's appearance editor would
do, with that project's permission checks — and its own result, so one
project failing never stops the others.
Permissions
| Action | Who |
|---|---|
| See themes, versions and projects | Any member of the organization |
| Create, change, restore themes | Organization admins and the owner |
| Apply a theme to many projects | Organization admins and the owner — plus deploy rights on a project to commit or save there directly |
Theme identifiers
A theme slug uses lower-case letters, digits and hyphens, up to 48 characters, and can't start or end with a hyphen. It's generated from the name unless you set one, and must be unique in the organization.
API
Themes are managed with the Organization Themes API: list, create, get, update, versions, restore and apply.