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,
    "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.

{
  "cloud": {
    "enabled": true,
    "analytics": true
  }
}

Or, when you need the serializable subset:

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

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.

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.