/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Project Structure

Project Structure

How to organize your Syntext documentation project.

3 min read

Syntext supports two project layouts to fit your workflow: standalone docs repositories and embedded documentation within existing codebases.

Standalone Layout

For dedicated documentation repositories:

text
my-docs/
├── syntext.json # Site configuration
├── docs/ # Documentation content
│ ├── index.mdx # Home page (/) — on v2 sites, without it / goes to the first page
│ ├── getting-started.mdx
│ └── guides/
│ ├── quickstart.mdx
│ └── advanced.mdx
├── public/ # Static assets
│ ├── favicon.ico
│ └── images/
│ └── hero.png
└── openapi.json # API spec (optional)

Best for:

•
Open-source project docs
•
Product documentation sites
•
Developer portals

Embedded Layout

For documentation inside an application repository:

text
my-api/
├── src/ # Application code
├── package.json
├── .syntext/ # Documentation root
│ ├── syntext.json
│ ├── docs/
│ │ ├── index.mdx
│ │ └── api-reference/
│ └── public/
│ └── openapi.json # Inside .syntext/, so stx deploy uploads it

Alternatively, use .stx/:

text
my-api/
├── src/
└── .stx/
├── syntext.json
└── docs/

Best for:

•
API documentation alongside API code
•
Libraries with integrated docs
•
Monorepos

File Conventions

docs/ Directory

The docs/ folder contains your MDX content files. The file structure determines URL paths:

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

text
my-docs/
├── syntext.json
├── index.mdx
├── getting-started.mdx
└── guides/
└── quickstart.mdx

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 PathURL
public/favicon.ico/favicon.ico
public/images/hero.png/images/hero.png
public/og-image.png/og-image.png
Note

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.

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:

json
{
"navigation": [
{
"group": "Getting Started",
"pages": ["index", "getting-started", "installation"]
},
{
"group": "Guides",
"pages": [
"guides/authentication",
"guides/pagination",
"guides/error-handling"
]
}
]
}

Tabs (Top Navigation)

For large documentation sites, use tabs to segment content:

json
{
"tabs": [
{ "name": "Guides", "url": "/guides", "icon": "book" },
{ "name": "API", "url": "/api-reference", "icon": "api" },
{ "name": "SDKs", "url": "/sdks", "icon": "code" }
]
}

Each tab can have its own navigation structure.

OpenAPI Specification

Place your OpenAPI spec at the project root:

text
my-docs/
├── syntext.json
├── openapi.json # or openapi.yaml
└── docs/

Or specify a custom path:

json
{
"openapi": "./specs/api.yaml"
}

Or a URL:

json
{
"openapi": "https://api.example.com/openapi.json"
}
Note

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:

json
{
"openapi": [
{ "path": "./specs/users.yaml", "prefix": "/api/users" },
{ "path": "./specs/orders.yaml", "prefix": "/api/orders" }
]
}

Versioning

Versioned docs (Pro plan) are listed under versioning.versions:

json
{
"versioning": {
"versions": [
{ "label": "v3", "branch": "main", "default": true },
{ "label": "v2", "branch": "v2" },
{ "label": "v1", "branch": "v1", "deprecated": true }
]
}
}

Each version maps to a git branch or tag. See Versioning.

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