---
title: Project Structure
description: How to organize your Syntext documentation project.
icon: folder
---

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

<Note>
Files in `public/` are copied as-is to the build output. Use this for images, favicons, and other static files.
</Note>

### syntext.json

The configuration file at the root of your docs folder. See [Configuration Reference](/configuration/syntext-json) 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`:

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

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

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

Enable versioned docs with the `versions` field:

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

Each version maps to a git branch.