Theming
Presets, appearance and token overrides — how to give your docs your brand's look, with contrast checks built in.
Syntext sites are customizable to match your brand without forking anything. A look is built in three layers, each one optional and each one overriding the last:
theme.appearance — single choices on top of the preset: accent, mode, fonts,
size, corners, density, width, the layout and component styles.themeOverrides — exact token values, for the cases a choice can't
express.The easiest way to work with all three is the
appearance editor in the dashboard
(Settings › Appearance): it shows a live preview and writes the
syntext.json changes for you, as a pull request.
1. Pick a preset
Doc engine v2 has eight presets — Workbench, Paper, Console, Atlas, Plain, Orbit, Grid and Margin. Each sets the fonts, accent, shell, header, navigation and the style of every component:
See Presets for what each one looks like. To share one
look across every project in your organization, save it as an
organization theme and use
"theme": "@your-org/brand".
"theme": "default" and "theme": "gravv" are the doc engine v1 themes. A
site on a v1 theme with no appearance block keeps the v1 renderer, and
everything in Typography and below still applies to it as
before. A preset name, an organization theme or an appearance block opts a
site in to v2 — see Opting in.
2. Change single choices with appearance
Every field is optional and works with every preset. The full list of fields
and values is in the appearance reference.
Header background and code corners
On Orbit the floating header lets the page scroll behind it. Any preset can do the same, or keep a band behind the header:
transparent keeps Orbit's island on its own background with the content
showing around it; on a full-width header bar the content shows through it,
blurred. solid puts a band behind the header, so text stops at its edge.
Without the setting, the island header is transparent and every other header
solid.
Code blocks follow the site's corners and their code style. To set their
corners on their own — code blocks, code tabs, request and response panels and
the copy and ask buttons — use codeRadius:
Values: site (default), none, small, medium, large. In the dashboard
both are under Settings › Appearance: Header background in Layout, next
to Header, and Code block corners in Components, next to Code blocks.
Brand colour
Set one accent, or a different one for dark mode. Everything else — link colour, hover, tints, the text on buttons — is derived from it per mode, the way the preset derives its own:
Contrast
Syntext checks your accent against the page background in each mode:
| Check | What's measured | Needs |
|---|---|---|
| Links | The derived link colour on the page background | 4.5:1 (WCAG AA for text) |
| Fills | The accent itself — buttons, active states — on the page background | 3:1 (WCAG AA for controls) |
A colour that misses either check is never blocked. The build log warns and suggests the nearest shade of your accent that passes, and keeps your colour:
The appearance editor shows the same checks as you pick a colour, with a
one-click fix, and stx check --explain appearance prints them locally. A
very light accent usually passes in dark mode and fails in light mode — set
accent to { "light", "dark" } to use a darker shade in light mode only.
Dark mode
appearance.mode sets the mode a first-time reader sees: light, dark, or
system to follow their operating system. Readers can switch with the
light/dark toggle, and their choice is remembered. Set "toggle": false to
remove the toggle and pin the site to mode.
On v1 sites, the toggle is controlled by
features.themeToggle — deprecated:
it stays a warning on v1 and moves to appearance.toggle when the site switches
to v2.
3. Exact values with themeOverrides
themeOverrides sets individual tokens by name — colours per mode, fonts,
named text styles and corner radii:
On a v2 site it applies on top of appearance. Not every v1 token has a v2
equivalent — the token map
lists which ones change v2 pages and which are ignored. On v1 sites it applies
on top of the v1 theme, and every token in this guide is available.
The full order, including organization themes and the legacy colors and
fonts blocks, is in Precedence.
Legacy brand colours
The colors block is deprecated. Use
appearance.accent on v2, or themeOverrides on v1. stx migrate moves it
for you.
| Property | Use instead |
|---|---|
primary | appearance.accent (v2) — on v1 it stays a warning until the site moves to v2 |
accent | themeOverrides.colors.{light,dark}.accent-strong |
background | themeOverrides.colors.{light,dark}.bg-page |
colors is applied after themeOverrides, so an existing site never changes
because a preset was introduced.
Typography
Font roles
A theme sets three font roles. Every named text style refers to one of them, so changing a role restyles everything that uses it.
| Role | Used by | default theme (v1) |
|---|---|---|
display | H1–H4 | Inter |
body | Body copy, navigation, labels, captions | Inter |
mono | Code blocks, inline code | JetBrains Mono |
A theme is free to make body monospace — the gravv theme (v1) sets body, nav and
labels in Geist Mono, with only headings in a display face.
Custom fonts
Families are fetched from Google Fonts automatically. When one family serves two roles, it appears once in the request with the weights unioned.
For more control, pass an object:
Load only the weights you use — each extra weight is bytes on the wire. If a named style needs a weight the family does not load, the browser synthesizes it and the result looks subtly wrong.
To self-host a face, set webfont: "self-hosted" (or "system" for a family
the reader's device already has) so no Google Fonts request is made for it.
On doc engine v2, appearance.fonts loads any Google Fonts family by name, and
only the three families in use are fetched.
Named text styles
Each style carries family role, weight, size, line-height and letter-spacing.
size and letterSpacing are px. lineHeight is px when greater than 4,
a unitless multiplier at 4 or below, or "normal".
The multiplier form matters for inheritance, not just notation. A unitless line-height is recomputed from each element's own font size, while a px value is inherited as-is — so a px line-height on body copy also sets the leading of tables, cards and code inside it. Figma reports px; hand-written CSS usually means a multiplier.
Letter-spacing from Figma needs converting. Figma lets a text style express
letter-spacing in either pixels or percent, but its API reports the bare number
with the unit stripped — a style set to 7% and a style set to 7px both come
across as 7.
Copied straight into letterSpacing, a percent value lands as pixels. On small
text the result is dramatic: 7 on an 11px label is 64% tracking, roughly double
the intended width, and it looks like a rendering fault rather than a
mis-transcribed number.
Check the unit in Figma's type panel before copying. Where it reads percent,
convert it: letterSpacing = size x percent / 100. An 11px label at 7% is
0.77.
Available styles: display-h1, heading-h2, heading-h3, heading-h4,
body-lg, body-md, body-sm, label-md, label-sm, strong-sm, strong-md,
code-md, code-sm, caption, eyebrow, nav-item, nav-section,
mono-label, card-title.
The API-reference scale
API reference pages carry more structure per screen than a guide, so they can run
a denser type scale. Set it with apiTypography, which takes the same style names
and applies scoped to that surface only — guide pages keep the base scale.
A partial patch inherits everything it does not restate from the base scale, so
overriding just size keeps the family, weight and tracking. Sites that want one
scale everywhere simply omit the block.
Logo
Add your logo for light and dark modes:
Place logo files in your public/ directory. On doc engine v2 sites the
header, menu and footer show the dark logo in dark mode.
For a single logo that works on both backgrounds:
Favicon
Every page links it, on doc engine v1 and v2. Only a single URL is used — an object of sizes is accepted but ignored.
Code Theme
Syntax colours come from the theme's syntax-* tokens:
bg-code and bg-code-header set the code surface itself, and content-code
sets inline code. A theme may keep code surfaces dark in both modes — the gravv
theme (v1) does.
The codeTheme key is accepted but has no effect. Code colours are fixed
when your site is built, so custom CSS can't change them afterwards — set them
with the syntax-* tokens above instead.
Custom CSS
customCSS in syntext.json is accepted but not applied by hosted builds.
Put your CSS in _syntext/*.css in your docs folder — up to 50 KB, loaded
after the theme on every page — see Custom code from your docs.
Pasted CSS still works under Integrations › Custom code › Override (advanced)
(Starter plan and up) and applies last; saving it redeploys the site.
On doc engine v2 sites, style with the supported --stx-* variables and
data-stx hooks — page and header backgrounds (gradients included), colours,
fonts, corners and widths, in light and dark mode. See
Custom CSS for the full reference and examples.
Available CSS variables (doc engine v1)
On doc engine v1 sites every token is emitted as a CSS custom property, so your
custom CSS can reference the resolved theme instead of hardcoding values. Doc
engine v2 pages don't use these names — see
Coming from doc engine v1. Colours are emitted twice — once on
:root for light mode and once under [data-theme="dark"].
Use them like any custom property:
Older variable names (--primary, --bg, --text, --border, --font-sans)
are still emitted as aliases onto the tokens above, so existing custom CSS
keeps working. Prefer the --color-* names for anything new.
Custom JavaScript
scripts and customJS in syntext.json are accepted but not applied by
hosted builds. Put analytics and other head tags in _syntext/head.html and
scripts in _syntext/*.js, then have a workspace admin turn on Head tags from
your docs and Scripts from your docs under Integrations › Custom code —
see Custom code from your docs. Pasted snippets
still work under Override (advanced) (Starter plan and up): up to 10
Head snippets and 10 Body snippets, 10 KB each, each with a name and an
Active switch. Saving them redeploys the site.
Top Banner
Display announcements or promotional banners:
Footer
On doc engine v1, every page ends with a full-width footer band. By default it shows your social links and a "Powered by Syntext" credit, which links to the Syntext dashboard at app.syntext.dev. Add footer.columns for a rich footer with your logo and grouped link columns. On doc engine v2 the footer appears only when footer.columns has entries — your logo, GitHub, X and LinkedIn icons, a copyright line and a "Built with Syntext" link:
Relative URLs stay on your doc site; on v1, absolute URLs open in a new tab. See the footer reference for details.
Social Links
Add social links. On doc engine v1 they appear at the top of the sidebar and in the footer. On doc engine v2, GitHub, X and LinkedIn appear as footer icons when the footer has columns.
Platforms with icons on v1: GitHub, X, Discord, LinkedIn, YouTube, Slack. v2 shows GitHub, X (or Twitter) and LinkedIn.