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

stx dev

Deploy a preview build and redeploy it as you edit.

3 min read

Deploy a preview build of your documentation to Syntext, then watch your files and redeploy the preview each time you save. There is no local server — pages are built on Syntext's servers, so the preview renders exactly like production.

Usage

bash
stx dev [options]

Options

FlagAliasTypeDefaultDescription
--dir <dir>-dstring.Documentation directory
--branch <branch>stringdevBranch name for the preview
--token <token>stringLogin token or project API key (overrides stx login)

Examples

Start Preview

bash
stx dev

Deploys to https://dev--<slug>-docs.syntext.dev — for a project with the slug my-docs, https://dev--my-docs-docs.syntext.dev. With --branch, the branch name replaces dev; a very long branch name is shortened so the address stays valid (see Branch Preview). The command prints the URL to open.

How it works

File watching

stx dev watches:

•
your pages — everything in docs/, or, when your pages sit next to syntext.json, the project folder (except node_modules/, .git/, build output and dot files)
•
public/
•
your _syntext/ folder — docs/_syntext/, or _syntext/ at the project root
•
your config file (syntext.json, syntext.yaml, syntext.yml, stx.json, stx.yaml or stx.yml)
•
the OpenAPI specs the openapi key names — or openapi.json, openapi.yaml or openapi.yml at the project root

Each preview uploads the same files as stx deploy; see What gets uploaded.

Changes are batched for 800 ms, then every file is uploaded again and the preview is rebuilt on the server. Refresh the page to see the new build.

Build errors

If a build fails, the spinner stops with the server's error message. The full build log is in the dashboard under Deployments. stx dev keeps watching, so the next save tries again.

Custom code in previews

CSS from _syntext/ and page css: files applies in the preview. Scripts and head.html never run in previews, even when their switches are on, so when your project has them stx dev prints:

text
Note: _syntext/*.js and head.html never run in previews (CSS does). On the live site they run only when "Scripts from your docs" / "Head tags from your docs" are on in Integrations › Custom code.

See Previews.

Draft pages

draft: true works the same in a preview as in production: the page leaves the sidebar and is marked noindex, but its URL still opens.

mdx
---
title: Work in Progress
draft: true
---

Output

text
Watching . for changes...
Branch: dev
✔ Deployed (5321ms)
Preview: https://dev--my-docs-docs.syntext.dev
Press Ctrl+C to stop.

Each save prints a new Deployed line once the rebuild finishes.

Troubleshooting

No config

text
No syntext.json found in this directory.
Run `stx init` to create a new documentation project.

Run stx dev from the folder that holds your docs, or pass --dir.

Not Authenticated

text
Not authenticated. Run `stx login` first, or pass --token.

Run stx login to authenticate with your Syntext account.

Not linked to a project

text
No projectId in syntext.json.
Run `stx connect <projectId>` to link this directory to a project.

Link the folder with stx connect, or create and link a project with stx init --create.

File Changes Not Detected

If file watching stops working:

1.
Check your file system supports inotify/FSEvents
2.
Restart stx dev
3.
On Linux, you may need to increase the watch limit:
bash
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext