Experiment Documentation Guide

Every worker under apps/experiments/<name>/ should have a matching docs page at /experiments/<name>. This guide explains structure, conventions, and the automation available to contributors and agents.

Where docs live

Artifact	Path
MDX page	`apps/docs/content/docs/experiments/<name>.mdx`
Sidebar order	`apps/docs/content/docs/meta.json`
Docs app	`apps/docs/` (Fumadocs + Next.js)
Worker source	`apps/experiments/<name>/`
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

Scaffold the MDX file

From the repository root:

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

Read these files (source of truth):

src/index.ts - name, description, usage
src/routes/*.ts - endpoints, validation, jsonError codes
src/types/ - response shapes
wrangler.json - bindings
README.md - examples (verify against code)

Replace every TODO in the MDX file.

Edit apps/docs/content/docs/meta.json and add "experiments/my-experiment" under the correct category (see Categories below).

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

cd apps/docs && npm run build

Open http://localhost:3000/experiments/my-experiment after npm run dev -- --filter=docs.

Page structure

Required frontmatter

---
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

Intro - What the worker does and which Cloudflare product it showcases
API Endpoint(s) - One ### METHOD /path block per public route
Parameters - Document each query/body field
Example request - curl against https://your-worker.workers.dev
Response fields - Type + description for each JSON key
Example response - Valid JSON
Error responses - { error, code } shape with real codes from routes
Use cases - 3–5 bullets
Deployment - <Steps> with deploy button + test command
Local development - install, npm run dev, local curl on port 8787
Cloudflare features used - Bullets with links to developer docs

Optional sections

Add when they help readers:

Section	When
`<Callout type="warning">`	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	`<Cards>` to related experiments or Cloudflare docs

Reference examples

Simple (single route, no bindings): Is It Down?, Where Am I?
Full (AI, config, implementation walkthrough): AI Website Summary

MDX conventions

Parameter documentation

Use bold name + type + description (Fumadocs prose style):

**`url`** `string` (required)

The target URL to check. Must use `http://` or `https://`.

Do not use Mintlify components (ParamField, Icon, etc.).

Deploy button

Always use the monorepo path apps/experiments/<name>:

[![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

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 <img> / markdown image syntax.

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

Updating existing docs

When changing an experiment:

Diff routes, types, wrangler.json, and README
Update only the affected MDX sections (API, errors, config, deployment notes)
Keep curl examples in sync with path and query names
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

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/<name>
apps/docs build passes

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.

Adding New Experiments - full worker scaffold process
Code Standards - API and folder conventions docs should reflect
Contributing - PR expectations