# Experiment Documentation Guide (/reference/experiment-docs) Every worker under `apps/experiments//` should have a matching docs page at `/experiments/`. This guide explains structure, conventions, and the automation available to contributors and agents. ## Where docs live [#where-docs-live] | Artifact | Path | | ------------- | ---------------------------------------------------- | | MDX page | `apps/docs/content/docs/experiments/.mdx` | | Sidebar order | `apps/docs/content/docs/meta.json` | | Docs app | `apps/docs/` (Fumadocs + Next.js) | | Worker source | `apps/experiments//` | | Root index | `README.md` experiments table (new experiments only) | Docs are **not** generated automatically on deploy. When you add or change an experiment, update its MDX page in the same PR (or immediately after). ## Quick start: new experiment [#quick-start-new-experiment] ### Scaffold the MDX file [#scaffold-the-mdx-file] From the repository root: ```bash node apps/docs/scripts/scaffold-experiment-doc.mjs my-experiment ``` This creates `apps/docs/content/docs/experiments/my-experiment.mdx` with frontmatter, deploy button, and `TODO` markers derived from `src/index.ts` and `wrangler.json`. ### Fill in content from source code [#fill-in-content-from-source-code] Read these files (source of truth): 1. `src/index.ts` - name, description, usage 2. `src/routes/*.ts` - endpoints, validation, `jsonError` codes 3. `src/types/` - response shapes 4. `wrangler.json` - bindings 5. `README.md` - examples (verify against code) Replace every `TODO` in the MDX file. ### Add to sidebar navigation [#add-to-sidebar-navigation] Edit `apps/docs/content/docs/meta.json` and add `"experiments/my-experiment"` under the correct category (see [Categories](#categories) below). ### Update root README (new experiments only) [#update-root-readme-new-experiments-only] Add a row to the experiments table in the root `README.md` with name, description, and deploy link. ### Verify the docs build [#verify-the-docs-build] ```bash cd apps/docs && npm run build ``` Open `http://localhost:3000/experiments/my-experiment` after `npm run dev -- --filter=docs`. ## Page structure [#page-structure] ### Required frontmatter [#required-frontmatter] ```yaml --- title: "Human Readable Name" description: "One sentence for SEO and page header (≤ ~160 characters)" --- ``` Use the same description as `GET /` returns in `src/index.ts` when possible. ### Required sections [#required-sections] 1. **Intro** - What the worker does and which Cloudflare product it showcases 2. **API Endpoint(s)** - One `### METHOD /path` block per public route 3. **Parameters** - Document each query/body field 4. **Example request** - `curl` against `https://your-worker.workers.dev` 5. **Response fields** - Type + description for each JSON key 6. **Example response** - Valid JSON 7. **Error responses** - `{ error, code }` shape with real codes from routes 8. **Use cases** - 3–5 bullets 9. **Deployment** - `` with deploy button + test command 10. **Local development** - install, `npm run dev`, local `curl` on port `8787` 11. **Cloudflare features used** - Bullets with links to developer docs ### Optional sections [#optional-sections] Add when they help readers: | Section | When | | -------------------------- | ---------------------------------------------------- | | `` | Experimental workers, AI cost/limits | | **Features** | Multiple capabilities beyond one endpoint | | **Implementation details** | AI pipelines, multi-step fetch/parse flows | | **Configuration** | Bindings, secrets, D1 schema SQL | | **Limitations** | Timeouts, size caps, local vs production differences | | **Next steps** | `` to related experiments or Cloudflare docs | ### Reference examples [#reference-examples] * **Simple** (single route, no bindings): [Is It Down?](/experiments/is-it-down), [Where Am I?](/experiments/whereami) * **Full** (AI, config, implementation walkthrough): [AI Website Summary](/experiments/ai-website-summary) ## MDX conventions [#mdx-conventions] ### Parameter documentation [#parameter-documentation] Use bold name + type + description (Fumadocs prose style): ```mdx **`url`** `string` (required) The target URL to check. Must use `http://` or `https://`. ``` Do **not** use Mintlify components (`ParamField`, `Icon`, etc.). ### Deploy button [#deploy-button] Always use the monorepo path `apps/experiments/`: ```mdx [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/shrinathsnayak/cloudflare-experiments/tree/main/apps/experiments/is-it-down) ``` ### Available MDX components [#available-mdx-components] Registered in `apps/docs/components/mdx.tsx`: * `Callout` - notes and warnings * `Steps` / `Step` - numbered procedures * `Cards` / `Card` - related links * `Accordions` / `Accordion` - collapsible detail External images (e.g. deploy button SVG) use plain `` / markdown image syntax. ## Categories [#categories] Add new pages under the matching separator in `meta.json`: | Separator | Use for | | ------------------------------ | -------------------------------------------------- | | `---AI & Machine Learning---` | Workers AI, LLM summarization, AI proxies | | `---Web Scraping & Parsing---` | HTML fetch/parse, metadata, llms.txt, dependencies | | `---Browser & Screenshots---` | Browser Rendering binding | | `---Network & Monitoring---` | DNS, uptime, redirects, geolocation, `request.cf` | | `---Storage & Data---` | R2, D1, KV, link shorteners | If an experiment spans categories, pick the **primary** capability shown in its README and issue proposal. ## Updating existing docs [#updating-existing-docs] When changing an experiment: 1. Diff routes, types, `wrangler.json`, and README 2. Update only the affected MDX sections (API, errors, config, deployment notes) 3. Keep curl examples in sync with path and query names 4. Run `npm run build` in `apps/docs` Do not remove documented error codes that still exist in code, and do not document routes that were deleted. ## Accuracy checklist [#accuracy-checklist] Before merging: * [ ] Every endpoint in docs exists in `src/routes/` or `src/index.ts` * [ ] Error `code` strings match `jsonError(c, message, "CODE")` in source * [ ] Response JSON matches TypeScript types * [ ] Binding setup matches `wrangler.json` and `src/types/env.d.ts` * [ ] Page entry exists in `meta.json` * [ ] Deploy URL uses `apps/experiments/` * [ ] `apps/docs` build passes ## Agent / Cursor skill [#agent--cursor-skill] The **`experiment-docs`** skill (`.cursor/skills/experiment-docs/SKILL.md`) instructs Cursor agents to: * Run the scaffold script * Follow the template at `.cursor/skills/experiment-docs/template.mdx` * Update `meta.json` and README * Verify the docs build Invoke it when adding or updating experiment documentation. ## Related guides [#related-guides] * [Adding New Experiments](/adding-experiments) - full worker scaffold process * [Code Standards](/code-standards) - API and folder conventions docs should reflect * [Contributing](/contributing) - PR expectations