Custom CSS
Restyle a doc engine v2 site with your own CSS — the supported variables and hooks, light and dark mode, and a gradient background example.
Presets, appearance
and themeOverrides cover
most looks. When you want something they can't express — a gradient page
background, a translucent header, a different card style — add your own CSS.
On doc engine v2 sites, custom CSS has a supported surface: a set of
--stx-* CSS variables and data-stx hook attributes that keep their names
from release to release. Write your CSS against them and it keeps working when
presets and components are updated.
Add your CSS
Put your CSS in a _syntext/ folder in your docs — docs/_syntext/style.css
— and publish. It's versioned and reviewed with your pages, and applies on
every page (all _syntext/*.css files together up to 50KB). For one page only,
add a stylesheet with css: in
its frontmatter. See Custom code from your docs
for the folder, the order the files apply in, and what's refused.
You can still paste CSS in the dashboard: Integrations › Custom code ›
Override (advanced) › Custom CSS (Starter plan and up, up to 50KB), or with
Update Pasted Custom Code (customCss).
Pasted CSS applies after the CSS from your docs. Move into your docs on the
same page moves it into _syntext/style.css.
Your CSS loads after the preset's own styles on every page, so a rule of
the same weight wins. That covers guide pages, the home page, API reference
pages, the changelog, wide pages, the 404 page, the /ask page, preview
deploys and the live preview in Settings › Appearance.
The sign-in, password and access-required pages get your CSS too (but not your
head and body snippets).
Prefer appearance for your brand colour. appearance.accent derives the
link colour, tints and the text on accent buttons from one value, and checks
their contrast. The --stx-color-accent* variables below set each one
separately and are not checked.
How the layers combine
Each layer overrides the one before it:
appearancethemeOverridescolors / fonts_syntext/*.css, then the page's css: file, then pasted Custom CSSEvery variable below starts at the value the first four layers resolve to, so you only set the ones you want to change.
Variables
Set variables on :root. A value set on :root applies in light and dark
mode; see Light and dark mode for one mode only.
Backgrounds
These take anything the CSS background property accepts: a colour, a
gradient, an image, and keywords such as fixed.
| Variable | What it paints |
|---|---|
--stx-page-bg | The page behind everything |
--stx-header-bg | The top bar, on desktop and phones |
--stx-sidebar-bg | The navigation sidebar |
--stx-content-bg | The column or sheet the page content sits on (in presets that draw one) |
--stx-toc-bg | The "On this page" column or card |
--stx-footer-bg | The site footer |
--stx-card-bg | Cards |
Colours
| Variable | Used for |
|---|---|
--stx-color-canvas | Page colour |
--stx-color-surface | Header, cards, menus and other raised surfaces |
--stx-color-panel | Subtle fills: hovered rows, inline panels |
--stx-color-border | Borders and dividers |
--stx-color-border-strong | Stronger borders |
--stx-color-text | Body text and headings |
--stx-color-text-secondary | Secondary text |
--stx-color-text-muted | Hints, captions and meta text |
--stx-color-accent | Accent fills: primary buttons, active markers |
--stx-color-accent-text | Links and accent text |
--stx-color-accent-tint | Accent-tinted backgrounds |
--stx-color-on-accent | Text on accent fills |
--stx-color-code-bg | Code block background |
--stx-color-code-text | Code block text |
--stx-color-code-border | Code block border |
--stx-color-success, -bg, -text | Success callouts and badges |
--stx-color-warning, -bg, -text | Warning callouts and badges |
--stx-color-danger, -bg, -text | Danger callouts and badges |
--stx-color-info, -bg, -text | Info callouts and badges |
Type
| Variable | Used for |
|---|---|
--stx-font-body | Body text |
--stx-font-heading | Headings |
--stx-font-mono | Code |
--stx-font-size | Body text size, e.g. 16px |
--stx-line-height | Body line height, e.g. 1.65 |
--stx-h1-size | Page title size |
A font you name here must be loaded: add an @import for it at the top of your
CSS, or a <link> in _syntext/head.html or a pasted head snippet. Fonts set with appearance.fonts are
loaded for you.
Shape and layout
| Variable | Used for |
|---|---|
--stx-radius-sm | Small corners: buttons, inputs, badges |
--stx-radius | Corners of cards, callouts and code blocks |
--stx-radius-lg | Large corners: panels and sheets |
--stx-header-height | Height of the top bar |
--stx-sidebar-width | Width of the sidebar |
--stx-content-width | Maximum width of the page content |
--stx-toc-width | Width of the "On this page" column |
Hooks
Every main region and component carries a data-stx attribute. Select on these
rather than on class names, which can change.
| Selector | Element |
|---|---|
[data-stx="banner"] | The announcement banner |
[data-stx="topbar"] | The company bar above the header (Atlas-style headers) |
[data-stx="header"] | The top bar |
[data-stx="sidebar"] | The navigation sidebar |
[data-stx="main"] | The main column |
[data-stx="surface"] | The sheet the content sits on (presets that draw one) |
[data-stx="content"] | The page content |
[data-stx="breadcrumbs"] | The breadcrumb trail |
[data-stx="toc"] | "On this page" |
[data-stx="page-footer"] | Feedback, edit link and previous / next |
[data-stx="footer"] | The site footer |
[data-stx="home"] | The home page body |
[data-stx="hero"] | The home hero and the <Hero> component |
[data-stx="card-group"], [data-stx="card"] | Card grids and cards |
[data-stx="callout"] | Callouts; data-stx-variant names the type (note, info, tip, warning, danger, success, important, security) |
[data-stx="code-block"] | Code blocks |
[data-stx="tabs"] | Tabs and code groups |
[data-stx="steps"] | Steps |
[data-stx="accordion-group"], [data-stx="accordion"] | Accordions |
The <html> element also says where you are:
| Attribute | Values |
|---|---|
data-theme | light or dark |
data-stx-preset | The preset: workbench, paper, console, atlas, plain, orbit, grid, margin |
data-stx-page | guide, home, api, changelog, wide, not-found, ask, state (sign-in, password and access pages) |
Light and dark mode
A variable on :root applies in both modes. For one mode only, use
html[data-theme="dark"] (or html[data-theme="light"]), which wins over
:root:
Example: a gradient background
A gradient behind the whole page, a see-through header that blurs what scrolls under it, and darker colours in dark mode:
fixed keeps the gradient still while the page scrolls. Presets that put the
content on a sheet or card (Paper, Atlas, Orbit) keep it on its own surface, so
text stays readable; set --stx-content-bg too if you want the gradient to
show through there as well.
More examples
Only the --stx-* variables, the data-stx* attributes and data-theme are
supported. Class names and other variables on the page are not, and can change
in any release.
Coming from doc engine v1
Doc engine v2 pages have new markup, so CSS written for v1 doesn't carry over:
v1 class names and the v1 --color-* variables do nothing on a v2 site. Move
your rules to the variables and hooks above — most v1 variables have a direct
match:
| v1 | v2 |
|---|---|
--color-bg-page | --stx-color-canvas (or --stx-page-bg) |
--color-bg-header | --stx-header-bg |
--color-bg-sidebar | --stx-sidebar-bg |
--color-bg-subtle | --stx-color-panel |
--color-content-primary | --stx-color-text |
--color-content-secondary | --stx-color-text-secondary |
--color-content-muted | --stx-color-text-muted |
--color-border | --stx-color-border |
--color-accent | --stx-color-accent |
--color-accent-strong | --stx-color-accent-text |
--color-accent-subtle | --stx-color-accent-tint |
--color-on-accent | --stx-color-on-accent |
--color-bg-code | --stx-color-code-bg |
Your CSS stays where it is — _syntext/*.css and the pasted Custom CSS
apply to both engines — so update it when you switch your site to a
preset, and check the result in a
preview deploy first.