stx build
Build your documentation on Syntext's servers and download the static site for self-hosting.
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
Requires authentication (stx login) and a connected project (stx connect), since the build runs on Syntext's servers.
Options
| Flag | Alias | Type | Default | Description |
|---|---|---|---|---|
--dir | -d | string | . | Documentation directory |
--output | -o | string | dist | Output directory for the built site |
--token | string | Login token or project API key (for CI, overrides stx login) | ||
--json | boolean | false | Machine-readable JSON output |
Examples
Standard Build
Uploads your source files, builds on the server, and downloads the result to ./dist/.
Custom Output Directory
CI Usage
Output Structure
Pages are emitted as flat .html files (for example guides/quickstart.html serves /guides/quickstart). Configure your host to resolve extensionless URLs — for Nginx:
_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.
Build Output
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.
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:
Self-Hosting
The build output is fully static and can be deployed anywhere:
See the Self-Hosted deployment guide for host-specific instructions.
For managed hosting with custom domains, analytics, and instant cache invalidation, use stx deploy instead.