diff --git a/website/app/docs/cloud/page.mdx b/website/app/docs/cloud/page.mdx new file mode 100644 index 00000000..fa10b1ef --- /dev/null +++ b/website/app/docs/cloud/page.mdx @@ -0,0 +1,204 @@ +--- +title: "Docs Cloud" +description: "Connect your docs project to Docs Cloud previews, API keys, and publish workflows" +icon: "cloud" +order: 3.6 +related: + - /docs/guides/docs-json + - /docs/configuration + - /docs/cli + - /docs/customization/analytics +--- + +# Docs Cloud + + +Use this page when the user asks about this topic: Connect an @farming-labs/docs project to Docs Cloud, create and store a Docs Cloud API key, sync docs.config.ts to docs.json, request hosted previews, or configure publish defaults. +Keep answers grounded in the exact commands and config shown here. Never suggest committing raw API key values to docs.config.ts, docs.json, or source control. +If the request is about the docs.json contract itself, point to /docs/guides/docs-json. If the request is about every config option, point to /docs/configuration. + + +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 + + + Docs Cloud is rolling out gradually. If your workspace does not have access yet, join the + [Cloud waitlist](/cloud#waitlist). Once access is enabled, create the API key from your Docs + Cloud project settings. + + +## 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: + +```bash title=".env.local" +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. + + + Keep the raw API key in `.env.local`, your shell, or CI secrets. `docs.config.ts` should only + name the environment variable, and `docs.json` should only contain that environment variable name. + + +## Configure `docs.config.ts` + +Add the `cloud` block to your docs config: + +```ts title="docs.config.ts" +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: + +| Mode | Meaning | +| --------------- | ---------------------------------------------------------------- | +| `"draft-pr"` | Create a draft pull request targeting `publish.baseBranch` | +| `"direct-commit"` | Commit directly to `publish.baseBranch` for trusted automation | + +## 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: + +```bash title="terminal" +pnpm exec docs cloud sync +``` + +This creates or updates `docs.json`: + +```json title="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: + +```bash title="terminal" +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: + +```bash title="terminal" +pnpm exec docs cloud preview +``` + +Use JSON output when another tool or CI job needs to read the preview URL: + +```bash title="terminal" +pnpm exec docs preview --json +``` + +## Useful Options + +| Command | Use it when | +| ------------------------------------ | ------------------------------------------------ | +| `pnpm exec docs cloud sync` | You only want to update `docs.json` | +| `pnpm exec docs preview` | You want to sync, validate the key, and preview | +| `pnpm exec docs cloud preview` | You prefer the explicit Cloud namespace | +| `pnpm exec docs preview --json` | CI or automation needs machine-readable output | +| `pnpm exec docs preview --config ` | Your config file is outside the project root | +| `pnpm exec docs preview --api-base-url ` | You are testing a staging or self-hosted Cloud API | + +`--api-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`: + +```bash title="terminal" +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: + +```bash title="terminal" +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](/docs/guides/docs-json) explains the repo-level contract that Cloud reads. +- [Configuration](/docs/configuration) lists the `cloud` config fields. +- [CLI](/docs/cli) covers the full command surface. +- [Cloud landing page](/cloud) explains the managed product direction and waitlist. diff --git a/website/app/docs/configuration/page.mdx b/website/app/docs/configuration/page.mdx index 25a7b99d..97104d30 100644 --- a/website/app/docs/configuration/page.mdx +++ b/website/app/docs/configuration/page.mdx @@ -141,6 +141,7 @@ All configuration lives in a single `docs.config.ts` file. | `pageActions` | `PageActionsConfig` | — | Copy Markdown, Open in LLM buttons | | `ai` | `AIConfig` | — | RAG-powered AI chat | | `search` | `boolean \| DocsSearchConfig` | `true` | Built-in simple search, Typesense, Algolia, or a custom adapter | +| `cloud` | `DocsCloudConfig` | — | Docs Cloud API key env, preview, and publish defaults mirrored into `docs.json` | | `llmsTxt` | `boolean \| LlmsTxtConfig` | `true` | Generated root and optional section-level `llms.txt` files with markdown page links | | `changelog` | `boolean \| ChangelogConfig` | `false` | Generated changelog feed and entry pages from dated MDX entries (Next.js) | | `mcp` | `boolean \| DocsMcpConfig` | enabled | Built-in MCP server over stdio, `/mcp`, and `/.well-known/mcp` | diff --git a/website/app/docs/guides/docs-json/page.mdx b/website/app/docs/guides/docs-json/page.mdx index 6c7e9607..06288586 100644 --- a/website/app/docs/guides/docs-json/page.mdx +++ b/website/app/docs/guides/docs-json/page.mdx @@ -3,6 +3,7 @@ title: "docs.json" description: "How the shared docs.json contract separates docs structure from Docs Cloud services" related: - /docs/guides + - /docs/cloud - /docs/configuration - /docs/cli order: 2 @@ -69,7 +70,6 @@ Hosted features live under `cloud`: ```json { "cloud": { - "enabled": true, "analytics": { "enabled": true, "console": "info", @@ -106,7 +106,6 @@ Cloud and for frameworkless generated runtimes. ```json { "cloud": { - "enabled": true, "analytics": true } } @@ -117,7 +116,6 @@ Or, when you need the serializable subset: ```json { "cloud": { - "enabled": true, "analytics": { "enabled": true, "console": "info", @@ -140,8 +138,13 @@ For frameworkless projects, this serializable subset can be materialized into th 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. +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 diff --git a/website/app/docs/page.mdx b/website/app/docs/page.mdx index 4624484d..4edd66bf 100644 --- a/website/app/docs/page.mdx +++ b/website/app/docs/page.mdx @@ -4,6 +4,7 @@ description: "An AI-native documentation framework that just works" related: - /docs/installation - /docs/guides + - /docs/cloud - /docs/configuration - /docs/customization/agent-primitive - /docs/customization/llms-txt @@ -62,7 +63,7 @@ docs files, scores agent-readiness, and reports GitHub annotations. Keep it as w ## Looking Ahead: Cloud -[Cloud](/cloud) is the infrastructure layer we are building around `@farming-labs/docs`. +[Docs Cloud](/docs/cloud) is the infrastructure layer we are building around `@farming-labs/docs`. **You ship the code and we write the docs for you.** @@ -72,6 +73,9 @@ Git as the source of truth. [Join the waitlist to be an early user →](/cloud#waitlist) +Already have access? Start with the [Docs Cloud integration guide](/docs/cloud) to create an API +key, sync `docs.json`, and request a hosted preview. + ## other docs frameworks? @@ -155,7 +159,7 @@ The CLI first asks **existing project or fresh?** — then (for existing) auto-d - [Guides](/docs/guides) — Long-form playbooks, starting with writing agent-friendly docs - [Token Efficiency](/docs/token-efficiency) — Why this is the most AI-friendly docs framework -- [Cloud](/cloud) — Where the managed infrastructure layer for humans and agents is heading +- [Docs Cloud](/docs/cloud) — Connect a docs project to hosted previews, API keys, and publish defaults - [Configuration](/docs/configuration) — Customize your theme, colors, typography, sidebar, and more - [Themes](/docs/themes) — Browse available themes and learn how to create your own - [Customization](/docs/customization) — Colors, typography, sidebar, AI chat, page actions diff --git a/website/docs.config.tsx b/website/docs.config.tsx index e99ff2f8..6e7d1808 100644 --- a/website/docs.config.tsx +++ b/website/docs.config.tsx @@ -34,6 +34,7 @@ import { ChartNoAxesColumn, DollarSign, Activity, + Cloud, } from "lucide-react"; import { SidebarThemeToggle } from "@/components/sidebar-theme-toggle"; import { Callout } from "@/components/ui/callout"; @@ -154,6 +155,7 @@ export default defineDocs({ arrowUpRight: , "chart-no-axes-column": , activity: , + cloud: , dollarSign: , }, github: {