/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Concepts How Syntext Works

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.

3 min read

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

text
Pages from the web editor · Markdown/MDX files · source code (optional)
│
▼
① Read your code ← only for source code: doc comments + @stx directives
│
▼
② Compile your pages ← MDX rendered, code blocks highlighted
│
▼
③ Build the site ← theme applied, navigation built, search updated
│
▼
④ Publish ← {slug}-docs.syntext.dev or your custom domain
│
▼
⑤ Update the assistant ← your published pages become its knowledge

A failed build can be retried safely — retrying never publishes a partial site or duplicates anything.

Core Entities

EntityWhat it is
OrganizationBilling boundary. Owns projects, members, and usage limits.
ProjectOne documentation site. Has a slug ({slug}-docs.syntext.dev), settings, API keys, and domains.
BuildOne 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).
PageA compiled MDX document. Editable via the web editor or your repo.
AudienceAn 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:

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

•
MDX pages rendered to HTML
•
Code blocks syntax-highlighted
•
{@embed symbolName} and {@embed src="path#symbol"} directives replaced with the annotated symbol's source as a highlighted code block (see Embedding Symbols)
•
Navigation built from syntext.json
•
Full-text search updated. Search switches to the new content only when the build finishes, so a build that fails partway through leaves the previous search results in place — never an empty search
•
OpenAPI specs (if configured) rendered as interactive endpoint pages

Step 4: Deploy

The site is published to a global CDN:

•
Default domain: {slug}-docs.syntext.dev
•
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

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

SurfaceUse it for
Web dashboardWriting and publishing in the browser, uploads, GitHub, deployments, insights, review workflow, integrations, settings
CLI (stx)Preview deploys, builds, deploys, checks, CI
REST APIAutomation and integrations
MCP serverDocs access from AI IDEs (Cursor, VS Code, Claude)
Note

New to Syntext? Start with the Quickstart — you'll have a live doc site in under five minutes.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext