/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Custom CSS

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.

6 min read

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).

Note

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:

1.
The preset
2.
appearance
3.
themeOverrides
4.
Legacy colors / fonts
5.
Your custom CSS — _syntext/*.css, then the page's css: file, then pasted Custom CSS

Every 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.

css
:root {
--stx-radius: 6px;
--stx-color-accent: #0e7490;
}

Backgrounds

These take anything the CSS background property accepts: a colour, a gradient, an image, and keywords such as fixed.

VariableWhat it paints
--stx-page-bgThe page behind everything
--stx-header-bgThe top bar, on desktop and phones
--stx-sidebar-bgThe navigation sidebar
--stx-content-bgThe column or sheet the page content sits on (in presets that draw one)
--stx-toc-bgThe "On this page" column or card
--stx-footer-bgThe site footer
--stx-card-bgCards

Colours

VariableUsed for
--stx-color-canvasPage colour
--stx-color-surfaceHeader, cards, menus and other raised surfaces
--stx-color-panelSubtle fills: hovered rows, inline panels
--stx-color-borderBorders and dividers
--stx-color-border-strongStronger borders
--stx-color-textBody text and headings
--stx-color-text-secondarySecondary text
--stx-color-text-mutedHints, captions and meta text
--stx-color-accentAccent fills: primary buttons, active markers
--stx-color-accent-textLinks and accent text
--stx-color-accent-tintAccent-tinted backgrounds
--stx-color-on-accentText on accent fills
--stx-color-code-bgCode block background
--stx-color-code-textCode block text
--stx-color-code-borderCode block border
--stx-color-success, -bg, -textSuccess callouts and badges
--stx-color-warning, -bg, -textWarning callouts and badges
--stx-color-danger, -bg, -textDanger callouts and badges
--stx-color-info, -bg, -textInfo callouts and badges

Type

VariableUsed for
--stx-font-bodyBody text
--stx-font-headingHeadings
--stx-font-monoCode
--stx-font-sizeBody text size, e.g. 16px
--stx-line-heightBody line height, e.g. 1.65
--stx-h1-sizePage 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

VariableUsed for
--stx-radius-smSmall corners: buttons, inputs, badges
--stx-radiusCorners of cards, callouts and code blocks
--stx-radius-lgLarge corners: panels and sheets
--stx-header-heightHeight of the top bar
--stx-sidebar-widthWidth of the sidebar
--stx-content-widthMaximum width of the page content
--stx-toc-widthWidth 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.

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

AttributeValues
data-themelight or dark
data-stx-presetThe preset: workbench, paper, console, atlas, plain, orbit, grid, margin
data-stx-pageguide, home, api, changelog, wide, not-found, ask, state (sign-in, password and access pages)
css
/* Only on the home page */
html[data-stx-page="home"] [data-stx="hero"] h1 { letter-spacing: -0.03em; }
/* Warning callouts with a thicker edge */
[data-stx="callout"][data-stx-variant="warning"] { border-left-width: 4px; }

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:

css
:root { --stx-color-code-bg: #f6f8fa; }
html[data-theme="dark"] { --stx-color-code-bg: #0d1117; }

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:

css
:root {
--stx-page-bg: linear-gradient(160deg, #e0f2fe 0%, #fdf4ff 55%, #fef3c7 100%) fixed;
--stx-header-bg: rgb(255 255 255 / 0.6);
}
html[data-theme="dark"] {
--stx-page-bg: linear-gradient(160deg, #0b1b2b 0%, #1d1030 60%, #2a1a0a 100%) fixed;
--stx-header-bg: rgb(12 18 30 / 0.6);
}
[data-stx="header"] { backdrop-filter: blur(10px); }

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

css
/* Square cards with a softer fill */
:root {
--stx-card-bg: var(--stx-color-panel);
--stx-radius: 0;
}
/* A tinted header with a stronger bottom edge */
:root { --stx-header-bg: var(--stx-color-accent-tint); }
[data-stx="header"] { border-bottom: 2px solid var(--stx-color-accent); }
/* A different heading font */
@import url("https://fonts.googleapis.com/css2?family=Fraunces:wght@600&display=swap");
:root { --stx-font-heading: "Fraunces", serif; }
/* No previous / next or feedback row under pages */
[data-stx="page-footer"] { display: none; }
Warning

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:

v1v2
--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.

•
Custom code from your docs — where your CSS goes, the order and the rules
•
Theming — presets, appearance and themeOverrides
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext