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

Custom code from your docs

Ship site-wide CSS, head tags and scripts from a _syntext/ folder in your docs, add a stylesheet to one page with css, and control what runs with three switches.

13 min read

Put your site's custom CSS, head tags and scripts in a _syntext/ folder next to your pages. They're versioned with your docs, reviewed like any other change, and published with the rest of your site.

This is the recommended way to add custom code. Pasting code into the dashboard still works — it's now Override (advanced) under Integrations › Custom code — but code in your docs is easier to review, roll back and keep in step with your pages.

The _syntext/ folder

Create _syntext/ in your docs folder — docs/_syntext/ when your pages live in docs/, otherwise at the project root:

text
my-docs/
├── syntext.json
└── docs/
├── index.mdx
├── pricing.mdx
└── _syntext/
├── 01-base.css
├── 02-brand.css
├── head.html
└── app.js
FileWhat it does
*.cssSite-wide CSS, on every page. Several files are applied in file-name order — prefix them (01-, 02-) to control it
*.jsScripts added at the end of every page, in file-name order
head.htmlTags added to every page's <head>: analytics, verification and other <meta> tags, font <link>s

Only files directly inside _syntext/ count. Nothing in _syntext/ is ever a page: it isn't in the sidebar, search, the sitemap or the AI assistant.

When your pages live in docs/, a _syntext/ folder at the project root works too. If both exist, docs/_syntext/ is used and the root one is ignored with a warning.

Note

For the --stx-* variables and data-stx hooks to write your CSS against on doc engine v2 sites, see Custom CSS.

Get started

  1. 01Step 1 of 41 ›Step 11.
    Add your CSS

    Create docs/_syntext/style.css:

    css
    :root { --stx-radius: 6px; }
    [data-stx="header"] { backdrop-filter: blur(10px); }
  2. 02Step 2 of 42 ›Step 22.
    Check it

    Run stx check. It reports problems in the same words as a publish.

  3. 03Step 3 of 43 ›Step 33.
    Publish

    Push, publish or run stx deploy as you normally do. CSS from your docs is on by default, so the styles are live when the build finishes.

  4. 04Step 4 of 44 ›Step 44.
    Turn on head tags and scripts, if you use them

    head.html and *.js files are off until a workspace admin turns them on under Integrations › Custom code — see The three switches.

The three switches

Three switches at the top of Integrations › Custom code decide what your live site applies from your docs:

