/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
CLI CLI Reference stx build

stx build

Build your documentation on Syntext's servers and download the static site for self-hosting.

3 min read

Compile your documentation into a fully static site you can host anywhere. The build runs on Syntext's servers — the same build that powers stx deploy — but instead of publishing to Syntext hosting, the compiled files are returned to you. It uploads the same files as stx deploy — your pages, from docs/ or the project root, your _syntext/ custom code and the OpenAPI specs syntext.json names; see What gets uploaded.

Usage

bash
stx build [options]

Requires authentication (stx login) and a connected project (stx connect), since the build runs on Syntext's servers.

Options

FlagAliasTypeDefaultDescription
--dir-dstring.Documentation directory
--output-ostringdistOutput directory for the built site
--tokenstringLogin token or project API key (for CI, overrides stx login)
--jsonbooleanfalseMachine-readable JSON output

Examples

Standard Build

bash
stx build

Uploads your source files, builds on the server, and downloads the result to ./dist/.

Custom Output Directory

bash
stx build --output ./public

CI Usage

bash
stx build --token $SYNTEXT_TOKEN --json

Output Structure

text
dist/
├── index.html
├── getting-started.html # one .html per page
├── getting-started.md # Markdown export per page
├── guides/
│ ├── quickstart.html
│ └── quickstart.md
├── api-reference/
│ └── *.html
├── ask.html # full-page AI chat route
├── 404.html
├── _assets/
│ └── search-index.json # static search index
├── llms.txt
├── llms-full.txt
├── sitemap.xml
├── robots.txt
├── _headers
├── _redirects
└── (your public/ assets)

Pages are emitted as flat .html files (for example guides/quickstart.html serves /guides/quickstart). Configure your host to resolve extensionless URLs — for Nginx:

Note

_headers and _redirects are emitted in the Cloudflare Pages / Netlify format so a self-hosted deploy can use them. Syntext hosting does not read either file — hosted sites get their own cache and security headers, and literal redirects resolve through the stub pages the build generates. They matter only when you host the output yourself.

nginx
location / {
try_files $uri $uri/ $uri.html =404;
}

Build Output

text
stx build
✔ Build complete!
Build: a1b2c3d4
Output: dist/
Files: 212 (3801 KB)
Pages: 97
Duration: 24810ms
Serve it with any static host, e.g. npx serve dist

Waiting behind another build

stx build waits its turn with deploys, so if another build of the project is running — a webhook build of a merge, or an stx deploy — your build waits for it, and the spinner names it, e.g. Waiting for build 1a2b3c4d (a push, commit abc1234, compiling) to finish....

The CLI waits up to 20 minutes in the queue, then up to 10 minutes for your build itself once it starts. If either wait runs out, the CLI stops waiting and exits with code 1 without downloading anything; the build itself keeps going on the server. If the build is cancelled, the CLI stops with the server's reason. This needs CLI v0.8.1 or later (brew upgrade stx).

Search Index

Every build includes _assets/search-index.json — a static index of all page content — so self-hosted sites can run search without calling the Syntext API.

Warning

Client-side search works well for small-to-medium sites (under 500 pages). For larger sites, consider a dedicated search service on your own host.

Validation

Builds run the same checks as deploys. Broken internal links are reported as warnings in the build output, and compile errors fail the build. To validate without building:

bash
stx check

Self-Hosting

The build output is fully static and can be deployed anywhere:

•
Cloudflare Pages
•
Netlify
•
AWS S3 + CloudFront
•
GitHub Pages
•
Nginx / Apache

See the Self-Hosted deployment guide for host-specific instructions.

Note

For managed hosting with custom domains, analytics, and instant cache invalidation, use stx deploy instead.

Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext