How Syntext Works
How Syntext turns your pages — written in the editor, in Markdown or from your code — into a site with search, an assistant and analytics.
Syntext turns your pages — written in the editor, in Markdown or from your code — into a site with search, an assistant and analytics. Every input goes through the same build; this page walks through what happens so everything else in these docs clicks into place.
The Big Picture
A failed build can be retried safely — retrying never publishes a partial site or duplicates anything.
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 run of the steps above. Triggered by stx deploy, a git push, a PR, or the API. Moves through queued → uploading or cloning → parsing → compiling → deploying → deployed (or ends failed / cancelled). |
| 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 isolated per project: builds, search, the assistant's knowledge, and analytics never mix with another project's.
Step 1: Annotation Parsing
This step runs only when your project documents code — a site of guides, help articles or handbook pages starts at Step 2. When it runs, Syntext reads documentation directly from your source code using a two-tier system:
///, Javadoc, PHPDoc, and C# XML docs are parsed automatically. No code changes needed.@stx directives give you control over grouping, titles, examples, and cross-references. When present, they take priority.See the Annotation Reference for the full syntax.
Parsed symbols become API reference pages, grouped by @stx group (or @category in JSDoc). Each symbol's signature is recorded 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:
{@embed symbolName} and {@embed src="path#symbol"} directives replaced with the annotated symbol's source as a highlighted code block (see Embedding Symbols)syntext.jsonStep 4: Deploy
The site is published to a global CDN:
{slug}-docs.syntext.devDeploys are atomic — visitors never see a half-deployed site.
Step 5: AI Assistant
After each production deploy, the assistant learns your newly published content. It reads your pages section by section — each heading, and each <Update> entry, is a separate section it can cite.
When a visitor asks a question, the assistant finds the sections most relevant to it and answers only from those, citing the pages it used. It never answers from another project's content. Questions the AI can't answer confidently are tracked as documentation gaps in Insights › Assistant.
Where You Interact
| Surface | Use it for |
|---|---|
| Web dashboard | Writing and publishing in the browser, uploads, GitHub, deployments, insights, review workflow, integrations, settings |
CLI (stx) | Preview deploys, builds, deploys, checks, CI |
| REST API | Automation and integrations |
| MCP server | Docs access from AI IDEs (Cursor, VS Code, Claude) |
New to Syntext? Start with the Quickstart — you'll have a live doc site in under five minutes.