SwitchCoversDefault
CSS from your docs_syntext/*.css and every page's css: fileOn
Head tags from your docs_syntext/head.htmlOff
Scripts from your docs_syntext/*.js, <script> tags in head.html, and scripts in your pagesOff
•
Who can change them. Only workspace admins and owners. Every change is recorded in the project's audit log.
•
Off means ignored, not deleted. The files stay in your docs. The publish log names each skipped file — _syntext/app.js skipped: Scripts from your docs is off in Integrations › Custom code — and stx check warns the same for a linked project.
•
On applies on the next publish. Turning a switch on doesn't rebuild your site; push, publish or deploy to apply it.
•
Private sites ask first. On a site behind a password, invites or SSO, turning on head tags or scripts asks you to confirm, because those scripts can read everything a signed-in reader sees.
•
The AI connector can't change them. Only a person in the dashboard (or the API) can.
•
Head tags alone never run JavaScript. With Head tags from your docs on and Scripts from your docs off, head.html applies without its <script> tags, and the publish log says how many were skipped.

Order

Each layer comes after — and so overrides — the one before it.

CSS:

1.
The preset and your appearance styles
2.
_syntext/*.css, in file-name order
3.
The page's own css: file
4.
Pasted Custom CSS under Override (advanced) — always last

In <head>: _syntext/head.html, then pasted head snippets.

At the end of the page: _syntext/*.js, then pasted body snippets.

Scripts and instant navigation

On doc engine v2 sites, pages open in place: moving to another page doesn't reload it. Your _syntext/*.js files and pasted body snippets run once per visit, when the reader's first page loads, and keep running as they move between pages.

To do something on every page — record a page view, update a widget — listen for stx:navigate on document. It fires after the new page is in place:

js
document.addEventListener('stx:navigate', (event) => {
const { url, from, title } = event.detail
// url: the new page's full URL; from: the previous one; title: the new document title
window.gtag?.('event', 'page_view', { page_location: url, page_title: title })
})
•
It doesn't fire for the first page of a visit: run that code on load as well.
•
Elements your scripts add directly to <body> (a chat launcher, a cookie banner) stay across pages. Anything added inside the page itself is replaced with the next page, so add it again on stx:navigate.
•
To make a link load its page the usual way, give it data-stx-reload: <a href="/pricing" data-stx-reload>Pricing</a>.

Styles for one page

Add a stylesheet to a single page with css in its frontmatter:

mdx
---
title: Pricing
css: ./pricing.css
---
•
./pricing.css is relative to the page; /styles/pricing.css starts from the docs folder.
•
It must be a .css file inside your docs folder, at most 50KB.
•
It applies only to that page, after the site CSS.
•
It's CSS only, and follows the same rules as _syntext/*.css. It's covered by CSS from your docs.
•
Doc engine v1 and v2.

Previews

Previews never run head.html or scripts, even when their switches are on. CSS applies, so previews still look like your site. That covers:

•
branch and pull request previews
•
unpublished changes made through the AI connector
•
stx dev and stx deploy --preview
•
the appearance and doc engine v2 previews

The publish log of a preview says so for each file: _syntext/app.js skipped: head tags and scripts never run on previews.

Pasted head and body snippets under Override (advanced) don't run on previews either; the pasted Custom CSS does.

Every project works the same

Where your docs liveHow _syntext/ gets there
GitHubCommit the folder to your repository, like your pages
Written in SyntextThe files are stored in the project like pages. Create and edit them in the web editor
Published with the CLIstx deploy, stx build and stx dev upload _syntext/ with your pages (CLI v0.10.0 and later)

_syntext/ must be a real folder in your docs. A symbolic link to a folder elsewhere fails the publish.

Deploys from the CLI

head.html and scripts in an stx deploy go live only when the deploy is made by a workspace admin or owner, or with a full-access API key that an admin or owner created. Anyone else's deploy — including one with a build-only key — still publishes your pages and CSS, without head.html and scripts. The deploy answers with a custom_code_not_applied warning and the publish log names each skipped file. Promoting a preview and rolling back to an uploaded version follow the same rule.

Versioned docs

A version is built from its own branch or tag. head.html and scripts from it apply only when that branch or tag is the one your versioning configuration names for the version; CSS always applies.

Who can change what

Workspace admins and ownersOther members
_syntext/*.css and page css: filesYesYes
_syntext/*.js and _syntext/head.htmlYesNo
The three switchesYesNo
Pasted code under Override (advanced)YesNo
Move into your docsYesNo
head.html and scripts in an stx deployYesDeployed without them

This applies in the dashboard editor, through the API, through the AI connector, in content reviews, when importing files and when restoring an earlier version of your pages. A member who tries to change a script or head.html sees:

text
Only workspace admins can change scripts and head tags in _syntext/. Ask an admin, or put styles in a .css file.

Every change to a script or head.html is recorded in the audit log: who made it, when, the file and a short fingerprint of its content.

On GitHub projects, anyone who can push to the repository can change _syntext/. Turn on head tags and scripts only if you trust everyone who can.

Integrations › Custom code

The page in the dashboard has three parts:

1.
The three switches, at the top.
2.
Applied from your docs — what the last published site applied: each file, its size, a short fingerprint, its status (applied, off, or not run on previews) and, for scripts and head.html, the outside domains they load from.
3.
Override (advanced) — the pasted Custom CSS, head snippets and body snippets that used to be Custom scripts & CSS (Starter plan and up). They still apply last. Only workspace admins and owners can save them; the Custom CSS follows the CSS rules; on a private site, saving a new or changed snippet asks you to confirm first; and every save is recorded in the audit log with a short fingerprint of the code before and after.

Move into your docs

Workspace admins can move pasted code into your docs with Move into your docs on Integrations › Custom code:

Pasted codeGoes to
Custom CSS_syntext/style.css
Head snippets_syntext/head.html
Body snippets that are a plain inline <script>_syntext/script.js

Snippets that can't move as they are — a body snippet that isn't a plain inline script, a head snippet with tags head.html doesn't allow — and disabled snippets stay pasted, and the result names them.

What happens next depends on your project:

•
Written in Syntext — the files are created and the moved pasted code is cleared, in one step.
•
GitHub — a pull request is opened with the files. The pasted code stays as it is, so your site looks the same; remove it after you merge.
•
Published with the CLI — Syntext doesn't store your files, so move the code yourself: add the files to _syntext/ and run stx deploy.

If one of the files already exists in _syntext/, nothing moves and the message names it — rename or remove it first. Afterwards, the result tells you which switches to turn on for the moved code to apply.

In the editor

_syntext/ files show in the editor's file tree under Custom code, and New › Custom code creates style.css, script.js or head.html with starter content. CSS files get completions for the --stx-* variables and data-stx hooks, and every file is checked as you type with the same messages as a publish. See Custom code files.

From the CLI

stx check checks the folder and every page's css: with the same messages as a publish, and warns about scripts and head.html:

text
⚠ docs/_syntext/app.js: _syntext/app.js runs only when "Scripts from your docs" is on in Integrations › Custom code (off by default), and never on previews

stx dev uploads and watches _syntext/, and stx deploy and stx build upload it. Custom code needs CLI v0.10.0 or later.

From the AI connector

The hosted connector's update_page and edit_page can write _syntext/ files. CSS follows the same rules as pages; scripts and head.html only for workspace admins. Content is checked like a publish — a refusal starts with Nothing was saved: and gives the reason. The connector can't change the switches.

HTML in your pages

You can write HTML in any page — <div>, <span>, <img>, <video>, <audio>, <details>, <table>, <iframe> embeds (YouTube, Loom, CodeSandbox) and so on. It's published as you wrote it.

What can run code or take over the page is removed when the page is published, unless Scripts from your docs is on:

RemovedUnless
<script> tagsScripts from your docs is on
Event handlers such as onclick, onload, onerrorScripts from your docs is on
javascript:, vbscript: and data:text/html links and sources, including Markdown links like [x](javascript:…)Scripts from your docs is on
<iframe srcdoc>Scripts from your docs is on
<base>, <meta>, <object>, <embed>, <applet>, <frame>, <frameset>Always removed

Previews, the editor's Preview and Publish checks always remove scripts, whatever the switch says. Pages without any of these are published exactly as before.

The publish log names each page and what it lost:

text
guides/setup.mdx: removed onclick on <button>, <script> (scripts and event handlers in pages run only when "Scripts from your docs" is on in Integrations › Custom code, and never on previews)

To add behaviour to many pages, prefer a _syntext/*.js file over scripts in each page.

Limits

WhatLimit
All _syntext/*.css files together50KB
A page's css: file50KB
Scripts10 files, 10KB each
head.html10KB

What's refused and how to fix it

A file that breaks a rule fails the publish, and the message names the file. The editor, stx check and the AI connector show the same message.

CSS

_syntext/*.css, page css: files, and <style> in head.html.

MessageFix
combined CSS is 61.2KB; the limit is 50KBMove styles for single pages into their own css: files, or minify
CSS must not contain </style>Remove it — a .css file holds only CSS rules, no tags
CSS must not contain </head> or </body>Remove the tag
CSS must not use expression()Remove it; no current browser supports it
CSS must not contain javascript: or vbscript: URLsRemove the URL. Put scripts in a _syntext/*.js file. Escaped spellings count too
CSS must not use behavior or -moz-bindingRemove the property; no current browser supports it
CSS may load only https:// URLs (found "http://cdn.example.com/a.woff2")Load url(), @import, image-set() and src() from an https:// address, a relative path, or an image or font data: URI. The first such address is named

Scripts

MessageFix
12 scripts; the limit is 10Combine scripts into fewer files
script is 12.3KB; the limit is 10KBSplit it, or load a larger script from an https:// address with <script src> in head.html
JavaScript must not contain </script>In a string, write it as "<\/script>"
JavaScript must not contain </head> or </body>Remove it, or split the string the same way ("<\/body>")

head.html

head.html may contain only <meta>, <link>, <script>, <noscript> and <style>, each with its usual attributes plus id and data-*. It's checked the way a browser reads it, and what goes on your site is rewritten from that reading, so only the allowed tags and attributes reach your pages. Its <script> tags need Scripts from your docs on too.

MessageFix
head.html is 11.0KB; the limit is 10KBMove styles into _syntext/*.css and inline scripts into _syntext/*.js
head.html: <base> is not allowed (head.html may contain only <meta>, <link>, <script>, <noscript> and <style>)Remove the tag. The page title comes from each page's frontmatter
head.html: <meta http-equiv="refresh"> is not allowedUse redirects in syntext.json. http-equiv may be only content-type, default-style, x-ua-compatible or content-language
head.html: <link> must not have event handlers (found onload)Remove the handler. Put the code in a _syntext/*.js file
head.html: <meta> must not have the foo attributeRemove the attribute. Each tag takes its usual attributes, plus id and data-*
head.html may contain only elements (text outside them would start the page body)Remove the text, or put it in a <meta> or a comment
head.html must not contain malformed comments or CDATAWrite comments as <!-- … -->, and remove <![CDATA[. A <script> that contains <!-- together with <script reads this way too: move it to a _syntext/*.js file
head.html: <script src> may load only https:// URLs (found "http://…")Load scripts from https:// addresses or relative paths. <link href> gets the same message and fix
head.html must not contain </head>, <body> or <html>Keep only the tags themselves — Syntext adds them to the page's <head>

Any file

MessageFix
is not a text fileSave it as UTF-8 text. Images and fonts don't go in _syntext/
_syntext/ holds only .css files, .js files and head.html, directly inside it.Shown by the editor and connector. Move other files and subfolders out — publishes ignore them
_syntext/ must be a real folder in your docs, not a symbolic linkReplace the link with the folder itself

Page css:

MessageFix
css "../../x.css" points outside the docs folderPoint to a file inside your docs folder
css "https://cdn.example.com/x.css" must be a path to a .css file in the docs folder, not a URLCopy the file into your docs, or @import it from a _syntext/*.css file
css "./x.css": file not found (x.css in the docs folder)Check the path: ./ is relative to the page, / starts at the docs folder
css "./x.css": the file is 50.1KB; the limit is 50KBTrim the file, or move shared rules into _syntext/*.css
css "./x.js" must point to a .css fileOnly stylesheets — put scripts in _syntext/*.js
•
Custom CSS — the --stx-* variables and data-stx hooks for doc engine v2
•
Frontmatter — the css key
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext