V8-Serverless/Telegram-Bot-Production- / .agents/skills/contributing
contributing
VerifiedUse when contributing to the Cloudflare Docs repository — writing or editing documentation pages, choosing content types or components, adding changelog entries, reviewing docs, or learning how to contribute.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| references/changelog.md | markdown | 3.9 KB |
| references/choosing-components.md | markdown | 10.8 KB |
| references/content-types.md | markdown | 5.1 KB |
| references/information-architecture.md | markdown | 4.1 KB |
| references/reviewing-docs.md | markdown | 13.3 KB |
| references/writing-docs.md | markdown | 4.5 KB |
references/choosing-components.md
View on GitHub# Choosing Components by Intent
Start from the content you have and pick the component that presents it correctly. This file is about _when_ and _why_ to reach for each component. For props, syntax, and full examples, read `.agents/references/components.md`. The authoritative live list with rendered examples is at https://developers.cloudflare.com/style-guide/build-the-page/components/.
This covers the components in the synced catalog (`.agents/references/components.md`). Diagram, homepage, and layout-internal exports from `~/components` are omitted as non-authoring tools. A few utility components documented only in the live style guide (for example, the icon components and `RSSButton`) sit outside this list — check https://developers.cloudflare.com/style-guide/build-the-page/components/ if you need one that is not here.
Two rules first:
- Add reusable components to the `~/components` barrel export (`src/components.ts`) and import them from `~/components`, after the frontmatter. Page-specific wrapper components or one-off components may use deep paths instead of adding to the barrel. A used-but-unimported component is a silent build failure.
- For the mandatory mappings below, never use a bare code fence.
## Reverse lookup: the data you have → the component
| You have… | Use | Mandatory? |
| ------------------------------------------------------ | ---------------------------------------- | ---------- |
| A Workers JavaScript/TypeScript code sample | `TypeScriptExample` | Yes |
| A Wrangler configuration | `WranglerConfig` (TOML input, `$today`) | Yes |
| A package install or exec command (npm/yarn/pnpm/bun) | `PackageManagers` | Yes |
| A multi-step procedure | `Steps` | Yes |
| A step that navigates the dashboard | `DashButton` | Yes |
| A Cloudflare API endpoint to call | `APIRequest` | — |
| A non-Cloudflare curl command | `CURL` | — |
| A full Wrangler command or namespace reference | `WranglerCommand` / `WranglerNamespace` | — |
| A parameter/field data type or constraint | `Type` / `MetaInfo` | — |
| Mutually exclusive paths (Dashboard vs API, languages) | `Tabs` / `TabItem` | — |
| Supplementary detail that would clutter the main flow | `Details` | — |
| A directory/file layout | `FileTree` | — |
| A sample to set apart in a styled box | `Example` | — |
| Content constrained to a narrower width | `Width` | — |
| A heading with a custom anchor (inside a component) | `AnchorHeading` | — |
| Reusable content shared across pages | `Render` (a partial) | — |
| A formatted Markdown string inside JSX | `Markdown` | — |
| Plan availability for a feature | `Plan` | — |
| Lifecycle status (Beta/Alpha) inline or in a heading | `ProductAvailabilityText`, `Badge` | — |
| A small inline status pill | `InlineBadge` (avoid; prefer `Badge`) | — |
| Inline changelog entries for a product | `ProductChangelog` | — |
| Relational data (fields, limits, comparisons) | a Markdown table | — |
| A glossary term inline | `GlossaryTooltip` / `GlossaryDefinition` | — |
| A full product glossary table | `Glossary` | — |
| Links/cards routing to other pages | `LinkCard` / `CardGrid`, `Card` | — |
| A primary call-to-action link | `LinkButton` | — |
| A product feature highlight on an overview | `Feature` | — |
| A related Cloudflare product reference | `RelatedProduct` | — |
| An auto-generated child-page list | `DirectoryListing` | — |
| A filterable list of examples/resources | `ResourcesBySelector` | — |
| An auto-generated tutorial table | `ListTutorials` | — |
| A description block below the page title | `Description` | — |
| A YouTube or Cloudflare Stream video | `YouTube` / `Stream` | — |
| A live statistic in prose | `PublicStats` | — |
| A copyable WAF/security rule ID | `RuleID` | — |
| Available notification types for a product | `AvailableNotifications` | — |
| Pages framework build-preset details | `PagesBuildPreset` | — |
| An interactive IP-range subtraction calculator | `SubtractIPCalculator` | — |
## By intent
### Code and configuration
- **`TypeScriptExample`** — any Workers JS/TS. Auto-generates the JS tab from TS, so there is one source to maintain. Do not use bare `ts`/`js` fences.
- **`WranglerConfig`** — any Wrangler config. Provide TOML or JSON; the other is generated. Use `$today` for `compatibility_date`. Note minimum compatibility dates in a `:::note`.
- **`PackageManagers`** — install/exec commands across npm, yarn, pnpm, and bun tabs.
- **`WranglerCommand` / `WranglerNamespace`** — auto-generated Wrangler CLI reference for a command or a whole namespace.
- **Plain fenced block** — any other language (Python, Rust, Go) or non-Workers config (JSON, YAML). Use a lowercase language; use `txt` for generic output. For command output, add the `output` suffix to a second fence.
### API and reference data
- **`APIRequest`** — Cloudflare API endpoints; generates a correct curl from the OpenAPI schema.
- **`CURL`** — arbitrary non-Cloudflare endpoints.
- **`Type`** — a pill-shaped data-type badge for a parameter, field, or property (`string`, `boolean`, `Promise<T>`). Heavily used on API and reference pages.
- **`MetaInfo`** — a metadata annotation alongside a type: constraints and defaults (`required`, `optional`, `read-only`, `(default: false)`).
### Structure and flow
- **`Steps`** — every multi-step procedure. See `.agents/references/procedures.md`.
- **`Tabs` / `TabItem`** — present mutually exclusive paths (Dashboard / API / Terraform via `syncKey="dashPlusAPI"`, or languages via `syncKey="workersExamples"`). The primary answer is the first tab. Do not nest tabs.
- **`Details`** — collapse advanced options, long samples, or background that would otherwise break the main flow.
- **`FileTree`** — show project/directory structure.
- **`Example`** — wrap content in a styled box to set it apart from surrounding prose.
- **`Width`** — constrain content (often an image) to large/medium/small width.
- **`AnchorHeading`** — a heading with a custom anchor ID, for use inside components or non-MDX contexts. In normal MDX, headings get anchors automatically.
### Content reuse
- **`Render`** — embed a partial from `src/content/partials/{product}/`. Prefer this over copy-pasting shared content. See `information-architecture.md` for when to extract a partial.
- **`Markdown`** — render a Markdown string inside JSX, mainly for formatted variables passed into partials. Use sparingly.
### Availability and status
- **`Plan`** — plan availability badge near a feature or at the top of an overview.
- **`ProductAvailabilityText`** — inline Beta/Alpha status that renders nothing once GA, so it is safe to leave in place.
- **`Badge`** — status label in a heading or sidebar. Prefer it over `InlineBadge`.
- **`InlineBadge`** — a small inline status pill. Avoid it; prefer `Badge` or stating status in prose.
- **`ProductChangelog`** — embed a product's or area's changelog entries inline on a page.
### Navigation and overview pages
- **`LinkCard` / `CardGrid`** — link cards, optionally gridded, for routing readers onward.
- **`Card` / `LinkTitleCard` / `ListCard`** — styled card containers for highlighting or grouping content.
- **`Feature`** — feature cards on a product overview.
- **`RelatedProduct`** — related-product cards with icons.
- **`DirectoryListing`** — auto-generated child-page listing on navigation/overview pages.
- **`LinkButton`** — primary call-to-action link on overview/get-started pages.
- **`ResourcesBySelector` / `ListTutorials`** — filterable/auto-generated listings for examples and tutorial indexes.
- **`Description`** — a description block rendered below the page title. Prefer the `summary` frontmatter field unless you need it conditionally or inside a component.
### Glossary and media
- **`GlossaryTooltip`** — hover definition for a term inline.
- **`GlossaryDefinition`** — pull a definition into the body.
- **`Glossary`** — full product glossary table on a dedicated page.
- **`YouTube`** — embed a YouTube video by ID.
- **`Stream`** — embed a Cloudflare Stream video.
### Stats and product-specific helpers
- **`PublicStats`** — a live statistic (data centers, bandwidth) inline in prose.
- **`DashButton`** — a button to a validated dashboard deeplink; use it for in-procedure dashboard navigation instead of a bare link.
- **`RuleID`** — a copyable WAF/security rule ID.
- **`AvailableNotifications`** — list a product's available notification types.
- **`PagesBuildPreset`** — Pages framework build-preset details.
- **`SubtractIPCalculator`** — interactive IP-range subtraction calculator (networking docs).
### When no component fits
Use prose, a Markdown table (for relational data), or a plain fenced code block with a lowercase language. Do not force a component where plain Markdown is clearer, and do not use a table to lay out a page. If you think a component exists but it is not listed here, check `.agents/references/components.md` or the live style guide before inventing markup.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |