Project Structure

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

Standalone Layout

For dedicated documentation repositories:

my-docs/
├── syntext.json    # Site configuration
├── docs/                  # Documentation content
│   ├── index.mdx          # Home 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:

my-api/
├── src/                   # Application code
├── package.json
├── .syntext/              # Documentation root
│   ├── syntext.json
│   ├── docs/
│   │   ├── index.mdx
│   │   └── api-reference/
│   └── public/
└── openapi.json           # Can be at repo root

Alternatively, use .stx/:

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

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.

By default, navigation is generated from your file structure. Files are sorted alphabetically, with index.mdx first.

Override with the navigation field in syntext.json:

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

For large documentation sites, use tabs to segment content:

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

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

Or specify a custom path:

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

Or a URL:

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

Multiple APIs

For microservices or multi-API products:

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

Versioning

Enable versioned docs with the versions field:

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

Each version maps to a git branch.