Deployment Overview
Deploy your documentation to Syntext's global CDN or self-host.
Syntext offers multiple deployment options: managed hosting on our global CDN, CI/CD integration, or self-hosted deployment.
Managed Hosting
The easiest option. Deploy with a single command:
Your docs are instantly available at your-project-docs.syntext.dev.
Features
docs.yourcompany.comDeployment Options
Quick Start
First Deployment
Install the CLI:
Log in or create an account:
Deploy:
Subsequent Deployments
Just run stx deploy again. The CLI handles building and uploading.
Preview Deployments
Test changes without affecting production:
Without --branch, the preview goes to preview--your-project-docs.syntext.dev, shared by every branchless preview.
Branch Previews
Creates feature-new-api--your-project-docs.syntext.dev. A branch too long to fit one 63-character DNS label is shortened and ends in a short code — see Branch Preview.
Environment Configuration
API Key
Locally, stx login is enough. In CI, pass a project API key with --token — the CLI does not read a key from the environment:
Project Configuration
The CLI reads project configuration from syntext.json. No additional setup needed.
Deployment Status
Open your project → Deployments in the dashboard. The Serving production card shows what the site runs right now, and the list shows every build with its status; a running build shows pages compiled so far (for example 88/142). From the API, use List Builds and Get Build.
Monthly build quota
Every build counts toward your plan's monthly build quota — from the dashboard, the CLI, the API, or a push or pull request on a connected GitHub repository. Once the quota is used up, a push or pull request isn't built: it appears in the build list as failed with Monthly build limit reached (100/100). Upgrade your plan for more builds., and your build.failed webhook fires. Builds start again next month or after you upgrade; push again, or start the build from the dashboard, to publish what you missed.
Cancelling a build
Choose Cancel on a running build's row, or Cancel build on its page. A build can be cancelled until it starts publishing (deploying); production is not changed. From the API, use Cancel Build.
Build order
Builds of one project run one at a time. A build started while another is running — say, stx deploy right after a merge whose webhook build is still compiling — waits as queued, and Get Build reports the build it is waiting on as queuedBehind.
The newest request always wins production. A production build never publishes over a production build that was requested later and is already live: it stops without publishing and ends as cancelled, with the reason Superseded: build <id> was requested later and is already live, so this build did not publish. Order is decided by when each build was requested, not by commit date, so a rollback or promote still replaces anything requested before it. Previews, versioned builds and stx build exports are never superseded.
Rollbacks
To put an earlier production version back live, open Deployments, choose Roll back on a build that deployed (or on the Serving production card), and confirm Roll back production. From the API, use Roll Back Deployment.
stx deploy can only be rebuilt from the newest upload on their branch; for older ones, redeploy that version from the CLI.An instant rollback never races a build: while a build of the project is running, or a production build is queued, it is refused (409 build_in_progress) and nothing changes. Cancel that build from Deployments — or wait for it — then roll back. A production build you start after a rollback replaces it when it deploys, like any newer deploy.
You can also restore an earlier version the usual ways:
Promote queues a new production build from the files that preview was deployed with, and counts toward the build quota.
Self-Hosting
Build a static site and host anywhere:
Deploy the dist/ folder to:
Self-hosted deployments don't include AI search, analytics, or the embedded AI assistant. These features require the managed platform.
Performance
Managed sites are served from a global CDN, close to your readers:
Caching
Your site's responses carry cache headers by asset type. There is no purge step on deploy — the rules are chosen so none is needed.
At the edge, Cloudflare answers repeat requests from its cache in each region: content-addressed assets under one key per file, and pages under a key that includes the deploy they belong to. A new deploy therefore never reuses a page cached for an older one.
| What | Cache-Control | Revalidates |
|---|---|---|
Content-addressed assets (/_assets/*, and any file with a hash in its name) | public, max-age=31536000, immutable | Never — a new build writes a new filename |
Everything else: HTML pages, sitemap.xml, llms.txt, images and fonts you ship in public/ | public, max-age=0, must-revalidate | On every request |
Every response carries an ETag, so a revalidation that finds nothing changed
is answered with a 304 Not Modified and no body. Revalidating is cheap; the
full document is re-sent only when it has actually changed.
The practical consequence: a deploy is live within seconds. A deploy
(or an instant rollback) switches your whole site over at once. Each region
re-checks which deploy is live at least once a second while it is serving
your site, and never trusts its answer for more than 10 seconds, so readers
see the new version within a few seconds at most. Neither the browser nor the
CDN keeps a page from one deploy once the site has switched to another. If
you still see old content after that, it is not caching. Check that the build
finished and reached the deployed state.
Every response also carries an X-Deploy-Id header naming the deploy it was
served from, which is the quickest way to confirm which build you are looking
at:
Pages and assets also carry a Server-Timing header. Its cache;desc=hit,
miss or bypass entry says whether the edge answered from its cache, and
edge;dur is the time in milliseconds the edge spent on the request.
Sites using access control — password, invite, SSO, or any deploy containing
audience-gated pages — are served private, no-store and are never held in a
shared cache, so a page rendered for a signed-in reader can never be replayed
to an anonymous one. Preview deployments are not held in the edge cache
either.