---
title: stx build
description: Build your documentation on the Syntext backend and download the static site for self-hosting.
icon: hammer
---

# stx build

Compile your documentation into a fully static site you can host anywhere. The build runs on the Syntext backend — the same pipeline that powers `stx deploy` — but instead of publishing to Syntext hosting, the compiled files are returned to you.

## Usage

```bash
stx build [options]
```

Requires authentication (`stx login`) and a connected project (`stx connect`), since compilation happens server-side.

## Options

| Flag | Alias | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--dir` | `-d` | string | `.` | Documentation directory |
| `--output` | `-o` | string | `dist` | Output directory for the built site |
| `--token` | | string | | Auth token (for CI, overrides login) |
| `--json` | | boolean | `false` | Machine-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

```
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:

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

## Build Output

```
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
```

## 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.

<Callout type="warning">
  Client-side search works well for small-to-medium sites (under 500 pages). For larger sites, consider hosting your own Meilisearch instance.
</Callout>

## 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](/deployment/self-hosted) for host-specific instructions.

<Note>
For managed hosting with custom domains, analytics, and instant cache invalidation, use `stx deploy` instead.
</Note>