# docs.json
URL: /docs/guides/docs-json
LLM index: /llms.txt
Description: How the shared docs.json contract separates docs structure from Docs Cloud services
Related: /docs/guides, /docs/cloud, /docs/configuration, /docs/cli

# docs.json

Use this page when the user asks about this topic: How the shared docs.json contract separates docs structure from Docs Cloud services.
Keep answers grounded in the exact options, routes, commands, and examples documented here.
If the request moves beyond this page, point to the closest related docs instead of inventing config.

Use `docs.json` when you want a repo-level contract for frameworkless docs or for connecting
an existing docs app to Docs Cloud services.

The important split is:

- `docs` describes how the docs project is structured
- `cloud` describes hosted Docs Cloud services layered on top

## Project Shape

For frameworkless docs:

```json
{
  "$schema": "https://docs.farming-labs.dev/schema/docs.json",
  "version": 1,
  "docs": {
    "mode": "frameworkless",
    "runtime": "nextjs",
    "root": ".docs/site"
  },
  "content": {
    "docsRoot": "docs",
    "apiReferenceRoot": "api-reference"
  }
}
```

For a framework-owned docs app:

```json
{
  "$schema": "https://docs.farming-labs.dev/schema/docs.json",
  "version": 1,
  "docs": {
    "mode": "framework",
    "runtime": "nextjs",
    "root": "apps/docs"
  }
}
```

`mode` tells you whether content is authored as plain folders or inside a framework app.
`runtime` tells you which docs runtime is responsible for rendering it, and it is meant to stay an
explicit choice in the contract rather than being implied.

## Cloud Services

Hosted features live under `cloud`:

```json
{
  "cloud": {
    "analytics": {
      "enabled": true,
      "console": "info",
      "includeInputs": false
    },
    "preview": {
      "enabled": true
    },
    "publish": {
      "mode": "draft-pr",
      "baseBranch": "main"
    },
    "ai": {
      "enabled": true
    },
    "deploy": {
      "enabled": true
    }
  }
}
```

This keeps product packaging separate from docs structure:

- `frameworkless` is an authoring mode
- `nextjs` is a runtime
- Docs Cloud is the hosted layer that can add preview, publish, AI, and deploy services

## Cloud Analytics

Use `cloud.analytics` when you want the shared repo contract to carry analytics settings for Docs
Cloud and for frameworkless generated runtimes.

```json
{
  "cloud": {
    "analytics": true
  }
}
```

Or, when you need the serializable subset:

```json
{
  "cloud": {
    "analytics": {
      "enabled": true,
      "console": "info",
      "includeInputs": false
    }
  }
}
```

`cloud.analytics` is intentionally limited to JSON-safe options:

- `enabled`
- `console`
- `includeInputs`

Function hooks such as `onEvent` still belong in `docs.config.ts`, because `docs.json` is a repo
contract and not an executable config file.

For frameworkless projects, this serializable subset can be materialized into the generated hidden
runtime even before the repo is fully connected to hosted Docs Cloud services. For framework-owned
apps, `docs.config.ts` remains the canonical place for advanced runtime analytics behavior.

The presence of a `cloud` block opts the project into Cloud-aware CLI flows. Leave
`cloud.enabled` unset for normal connected projects. Set it to `false` only when the repo is using
`docs.json` as a local project contract and should explicitly disable Cloud previews and publish
commands.

To connect a repo, create an API key, and request hosted previews, see
[Docs Cloud](/docs/cloud).

## Current Note

This example uses `nextjs`, but the config shape keeps `docs.runtime` explicit so the same contract
can support other runtimes too.

When using `pnpm exec docs dev` today, the local frameworkless preview is still generated through
the Next.js runtime.