docs.json

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:

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

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

{
  "cloud": {
    "enabled": true,
    "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

Set cloud.enabled to false when the repo is using docs.json only as a local project contract. Set it to true once the repo is actually connected to Docs Cloud services.

Compatibility

docs.json is the canonical config name and contract going forward.

Older repos that still use docs.cloud.json, docs.framework, or top-level preview and publish can still be read for compatibility, but new examples and generated configs should use the docs.mode, docs.runtime, and cloud.* shape shown here.

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.