Guides
View as Markdown Open in ChatGPT Open in Claude

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

Where You Interact

Surface Use it for
CLI (stx) Local dev server, builds, deploys, CI
Web dashboard Analytics, collaboration, settings, the web editor
REST API Automation and integrations
SDKs Typed API access from TypeScript, Go, or Python
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.
Was this page helpful?