Project Structure
How to organize your Syntext documentation project.
Syntext supports two project layouts to fit your workflow: standalone docs repositories and embedded documentation within existing codebases.
Standalone Layout
For dedicated documentation repositories:
Best for:
Embedded Layout
For documentation inside an application repository:
Alternatively, use .stx/:
Best for:
File Conventions
docs/ Directory
The docs/ folder contains your MDX content files. The file structure determines URL paths:
| File Path | URL |
|---|---|
docs/index.mdx | / |
docs/getting-started.mdx | /getting-started |
docs/guides/quickstart.mdx | /guides/quickstart |
docs/api-reference/users/create.mdx | /api-reference/users/create |
Pages at the project root
Pages can also sit next to syntext.json, without a docs/ folder:
Syntext uses docs/ when it has .md or .mdx pages at its top level, otherwise the project root. Builds from a connected repository and stx deploy, stx build and stx dev all follow this rule, so your pages are uploaded and built either way. At the project root, node_modules/, .git/, build output folders (dist/, .next/, out/, build/), dot folders and anything your .gitignore ignores are skipped, and .env files, keys and credential files are never uploaded. See What gets uploaded.
public/ Directory
Static assets are served from public/:
| File Path | URL |
|---|---|
public/favicon.ico | /favicon.ico |
public/images/hero.png | /images/hero.png |
public/og-image.png | /og-image.png |
Files in public/ are copied as-is to the build output. Use this for images, favicons, and other static files.
syntext.json
The configuration file at the root of your docs folder. See Configuration Reference for all options.
Navigation
Automatic Navigation
By default, navigation is generated from your file structure. Files are sorted alphabetically, with index.mdx first.
Manual Navigation
Override with the navigation field in syntext.json:
Tabs (Top Navigation)
For large documentation sites, use tabs to segment content:
Each tab can have its own navigation structure.
OpenAPI Specification
Place your OpenAPI spec at the project root:
Or specify a custom path:
Or a URL:
A URL entry works for builds from a connected Git repository. stx deploy, stx build and stx dev upload only local spec files — a path in openapi can point to any folder in your project — so with the CLI keep the spec in your project, or register the URL in the dashboard.
Multiple APIs
For microservices or multi-API products:
Versioning
Versioned docs (Pro plan) are listed under versioning.versions:
Each version maps to a git branch or tag. See Versioning.