Docs Cloud

Docs Cloud is the hosted layer around @farming-labs/docs. Your repo stays the source of truth, your app still owns the runtime, and Cloud adds managed previews, publish workflows, analytics, AI, search, and agent operations on top.

The first integration surface is the Cloud preview flow:

1. create a Docs Cloud API key
2. store the key in an environment variable
3. add a serializable cloud block to docs.config.ts
4. sync that config into docs.json
5. request a hosted preview

Create An API Key

In Docs Cloud, open your workspace, choose the docs project, then create a project API key from the project settings. For previews, the key needs access to read the project and request previews.

Copy the key once and put it in your local environment:

DOCS_CLOUD_API_KEY=docs_cloud_...

Use the same environment variable name as a CI secret when previews should run from GitHub Actions or another build system.

Configure docs.config.ts

Add the cloud block to your docs config:

import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  cloud: {
    apiKey: { env: "DOCS_CLOUD_API_KEY" },
    preview: { enabled: true },
    publish: { mode: "draft-pr", baseBranch: "main" },
  },
});

cloud.apiKey.env defaults to DOCS_CLOUD_API_KEY, but writing it explicitly makes the contract clear for teammates and CI.

publish.mode is the default Cloud should use when generated docs changes need to go back to Git:

Sync docs.json

docs.json is the serializable project contract that Docs Cloud reads. It mirrors safe project metadata from docs.config.ts; it does not store API key values.

Run:

pnpm exec docs cloud sync

This creates or updates docs.json:

{
  "$schema": "https://docs.farming-labs.dev/schema/docs.json",
  "version": 1,
  "docs": {
    "mode": "framework",
    "runtime": "nextjs",
    "root": "."
  },
  "content": {
    "docsRoot": "docs"
  },
  "cloud": {
    "apiKey": {
      "env": "DOCS_CLOUD_API_KEY"
    },
    "preview": {
      "enabled": true
    },
    "publish": {
      "mode": "draft-pr",
      "baseBranch": "main"
    }
  }
}

Commit docs.json when you want the Cloud contract to be reviewed with the repo. The file is safe to commit because it contains only configuration and environment variable names.

The generated cloud block intentionally omits enabled. The block itself opts the project into Cloud-aware CLI flows; set "enabled": false only when you need to disable Cloud operations while keeping the rest of the contract in place.

Request A Preview

Use docs preview from the project root:

pnpm exec docs preview

docs preview does three things:

1. syncs docs.config.ts into docs.json
2. validates the configured API key with Docs Cloud
3. requests a hosted preview deployment

The explicit Cloud command is equivalent:

pnpm exec docs cloud preview

Use JSON output when another tool or CI job needs to read the preview URL:

pnpm exec docs preview --json

Useful Options

--api-key <key> also exists for local testing, but prefer cloud.apiKey.env plus an environment variable so the key does not end up in shell history, logs, or docs.

Troubleshooting

Missing API key

If the CLI says the Docs Cloud API key is missing, set the env var named by cloud.apiKey.env:

export DOCS_CLOUD_API_KEY=docs_cloud_...

or add it to .env.local.

Preview disabled

If cloud.preview.enabled is false, docs preview stops before making a hosted preview request. Set it back to true or remove the override.

Wrong Cloud host

For staging or self-hosted testing, pass:

pnpm exec docs preview --api-base-url https://cloud.example.com

You can also set DOCS_CLOUD_API_URL in the environment.

Related Docs

• docs.json explains the repo-level contract that Cloud reads.
• Configuration lists the cloud config fields.
• CLI covers the full command surface.
• Cloud landing page explains the managed product direction and waitlist.