/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Platform Organization themes

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.

4 min read

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

json
{
"theme": "@acme/brand"
}
ValueBehaviour
"@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:

text
Organization theme @acme/brand: version 4 (latest)

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.

•
New theme — give it a name, pick a preset to start from, and create it as version 1.
•
Save as organization theme — from a project's appearance editor, saves that project's current preset and appearance settings as a new theme. Choose a name and an identifier (the slug in @acme/<slug>).
•
Copy reference — copies the "@acme/brand" value for syntext.json.
•
Export JSON — downloads the theme's preset, 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:

•
Version history, newest first, with who made each version and a diff against the one before
•
Restore — copies an old version into a new latest version, so the history is never rewritten
•
Projects using the theme, each marked Follows latest or Pinned to vN. The list is updated by each project's production builds, and when a theme is published from the appearance editor

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:

•
Version: follow the latest, or pin any version, for all projects or per project.
•
How changes land: a pull request per project (the default), or Commit where I can deploy. Projects where you lack deploy rights still get a pull request; hosted projects always save directly.

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

ActionWho
See themes, versions and projectsAny member of the organization
Create, change, restore themesOrganization admins and the owner
Apply a theme to many projectsOrganization 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.

•
Custom CSS — style a v2 site beyond the preset with --stx-* variables and data-stx hooks
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext