---
title: How Syntext Works
description: "The mental model behind Syntext — from code annotations to a deployed doc site with an AI assistant."
---

# How Syntext Works

Syntext turns your codebase and Markdown content into a complete documentation site — with search, an AI assistant, and analytics — through a single build pipeline. This page explains the mental model so everything else in these docs clicks into place.

## The Big Picture

```
Source code + MDX content
        │
        ▼
  ① Annotation parsing        ← doc comments + @stx directives extracted
        │
        ▼
  ② MDX compilation           ← unified/remark/rehype + Shiki highlighting
        │
        ▼
  ③ Static site generation    ← theme applied, navigation built, search indexed
        │
        ▼
  ④ Deploy to CDN             ← {slug}-docs.syntext.dev or your custom domain
        │
        ▼
  ⑤ AI indexing               ← content chunked, embedded, stored per-project
```

Every step is **idempotent** — a failed build can be retried at any stage without side effects.

## Core Entities

| Entity | What it is |
|--------|-----------|
| **Organization** | Billing boundary. Owns projects, members, and usage limits. |
| **Project** | One documentation site. Has a slug (`{slug}-docs.syntext.dev`), settings, API keys, and domains. |
| **Build** | One pipeline run. Triggered by `stx deploy`, a git push, a PR, or the API. Has status `queued → building → deployed` (or `failed` / `canceled`). |
| **Page** | A compiled MDX document. Editable via the web editor or your repo. |
| **Audience** | An access tier for gated content (e.g. partners-only pages). |

Everything is tenant-scoped: builds, search indexes, AI embeddings, and analytics are isolated per project.

## Step 1: Annotation Parsing

Syntext reads documentation **directly from your source code** using a two-tier system:

1. **Zero-config** — existing JSDoc, Python docstrings, Go doc comments, Rust `///`, Javadoc, PHPDoc, and C# XML docs are parsed automatically. No code changes needed.
2. **Enhanced** — optional `@stx` directives give you control over grouping, titles, examples, and cross-references. When present, they take priority.

See the [Annotation Reference](/concepts/annotations) for the full syntax.

Parsed symbols become API reference pages, grouped by `@stx group` (or `@category` in JSDoc). Signature hashes are stored for **drift detection** — when code changes but docs don't, `stx check` flags it.

## Step 2–3: Compile & Generate

Your hand-written MDX (in `docs/`) and the generated API reference are compiled together:

- MDX → HTML via unified + remark + rehype
- Code blocks highlighted with Shiki
- `{@embed symbolName}` directives resolved inline from parsed symbols
- Navigation built from `syntext.json`
- Full-text search index generated (Meilisearch)
- OpenAPI specs (if configured) rendered as interactive endpoint pages

## Step 4: Deploy

The static site is uploaded to object storage and served through an edge network:

- Default domain: `{slug}-docs.syntext.dev`
- [Custom domains](/guides/custom-domains) via automatic SSL
- Preview builds get isolated preview URLs (PRs trigger these automatically)

Deploys are atomic — visitors never see a half-deployed site.

## Step 5: AI Assistant (RAG)

After each production deploy, content is:

1. **Chunked** by heading
2. **Embedded** via OpenAI embeddings
3. **Stored** in a per-project vector namespace (pgvector)

When a visitor asks the AI assistant a question, relevant chunks are retrieved by cosine similarity and fed to the model with citations. Questions the AI can't answer confidently are tracked as **documentation gaps** in your [analytics dashboard](/platform/analytics).

## Where You Interact

| Surface | Use it for |
|---------|-----------|
| [CLI (`stx`)](/cli/overview) | Local dev server, builds, deploys, CI |
| [Web dashboard](https://syntext.dev) | Analytics, collaboration, settings, the web editor |
| [REST API](/api-reference/overview) | Automation and integrations |
| [SDKs](/sdks/overview) | Typed API access from TypeScript, Go, or Python |
| [MCP server](/guides/mcp-integration) | Docs access from AI IDEs (Cursor, VS Code, Claude) |

<Note>
New to Syntext? Start with the [Quickstart](/guides/quickstart) — you'll have a live doc site in under five minutes.
</Note>