docs.jsonCopy Anchor Link

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 ShapeCopy Anchor Link

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.

OpenAPI entriesCopy Anchor Link

Each entry in content.openapi[] describes one API reference. Fields:

catalogTargets — when to set itCopy Anchor Link

catalogTargets declares which product API base URLs the OpenAPI document describes. The runtime uses these to populate the RFC 9727 /.well-known/api-catalog endpoint, associating the OpenAPI document with each URL via service-desc.

You only need catalogTargets when path is an absolute remote URL. For remotely hosted schemas, the schema URL is not the same as the API URL, so the runtime has no way to infer a target automatically.

• Same-origin or relative path values default to ["/"] — no extra configuration needed.
• Absolute remote path values (e.g. https://schemas.example.com/product.json) have no default. Set catalogTargets explicitly.
• An explicit empty array [] disables catalog association entirely.

{
  "content": {
    "openapi": [
      {
        "name": "Core API",
        "path": "https://schemas.example.com/product.openapi.json",
        "route": "/api-reference",
        "catalogTargets": [
          "https://api.acme.dev/v1"
        ]
      }
    ]
  }
}

For a local schema file, omit catalogTargets:

{
  "content": {
    "openapi": [
      {
        "name": "Core API",
        "path": "api/openapi.json",
        "route": "/api-reference"
      }
    ]
  }
}

Cloud ServicesCopy Anchor Link

Hosted features live under cloud:

{
  "cloud": {
    "analytics": {
      "enabled": true,
      "console": "info",
      "includeInputs": false
    },
    "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

Theme names, CSS imports, and component styling belong in docs.config.ts and the framework theme packages. Keep docs.json focused on repo shape and hosted Cloud services so the contract stays runtime-neutral.

Cloud AnalyticsCopy Anchor Link

Use cloud.analytics when you want the shared repo contract to carry analytics settings for Docs Cloud and for frameworkless generated runtimes. Connected Cloud projects use these settings with the Cloud-provided project identity so events are stored by Docs Cloud without requiring an onEvent callback in the repo.

{
  "cloud": {
    "analytics": true
  }
}

Or, when you need the serializable subset:

{
  "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. Use onEvent only when you want to send an extra copy to a tool you own; Cloud storage is handled by the managed Cloud delivery path.

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 deploy and publish commands.

To connect a repo, create an API key, and deploy hosted preview docs, see Docs Cloud and Deploy. For hosted analytics storage, see Docs Cloud Analytics.

Current NoteCopy Anchor Link

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.