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.
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:
| File | What it does |
|---|---|
*.css | Site-wide CSS, on every page. Several files are applied in file-name order — prefix them (01-, 02-) to control it |
*.js | Scripts added at the end of every page, in file-name order |
head.html | Tags 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.
For the --stx-* variables and data-stx hooks to write your CSS against on
doc engine v2 sites, see Custom CSS.
Get started
- 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); } - 02Step 2 of 42 ›Step 22.Check it
Run
stx check. It reports problems in the same words as a publish. - 03Step 3 of 43 ›Step 33.Publish
Push, publish or run
stx deployas you normally do. CSS from your docs is on by default, so the styles are live when the build finishes. - 04Step 4 of 44 ›Step 44.Turn on head tags and scripts, if you use them
head.htmland*.jsfiles 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:
| Switch | Covers | Default |
|---|---|---|
| CSS from your docs | _syntext/*.css and every page's css: file | On |
| Head tags from your docs | _syntext/head.html | Off |
| Scripts from your docs | _syntext/*.js, <script> tags in head.html, and scripts in your pages | Off |
_syntext/app.js skipped: Scripts from your docs is off in Integrations › Custom code —
and stx check warns the same for a linked project.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:
_syntext/*.css, in file-name ordercss: fileIn <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:
<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.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:
./pricing.css is relative to the page; /styles/pricing.css starts from
the docs folder..css file inside your docs folder, at most 50KB._syntext/*.css. It's covered by CSS from your docs.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:
stx dev and stx deploy --previewThe 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 live | How _syntext/ gets there |
|---|---|
| GitHub | Commit the folder to your repository, like your pages |
| Written in Syntext | The files are stored in the project like pages. Create and edit them in the web editor |
| Published with the CLI | stx 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 owners | Other members | |
|---|---|---|
_syntext/*.css and page css: files | Yes | Yes |
_syntext/*.js and _syntext/head.html | Yes | No |
| The three switches | Yes | No |
| Pasted code under Override (advanced) | Yes | No |
| Move into your docs | Yes | No |
head.html and scripts in an stx deploy | Yes | Deployed 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:
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:
head.html, the outside
domains they load from.Move into your docs
Workspace admins can move pasted code into your docs with Move into your docs on Integrations › Custom code:
| Pasted code | Goes 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:
_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:
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:
| Removed | Unless |
|---|---|
<script> tags | Scripts from your docs is on |
Event handlers such as onclick, onload, onerror | Scripts 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:
To add behaviour to many pages, prefer a _syntext/*.js file over scripts in
each page.
Limits
| What | Limit |
|---|---|
All _syntext/*.css files together | 50KB |
A page's css: file | 50KB |
| Scripts | 10 files, 10KB each |
head.html | 10KB |
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.
| Message | Fix |
|---|---|
combined CSS is 61.2KB; the limit is 50KB | Move 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: URLs | Remove the URL. Put scripts in a _syntext/*.js file. Escaped spellings count too |
CSS must not use behavior or -moz-binding | Remove 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
| Message | Fix |
|---|---|
12 scripts; the limit is 10 | Combine scripts into fewer files |
script is 12.3KB; the limit is 10KB | Split 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.
| Message | Fix |
|---|---|
head.html is 11.0KB; the limit is 10KB | Move 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 allowed | Use 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 attribute | Remove 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 CDATA | Write 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
| Message | Fix |
|---|---|
is not a text file | Save 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 link | Replace the link with the folder itself |
Page css:
| Message | Fix |
|---|---|
css "../../x.css" points outside the docs folder | Point 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 URL | Copy 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 50KB | Trim the file, or move shared rules into _syntext/*.css |
css "./x.js" must point to a .css file | Only stylesheets — put scripts in _syntext/*.js |
Related
css key