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

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

SEO, tags, and AI discoveryCopy Anchor Link

Edit title, description, tags, and bindings in each experiment's MDX frontmatter. Keep apps/docs/lib/experiment-docs-meta.ts in sync when you change tags or bindings. Optional reference catalog: apps/docs/data/experiment-seo.json.

Tag guidelines:

1. Primary category first - one of ai, scraping, browser, network, edge, storage, stateful, containers, email, security (used by docs search chips).
2. Product / binding tags - e.g. workers-ai, durable-objects, vectorize, browser-rendering.
3. Discoverability aliases - names people or agents actually search for when the Cloudflare product is obscure (e.g. Clef → jev, systemone, decision-model; ML-KEM → kyber, post-quantum).

Descriptions should be ~120–160 characters and mention the searchable alias plus the Cloudflare capability. Intros can expand on that for humans and LLM crawlers (/llms.txt, /llms-full.txt, per-page markdown).

Quick start: new experimentCopy Anchor Link

node apps/docs/scripts/scaffold-experiment-doc.mjs my-experiment

cd apps/docs && npm run build

Page structureCopy Anchor Link

Required frontmatterCopy Anchor Link

---
title: "Human Readable Name"
description: "One sentence for SEO and page header (≤ ~160 characters)"
# Only for experiments in the latest What's New batch:
# status: new
---

Use the same description as GET / returns in src/index.ts when possible. Add status: new only while the experiment is in the current What's New cohort, then remove it when the next batch ships.

Required sectionsCopy Anchor Link

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 - <Steps> 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 sectionsCopy Anchor Link

Add when they help readers:

Use in your projectCopy Anchor Link

For experiments with a small, self-contained core (helpers in src/lib/, few or no bindings), add a paste recipe between Limitations and Deployment using <UseInYourProject>:

## Use in your project

<UseInYourProject
  experiment="whereami"
  platform={["request.cf"]}
  files={["src/lib/cf.ts", "examples/usage.ts"]}
/>

The component loads each path in files from apps/experiments/<name>/ at build time and renders filename tabs. Put wire-up snippets in examples/usage.ts (docs-only; keep it out of wrangler main). Do not paste source into MDX - edit the real files so docs stay in sync.

Pilots: Crypto Hash, Where Am I?, Edge Cache.

Skip this section when the useful unit is the whole Worker (many bindings, Durable Objects, multi-route apps). Deploy remains the primary path.

Reference examplesCopy Anchor Link

• Simple (single route, no bindings): Is It Down?, Where Am I?
• Paste recipe: Crypto Hash, Edge Cache
• Full (AI, config, implementation walkthrough): AI Website Summary

MDX conventionsCopy Anchor Link

Parameter documentationCopy Anchor Link

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

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

Registered in apps/docs/components/mdx.tsx:

• Callout - notes and warnings
• Steps / Step - numbered procedures
• Cards / Card - related links
• Accordions / Accordion - collapsible detail
• UseInYourProject - paste recipe checklist (deps, bindings, files, snippets)
• File / Files / Folder - folder trees

External images (e.g. deploy button SVG) use plain <img> / markdown image syntax.

CategoriesCopy Anchor Link

Add new pages under the matching separator in meta.json:

If an experiment spans categories, pick the primary capability shown in its README and issue proposal.

Updating existing docsCopy Anchor Link

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

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
• New experiment or notable user-facing change listed on What's New
• status: new only on the latest What's New cohort (older badges cleared; home-content.ts matched)
• Deploy URL uses apps/experiments/<name>
• apps/docs build passes

Agent / Cursor skillCopy Anchor Link

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, README, and What's New
• Rotate status: new badges from the latest What's New batch
• Verify the docs build

Invoke it when adding or updating experiment documentation.

Related guidesCopy Anchor Link

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