From b8843bc3c436268cef0c323d461069616e7d59a9 Mon Sep 17 00:00:00 2001 From: kodster28 Date: Mon, 18 May 2026 13:44:27 -0500 Subject: [PATCH 1/6] Remove tagging logic and enforcement --- .agents/references/components.md | 191 +++++++++------ .agents/references/style-guide.md | 218 +++++++++--------- .github/CODEOWNERS | 3 +- AGENTS.md | 56 ++--- astro.config.ts | 2 - src/components/ResourcesBySelector.astro | 3 - src/components/TagsUsage.astro | 71 ------ src/components/index.ts | 1 - src/components/overrides/Head.astro | 8 - .../framework-guides/deploy-a-hono-site.mdx | 10 - .../framework-guides/deploy-a-nuxt-site.mdx | 6 - src/content/docs/rules/examples.mdx | 2 +- .../docs/rules/snippets/examples/index.mdx | 6 +- .../docs/rules/transform/examples/index.mdx | 1 - .../components/resources-by-selector.mdx | 2 +- src/content/docs/workers/examples/index.mdx | 6 +- src/plugins/starlight/route-data.ts | 29 --- src/schemas/base.ts | 2 +- src/schemas/tags.ts | 186 --------------- 19 files changed, 257 insertions(+), 546 deletions(-) delete mode 100644 src/components/TagsUsage.astro delete mode 100644 src/plugins/starlight/route-data.ts delete mode 100644 src/schemas/tags.ts diff --git a/.agents/references/components.md b/.agents/references/components.md index 2e42390e5b344e9..8e2fc5358adb2c9 100644 --- a/.agents/references/components.md +++ b/.agents/references/components.md @@ -14,6 +14,7 @@ import { Render } from "~/components"; + ``` @@ -34,7 +35,7 @@ Inside the partial, params are referenced as JS expressions: `{props.product}`. Renders a TypeScript code block and auto-generates a JavaScript tab using `ts-blank-space`. **Required for all Workers JS/TS examples** — do not use bare `ts`/`js` fences. -```mdx +````mdx import { TypeScriptExample } from "~/components"; @@ -44,11 +45,13 @@ export default { return new Response("Hello World"); } } satisfies ExportedHandler; -``` +```` + ``` Props: + - `filename` — optional, must end in `.ts`. The JS tab shows the `.js` equivalent. - `playground` — boolean. Adds "Run Worker in Playground" button to the JS tab. - `code` — object. Expressive Code options (e.g. `collapse: "1-2"`). Apply to both tabs. @@ -61,7 +64,7 @@ Note: Expressive Code fence options (`collapse={1-2}`, etc.) cannot be set on th Renders Wrangler config with synced TOML and JSON tabs, auto-converting between formats. **Required for all Wrangler configuration examples** — do not use bare `toml`/`jsonc` fences. -```mdx +````mdx import { WranglerConfig } from "~/components"; @@ -74,7 +77,8 @@ compatibility_date = "$today" binding = "DB" database_name = "prod-d1-tutorial" database_id = "" -``` +```` + ``` @@ -93,9 +97,11 @@ Shows a command across npm, yarn, and pnpm in synced tabs. **Required for packag import { PackageManagers } from "~/components"; + + ``` @@ -109,13 +115,14 @@ For showing different ways to accomplish the same thing. Use when there are mutu import { Tabs, TabItem } from "~/components"; - Dashboard instructions - API instructions - Terraform instructions + Dashboard instructions + API instructions + Terraform instructions ``` Standard `syncKey` values (sync tab selection across the page): + - `dashPlusAPI` — Dashboard / API / Terraform - `workersExamples` — JavaScript / TypeScript / Python / Rust @@ -146,13 +153,12 @@ Collapsible section. Use for supplementary content that would clutter the main f ```mdx import { Details } from "~/components"; -
- Content shown when expanded. -
+
Content shown when expanded.
+
- Content visible without interaction. + Content visible without interaction.
``` @@ -177,6 +183,7 @@ import { Plan } from "~/components"; + ``` @@ -192,10 +199,16 @@ import { GlossaryTooltip } from "~/components"; active zone -active zone + + + active zone + -active zone + + + active zone + ``` Props: `term` (required, matches a YAML entry key), `prepend` (optional text prepended to the definition), `link` (optional, wraps the inner text in a link). @@ -278,6 +291,7 @@ import { DashButton } from "~/components"; + ``` @@ -293,25 +307,28 @@ Fetches and displays a file from a Cloudflare GitHub repository. Use a full 40-c import { GitHubCode } from "~/components"; + + + ``` @@ -364,19 +381,21 @@ Starlight built-ins for styled card containers. Used on overview and navigation import { Card, LinkTitleCard, ListCard } from "~/components"; + - Interesting content you want to highlight. + Interesting content you want to highlight. + - Deploy your first Worker in minutes. + Deploy your first Worker in minutes. + -- [Docs](/workers/) -- [API reference](/api/) + - [Docs](/workers/) - [API reference](/api/) ``` @@ -402,13 +421,15 @@ Embeds a Cloudflare Stream video. Use `id` + `title` for a specific video, or `f import { Stream } from "~/components"; + + ``` @@ -424,24 +445,27 @@ Generates a formatted `curl` command from the Cloudflare OpenAPI schema. Use for import { APIRequest } from "~/components"; + + + ``` @@ -457,10 +481,10 @@ Generates a `curl` command for arbitrary (non-Cloudflare-API) URLs. Use when `AP import { CURL } from "~/components"; ``` @@ -479,7 +503,11 @@ import { WranglerCommand } from "~/components"; - + + ``` Use `ExtraFlagDetails` as a child to add or replace help text for specific flags: @@ -488,12 +516,12 @@ Use `ExtraFlagDetails` as a child to add or replace help text for specific flags import { WranglerCommand, ExtraFlagDetails } from "~/components"; - - Additional detail appended to the flag's help text. - - - Custom text that replaces the flag's help text entirely. - + + Additional detail appended to the flag's help text. + + + Custom text that replaces the flag's help text entirely. + ``` @@ -511,6 +539,7 @@ import { Markdown } from "~/components"; + ``` @@ -523,7 +552,7 @@ Limitations: no MDX features, no Astro image optimization, no syntax highlightin Creates a heading with a custom anchor ID — useful when writing headings inside components or non-Markdown files. In regular MDX, headings get anchors automatically via rehype plugins, so this is rarely needed. To override a heading ID in MDX, use an inline comment instead: ```mdx -## My heading {/*custom-anchor*/} +## My heading {/* custom-anchor */} ``` When you do need the component: @@ -531,7 +560,11 @@ When you do need the component: ```mdx import { AnchorHeading } from "~/components"; - + ``` Props: `title` (required, heading text), `slug` (required, custom anchor ID), `depth` (heading level, e.g. `2` for H2). @@ -546,8 +579,12 @@ Renders a styled link button. Useful for primary CTAs on overview and get-starte import { LinkButton } from "~/components"; Get started -More information -Other stuff + + More information + + + Other stuff + ``` Variants: `primary` (default), `secondary`, `minimal`. @@ -562,14 +599,14 @@ Starlight built-in. Renders a card with a title, description, and link. Use `Car import { LinkCard, CardGrid } from "~/components"; - - + + ``` @@ -582,12 +619,7 @@ Starlight built-in. Displays a file and directory tree. Use bold to highlight th ```mdx import { FileTree } from "~/components"; - -- src/ - - index.ts - - **worker.ts** -- wrangler.toml - +- src/ - index.ts - **worker.ts** - wrangler.toml ``` --- @@ -599,9 +631,7 @@ Renders a short description block directly below the page title. Prefer the `sum ```mdx import { Description } from "~/components"; - - A short description rendered below the page title. - +A short description rendered below the page title. ``` --- @@ -614,7 +644,7 @@ Renders a feature card with a name and link. Used on product overview pages to l import { Feature } from "~/components"; - Coordinate state and logic across Workers with strongly consistent storage. + Coordinate state and logic across Workers with strongly consistent storage. ``` @@ -630,7 +660,7 @@ Renders a related product card with an icon, name, and link. Used on overview pa import { RelatedProduct } from "~/components"; - Store large amounts of unstructured data without egress fees. + Store large amounts of unstructured data without egress fees. ``` @@ -734,13 +764,13 @@ Displays a filterable list of docs pages pulled by `pcx_content_type`, `tags`, a import { ResourcesBySelector } from "~/components"; ``` -Props: `directory` (required, relative to `src/content/docs/`), `types` (array of `pcx_content_type` values), `filterables` (frontmatter properties to show as filter dropdowns), `tags` (pre-filter by tag), `products` (pre-filter by product), `showDescriptions` (boolean, default `true`), `showLastUpdated` (boolean, default `false`). +Props: `directory` (required, relative to `src/content/docs/`), `types` (array of `pcx_content_type` values), `filterables` (frontmatter properties to show as filter dropdowns), `products` (pre-filter by product), `showDescriptions` (boolean, default `true`), `showLastUpdated` (boolean, default `false`). --- @@ -807,7 +837,11 @@ import SubtractIPCalculator from "~/components/SubtractIPCalculator.tsx"; - + + ``` Note: imports directly from the `.tsx` file path, not from `~/components`. @@ -823,7 +857,9 @@ import { Width } from "~/components"; 75% of container width 50% of container width -25%, centered + + 25%, centered + ``` Props: `size` (required, `"large"` | `"medium"` | `"small"`), `center` (boolean). @@ -852,7 +888,10 @@ Lists available notification types for a product, sourced from `src/content/noti import { AvailableNotifications } from "~/components"; - + ``` Props: `product` (required, product name or slug), `notificationFilter` (optional, filter to a specific notification type by name). diff --git a/.agents/references/style-guide.md b/.agents/references/style-guide.md index ab12eb351deb394..ea75f240380ae42 100644 --- a/.agents/references/style-guide.md +++ b/.agents/references/style-guide.md @@ -8,10 +8,10 @@ Prescriptive rules for writing and reviewing content in this repository. Distill These characters have special meaning in MDX and **will break the build** if used unescaped in prose, tables, or headings: -| Character | Problem | Fix | -| --------- | ------- | --- | -| `{` `}` | Interpreted as JS expressions | Wrap in backticks or use `\{` `\}` | -| `<` `>` | Interpreted as JSX elements | Use `<` `>` or wrap in backticks | +| Character | Problem | Fix | +| --------- | ----------------------------- | -------------------------------------- | +| `{` `}` | Interpreted as JS expressions | Wrap in backticks or use `\{` `\}` | +| `<` `>` | Interpreted as JSX elements | Use `<` `>` or wrap in backticks | Component imports must appear after the frontmatter block. A used-but-not-imported component is a silent build failure. @@ -21,31 +21,30 @@ Component imports must appear after the frontmatter block. A used-but-not-import ### Required fields -| Field | Rule | -| ----- | ---- | -| `title` | Required. Plain text. | -| `pcx_content_type` | Required. Must be one of the valid values below. | -| `description` | Required for all pages with `pcx_content_type`. 1–2 self-contained sentences, 50–160 characters. | +| Field | Rule | +| ------------------ | ------------------------------------------------------------------------------------------------ | +| `title` | Required. Plain text. | +| `pcx_content_type` | Required. Must be one of the valid values below. | +| `description` | Required for all pages with `pcx_content_type`. 1–2 self-contained sentences, 50–160 characters. | Valid `pcx_content_type` values: `changelog`, `concept`, `configuration`, `design-guide`, `example`, `faq`, `get-started`, `how-to`, `integration-guide`, `implementation-guide`, `learning-unit`, `navigation`, `overview`, `reference`, `reference-architecture`, `reference-architecture-diagram`, `release-notes`, `solution-guide`, `troubleshooting`, `tutorial`, `video`. ### Optional fields -| Field | Type | Description | -| ----- | ---- | ----------- | -| `sidebar.order` | number | Sort order in the left nav. Lower = higher. | -| `sidebar.label` | string | Override the nav label (defaults to `title`). | -| `sidebar.hidden` | boolean | Hide from nav but keep the page accessible. | -| `products` | array | Related directory entries by filename from `src/content/directory/`. | -| `tags` | array | Related keywords. Validated against allowlist in `src/schemas/tags.ts` — invalid tags fail the build. | -| `difficulty` | string | For tutorials: `Beginner`, `Intermediate`, or `Advanced`. Shown in tutorial listings. | -| `reviewed` | string | `YYYY-MM-DD` of last explicit end-to-end review. | -| `summary` | string | Short description rendered below the page title on the page itself. | -| `noindex` | boolean | Adds `noindex` to the page — use for deprecated/legacy content. | -| `chatbot_deprioritize` | boolean | De-prioritizes the page in Support AI responses. Companion to `noindex`. | -| `canonical` | string | Override the `` URL. | -| `hideChildren` | boolean | Collapses this nav group to a single link to the index page. | -| `feedback` | boolean | Show/hide the feedback prompt. Defaults to `true`. | +| Field | Type | Description | +| ---------------------- | ------- | ------------------------------------------------------------------------------------- | +| `sidebar.order` | number | Sort order in the left nav. Lower = higher. | +| `sidebar.label` | string | Override the nav label (defaults to `title`). | +| `sidebar.hidden` | boolean | Hide from nav but keep the page accessible. | +| `products` | array | Related directory entries by filename from `src/content/directory/`. | +| `difficulty` | string | For tutorials: `Beginner`, `Intermediate`, or `Advanced`. Shown in tutorial listings. | +| `reviewed` | string | `YYYY-MM-DD` of last explicit end-to-end review. | +| `summary` | string | Short description rendered below the page title on the page itself. | +| `noindex` | boolean | Adds `noindex` to the page — use for deprecated/legacy content. | +| `chatbot_deprioritize` | boolean | De-prioritizes the page in Support AI responses. Companion to `noindex`. | +| `canonical` | string | Override the `` URL. | +| `hideChildren` | boolean | Collapses this nav group to a single link to the index page. | +| `feedback` | boolean | Show/hide the feedback prompt. Defaults to `true`. | Example: @@ -60,8 +59,6 @@ sidebar: order: 2 difficulty: Beginner reviewed: 2025-01-15 -tags: - - Tunnel --- ``` @@ -93,15 +90,15 @@ Do not use Internet slang: no `tl;dr`, `IMO`, `FYI`. ### Jargon to avoid -| Instead of | Use | -| ---------- | --- | -| whitelist / blacklist | allowlist / blocklist | -| master / slave | primary / replica (or context-specific terms) | -| man-in-the-middle attack | on-path attack | -| sanity check | validate / smoke test | -| enable / disable (toggle) | turn on / turn off | -| out-of-the-box | default | -| on-prem | on-premises | +| Instead of | Use | +| ------------------------- | --------------------------------------------- | +| whitelist / blacklist | allowlist / blocklist | +| master / slave | primary / replica (or context-specific terms) | +| man-in-the-middle attack | on-path attack | +| sanity check | validate / smoke test | +| enable / disable (toggle) | turn on / turn off | +| out-of-the-box | default | +| on-prem | on-premises | ### Inclusive language @@ -111,23 +108,23 @@ Do not use racist, gendered, or ableist terminology. Use gender-neutral pronouns ## Terminology and UI interactions -| Use | Not | -| --- | --- | -| select | click | -| go to | navigate to | +| Use | Not | +| ------------------ | ---------------- | +| select | click | +| go to | navigate to | | turn on / turn off | enable / disable | -| refer to | see | +| refer to | see | --- ## Text formatting -| Element | Convention | -| ------- | ---------- | -| Clickable UI elements, menu items, button labels | **Bold**: select **Save**, go to **DNS** > **Records** | -| Code, paths, IPs, ports, HTTP verbs, status codes, filenames, config keys | `monospace` | -| Dropdown options the user selects *from* | *Italics* | -| Nested menu separators | **Bold** the words, plain `>` symbol: **Options** > **Settings** | +| Element | Convention | +| ------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| Clickable UI elements, menu items, button labels | **Bold**: select **Save**, go to **DNS** > **Records** | +| Code, paths, IPs, ports, HTTP verbs, status codes, filenames, config keys | `monospace` | +| Dropdown options the user selects _from_ | _Italics_ | +| Nested menu separators | **Bold** the words, plain `>` symbol: **Options** > **Settings** | Things that get monospace: IP addresses and ranges, port numbers, API commands (`GET`, `POST`), terminal commands (`wrangler login`), file paths, filenames and extensions (`wrangler.toml`), config keys, data types (`string`, `int64`), environment variable names, HTTP headers (`Content-Length`), HTTP status codes (`400`, `200`), URLs used as input/output, DNS record types (`AAAA`). @@ -146,15 +143,15 @@ Do not use italics for toggle states — "enabled" and "disabled" should not be Common terms: -| Correct | Incorrect | -| ------- | --------- | -| DDoS | DDOS, ddos | -| SSL | ssl | -| TLS | tls | -| WAF | waf | -| CAPTCHA | Captcha, captcha | -| Zero Trust | zero trust | -| Internet | internet | +| Correct | Incorrect | +| ---------- | ---------------- | +| DDoS | DDOS, ddos | +| SSL | ssl | +| TLS | tls | +| WAF | waf | +| CAPTCHA | Captcha, captcha | +| Zero Trust | zero trust | +| Internet | internet | --- @@ -167,6 +164,7 @@ Common terms: - Descriptive link text — never "here", "this page", "read more", "click here" Standard phrasing: + - `For more information, refer to [Page Title](/path/).` - `To , refer to [Section Title](/path/).` @@ -191,11 +189,13 @@ Do not use: "Learn more about...", "To read more...", "refer the [Page] page/doc Use numbered lists for **procedures** (sequential steps). Use bullet points for **facts, data, or options** (unordered). Do not use bullet points for: + - Processes or steps (use a numbered list) - Fewer than three items (write a sentence instead) - Items longer than three lines each (break into subsections) Bullet point rules: + - All items in a list must be parallel (same grammatical form). - Do not punctuate bullets unless each item is a full sentence. - Aim for 3–6 items; the "six-pack rule" — no more than six bullets, each six words or fewer, is a good default. @@ -282,59 +282,60 @@ Package install commands must use `PackageManagers`. All components are imported from `~/components`. Imports must appear after the frontmatter block. **Mandatory component usage** — do not use bare fences for these: + - Workers JS/TS examples → `TypeScriptExample` - Wrangler config → `WranglerConfig` (TOML input, use `$today` for `compatibility_date`) - Package install/exec commands → `PackageManagers` - Multi-step procedures → `Steps` - Dashboard navigation steps → `DashButton` (not bare links) -| Component | Purpose | -| --------- | ------- | -| `Render` | Embed a reusable partial from `src/content/partials/{product}/{file}.mdx` | -| `TypeScriptExample` | Workers TS example with auto-generated JS tab | -| `WranglerConfig` | Wrangler config in synced TOML + JSON tabs | -| `PackageManagers` | Package install/exec command across npm, yarn, pnpm | -| `WranglerCommand` | Auto-generated full Wrangler command reference | -| `WranglerNamespace` | Auto-generated Wrangler namespace command listing | -| `Tabs` / `TabItem` | Switchable tabs (`syncKey="dashPlusAPI"` or `"workersExamples"`) | -| `Steps` | Visual numbered procedure wrapper | -| `Details` | Collapsible section for supplementary content | -| `FileTree` | File and directory tree display | -| `Width` | Constrain content to `"large"` (75%), `"medium"` (50%), or `"small"` (25%) width | -| `Plan` | Plan availability badge (`type="all"`, `"paid"`, `"pro"`, `"business"`, `"add-on"`) | -| `FeatureTable` | Feature availability by plan from `src/content/plans/` (dot-notation `id`) | -| `ProductFeatures` | Full feature list for a product from `src/content/plans/` | -| `ProductChangelog` | Inline changelog entries for a product or area | -| `ProductAvailabilityText` | Inline lifecycle status (Beta, Alpha) — renders nothing for GA | -| `Feature` | Feature card for product overview pages | -| `RelatedProduct` | Related product card with icon for overview pages | -| `GlossaryTooltip` | Hover tooltip from `src/content/glossary/` | -| `GlossaryDefinition` | Inline glossary definition | -| `Glossary` | Full product glossary table | -| `InlineBadge` | Inline status badge — **avoid**, prefer `Badge` in headings or sidebar frontmatter | -| `Badge` | Coloured status badge (`Beta`, `New`, `Deprecated`) for headings and sidebar | -| `LinkButton` | Styled link button (`variant="primary"`, `"secondary"`, `"minimal"`) | -| `Card` / `LinkTitleCard` / `ListCard` | Styled card containers for overview and navigation pages | -| `LinkCard` / `CardGrid` | Starlight link cards, optionally in a grid | -| `DashButton` | Button linking to a validated dashboard deeplink | -| `GitHubCode` | Fetch and display a file from a Cloudflare GitHub repo (use full commit hash) | -| `DirectoryListing` | Auto-generated child page listing for nav/overview pages | -| `ListTutorials` | Auto-generated tutorial table for the current product | -| `ResourcesBySelector` | Filterable list of pages by `pcx_content_type`, tags, or products | -| `ExternalResources` | Demo apps or videos from central YAML collections, filtered by tags/products | -| `PublicStats` | Inline live statistic (data centers, bandwidth, etc.) | -| `YouTube` | Embed a YouTube video by ID | -| `YouTubeVideos` | Grid of YouTube videos for a product from `src/content/videos/` | -| `Stream` | Embed a Cloudflare Stream video by ID or collection file | -| `APIRequest` | Generate a `curl` command from the Cloudflare OpenAPI schema | -| `CURL` | Generate a `curl` command for arbitrary URLs | -| `PagesBuildPreset` | Pages framework build preset details | -| `RuleID` | Copyable rule ID (WAF / security rules) | -| `SubtractIPCalculator` | Interactive IP range subtraction calculator | -| `AvailableNotifications` | List available notification types for a product | -| `AnchorHeading` | Heading with custom anchor ID — for use inside components/non-MDX files | -| `Description` | Description block rendered below the page title | -| `Markdown` | Render a Markdown string inside JSX — primarily for formatted partial variables | +| Component | Purpose | +| ------------------------------------- | ----------------------------------------------------------------------------------- | +| `Render` | Embed a reusable partial from `src/content/partials/{product}/{file}.mdx` | +| `TypeScriptExample` | Workers TS example with auto-generated JS tab | +| `WranglerConfig` | Wrangler config in synced TOML + JSON tabs | +| `PackageManagers` | Package install/exec command across npm, yarn, pnpm | +| `WranglerCommand` | Auto-generated full Wrangler command reference | +| `WranglerNamespace` | Auto-generated Wrangler namespace command listing | +| `Tabs` / `TabItem` | Switchable tabs (`syncKey="dashPlusAPI"` or `"workersExamples"`) | +| `Steps` | Visual numbered procedure wrapper | +| `Details` | Collapsible section for supplementary content | +| `FileTree` | File and directory tree display | +| `Width` | Constrain content to `"large"` (75%), `"medium"` (50%), or `"small"` (25%) width | +| `Plan` | Plan availability badge (`type="all"`, `"paid"`, `"pro"`, `"business"`, `"add-on"`) | +| `FeatureTable` | Feature availability by plan from `src/content/plans/` (dot-notation `id`) | +| `ProductFeatures` | Full feature list for a product from `src/content/plans/` | +| `ProductChangelog` | Inline changelog entries for a product or area | +| `ProductAvailabilityText` | Inline lifecycle status (Beta, Alpha) — renders nothing for GA | +| `Feature` | Feature card for product overview pages | +| `RelatedProduct` | Related product card with icon for overview pages | +| `GlossaryTooltip` | Hover tooltip from `src/content/glossary/` | +| `GlossaryDefinition` | Inline glossary definition | +| `Glossary` | Full product glossary table | +| `InlineBadge` | Inline status badge — **avoid**, prefer `Badge` in headings or sidebar frontmatter | +| `Badge` | Coloured status badge (`Beta`, `New`, `Deprecated`) for headings and sidebar | +| `LinkButton` | Styled link button (`variant="primary"`, `"secondary"`, `"minimal"`) | +| `Card` / `LinkTitleCard` / `ListCard` | Styled card containers for overview and navigation pages | +| `LinkCard` / `CardGrid` | Starlight link cards, optionally in a grid | +| `DashButton` | Button linking to a validated dashboard deeplink | +| `GitHubCode` | Fetch and display a file from a Cloudflare GitHub repo (use full commit hash) | +| `DirectoryListing` | Auto-generated child page listing for nav/overview pages | +| `ListTutorials` | Auto-generated tutorial table for the current product | +| `ResourcesBySelector` | Filterable list of pages by `pcx_content_type` or products | +| `ExternalResources` | Demo apps or videos from central YAML collections, filtered by tags/products | +| `PublicStats` | Inline live statistic (data centers, bandwidth, etc.) | +| `YouTube` | Embed a YouTube video by ID | +| `YouTubeVideos` | Grid of YouTube videos for a product from `src/content/videos/` | +| `Stream` | Embed a Cloudflare Stream video by ID or collection file | +| `APIRequest` | Generate a `curl` command from the Cloudflare OpenAPI schema | +| `CURL` | Generate a `curl` command for arbitrary URLs | +| `PagesBuildPreset` | Pages framework build preset details | +| `RuleID` | Copyable rule ID (WAF / security rules) | +| `SubtractIPCalculator` | Interactive IP range subtraction calculator | +| `AvailableNotifications` | List available notification types for a product | +| `AnchorHeading` | Heading with custom anchor ID — for use inside components/non-MDX files | +| `Description` | Description block rendered below the page title | +| `Markdown` | Render a Markdown string inside JSX — primarily for formatted partial variables | For full props, examples, and edge cases, see `.agents/references/components.md`. @@ -357,6 +358,7 @@ For best practices or opinionated recommendations outside the main content. Defa ``` Usage rules: + - Use `note` for supplementary info that cannot be integrated into prose. - Use `caution` for actions that could break functionality or impact security. - Use `tip` for best practices and opinionated recommendations. @@ -395,6 +397,7 @@ Use screenshots sparingly — they have a high maintenance cost because UI chang Exception: use screenshots freely in changelog entries (accepted as point-in-time references). Guidelines: + - Maintain original aspect ratio. - Width 500–600 px, resolution 72 dpi. - Do not include sensitive information (redact if needed). @@ -406,6 +409,7 @@ Guidelines: ``` Alt text rules: + - Describe what the image shows and why it matters (under ~150 characters). - Do not start with "Image of" or "Screenshot of". - For purely decorative images, use empty alt text: `![]()`. @@ -430,11 +434,11 @@ In diagrams: do not use color as the only way to distinguish elements — also u Use these reserved values in examples — they are safe and will not resolve to live origins: -| Type | Values | -| ---- | ------ | -| Domains | `example.com`, `example.org`, `myappexample.com` | -| IPv4 ranges | `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` | -| URL placeholders | ``, ``, `` | +| Type | Values | +| ------------------- | ---------------------------------------------------- | +| Domains | `example.com`, `example.org`, `myappexample.com` | +| IPv4 ranges | `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` | +| URL placeholders | ``, ``, `` | | API shell variables | `$ZONE_ID`, `$CLOUDFLARE_API_TOKEN` (in curl blocks) | Use angle brackets with `ALL_CAPS_UNDERSCORES` for variable placeholders in non-API contexts. In API examples (curl blocks, `APIRequest` component), use `$VARIABLE_NAME` shell variable format. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0debf68fc73c70a..a04af6357f80096 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -13,7 +13,6 @@ *.ts @cloudflare/content-engineering @kodster28 *.astro @cloudflare/content-engineering @kodster28 package.json @cloudflare/content-engineering -/src/schemas/tags.ts @cloudflare/content-engineering @kodster28 /src/util/api.ts @cloudflare/content-engineering @kodster28 /src/content/workers-ai-models/ @craigsdennis @cloudflare/content-engineering @cloudflare/product-owners @kodster28 /public/__redirects @cloudflare/content-engineering @cloudflare/product-owners @@ -268,7 +267,7 @@ package.json @cloudflare/content-engineering /src/content/docs/support/ @cloudflare/product-owners @cloudflare/customer-support @ngayerie /src/assets/images/support/ @cloudflare/product-owners @cloudflare/customer-support @ngayerie -/src/content/docs/billing/ @cloudflare/customer-support @cloudflare/product-owners @ngayerie +/src/content/docs/billing/ @cloudflare/customer-support @cloudflare/product-owners @ngayerie # Turnstile diff --git a/AGENTS.md b/AGENTS.md index 675b4e371d8c3fc..f093f9e5285f148 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,9 +73,6 @@ pcx_content_type: how-to # Page type (see below) sidebar: order: 1 # Sort order in sidebar label: Custom Label # Override sidebar text -tags: # Optional, validated against allowlist - - JavaScript - - Workers products: # References to src/content/products/ entries - workers difficulty: Beginner # For tutorials: Beginner | Intermediate | Advanced @@ -85,8 +82,6 @@ reviewed: 2025-01-15 # YYYY-MM-DD of last content review Valid `pcx_content_type` values: `changelog`, `concept`, `configuration`, `design-guide`, `example`, `faq`, `get-started`, `how-to`, `integration-guide`, `implementation-guide`, `learning-unit`, `navigation`, `overview`, `reference`, `reference-architecture`, `reference-architecture-diagram`, `release-notes`, `solution-guide`, `troubleshooting`, `tutorial`, `video`. -Tags are validated against an allowlist in `src/schemas/tags.ts`. Invalid tags will fail the build. - ### Writing and style rules For MDX syntax, links, code blocks, formatting, and writing style, see `.agents/references/style-guide.md`. That file is the canonical agent reference — distilled from the full style guide at `src/content/docs/style-guide/`. @@ -181,26 +176,25 @@ A separate Semgrep workflow checks style guide compliance (dates, "coming soon" 8. **Skipping heading levels** — H2 then H4 without H3 will violate style guide rules. 9. **`$` prefix in terminal commands** — the copy button copies verbatim, including the `$`. 10. **Invalid changelog product folders** — the product directory must exist in `src/content/products/`. -11. **Invalid tags** — tags are validated against the allowlist in `src/schemas/tags.ts`. -12. **Redirect issues** — source URLs in `public/__redirects` must end in `/` (or `*`, `.xml`, `.json`, `.html`). No fragments in source URLs. No infinite loops. -13. **Hand-crafted directory entry IDs** — never manually write `id` values in `src/content/directory/` files. Always run `node tools/directory-entry-ids --fix` to generate them. +11. **Redirect issues** — source URLs in `public/__redirects` must end in `/` (or `*`, `.xml`, `.json`, `.html`). No fragments in source URLs. No infinite loops. +12. **Hand-crafted directory entry IDs** — never manually write `id` values in `src/content/directory/` files. Always run `node tools/directory-entry-ids --fix` to generate them. ## Content collections The site defines 20 content collections in `src/content.config.ts` with schemas in `src/schemas/`. The major ones: -| Collection | Location | Description | -| ------------------- | -------------------------------- | --------------------------------------- | -| `docs` | `src/content/docs/` | Main documentation pages (MDX) | -| `partials` | `src/content/partials/` | Reusable content snippets (MDX) | -| `changelog` | `src/content/changelog/` | Product changelogs (MDX) | -| `glossary` | `src/content/glossary/` | Glossary terms (YAML) | -| `products` | `src/content/products/` | Product metadata (YAML) | -| `plans` | `src/content/plans/` | Plan/pricing data (YAML) | -| `workers-ai-models` | `src/content/workers-ai-models/` | AI model definitions (JSON) | +| Collection | Location | Description | +| ------------------- | -------------------------------- | ---------------------------------------- | +| `docs` | `src/content/docs/` | Main documentation pages (MDX) | +| `partials` | `src/content/partials/` | Reusable content snippets (MDX) | +| `changelog` | `src/content/changelog/` | Product changelogs (MDX) | +| `glossary` | `src/content/glossary/` | Glossary terms (YAML) | +| `products` | `src/content/products/` | Product metadata (YAML) | +| `plans` | `src/content/plans/` | Plan/pricing data (YAML) | +| `workers-ai-models` | `src/content/workers-ai-models/` | AI model definitions (JSON) | | `directory` | `src/content/directory/` | Product/feature directory entries (YAML) | -| `fields` | `src/content/fields/` | Ruleset engine field definitions (YAML) | -| `learning-paths` | `src/content/learning-paths/` | Learning path definitions (JSON) | +| `fields` | `src/content/fields/` | Ruleset engine field definitions (YAML) | +| `learning-paths` | `src/content/learning-paths/` | Learning path definitions (JSON) | ### Directory entry IDs @@ -255,22 +249,22 @@ Existing components (`warp-download`, `stream-player`, `rule-id`, `check-box`, ` Repo-specific skills live in `.agents/skills/`. Each skill provides specialized instructions for a particular task. Load a skill when the task matches its description. -| Skill | When to use | -| ----- | ----------- | -| `changelog` | Creating, editing, or reviewing changelog entries | -| `code-review` | Reviewing Workers/platform code for type correctness and API usage | -| `dependabot-review` | Analyzing a Dependabot PR for impact on this repo | -| `docs-review` | Reviewing documentation PRs for style, structure, and correctness | -| `eli5` | Simplifying technical documentation for broader audiences | -| `pr` | Creating or updating GitHub pull requests | +| Skill | When to use | +| ------------------- | ------------------------------------------------------------------ | +| `changelog` | Creating, editing, or reviewing changelog entries | +| `code-review` | Reviewing Workers/platform code for type correctness and API usage | +| `dependabot-review` | Analyzing a Dependabot PR for impact on this repo | +| `docs-review` | Reviewing documentation PRs for style, structure, and correctness | +| `eli5` | Simplifying technical documentation for broader audiences | +| `pr` | Creating or updating GitHub pull requests | Shared reference files in `.agents/references/`: -| File | Contents | -| ---- | -------- | +| File | Contents | +| ---------------- | ----------------------------------------------------------- | | `style-guide.md` | Canonical writing and formatting rules for all content work | -| `components.md` | Full MDX component catalog with props and usage examples | -| `procedures.md` | Rules for writing step-by-step procedural instructions | +| `components.md` | Full MDX component catalog with props and usage examples | +| `procedures.md` | Rules for writing step-by-step procedural instructions | ## Commit conventions diff --git a/astro.config.ts b/astro.config.ts index f7e202d01fea15d..42fadcc3bfda9f7 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -192,7 +192,6 @@ export default defineConfig({ "/rules/transform/examples/?operation=*", "/ruleset-engine/rules-language/fields/reference/**", "/workers/examples/?languages=*", - "/workers/examples/?tags=*", "/workers/llms-full.txt", "/workers-ai/models/**", "/markdown.zip", @@ -222,7 +221,6 @@ export default defineConfig({ headingLinks: false, processedDirs: ["./src/content/partials/", "./src/content/changelog/"], }, - routeMiddleware: "./src/plugins/starlight/route-data.ts", disable404Route: true, }), liveCode({}), diff --git a/src/components/ResourcesBySelector.astro b/src/components/ResourcesBySelector.astro index 52c42f01fe79601..a315c3b1391900a 100644 --- a/src/components/ResourcesBySelector.astro +++ b/src/components/ResourcesBySelector.astro @@ -18,7 +18,6 @@ type LearningPathsData = keyof CollectionEntry<"learning-paths">["data"]; type ResourcesData = DocsData | VideosData | LearningPathsData; const props = z.object({ - tags: z.string().array().optional(), types: z.string().array(), products: reference("directory").array().optional(), directory: z.string().optional(), @@ -30,7 +29,6 @@ const props = z.object({ }); const { - tags, types, products, directory, @@ -52,7 +50,6 @@ const filteredResources = [...docs, ...videos, ...learningPaths].filter( return ( types.includes(type ?? "") && (directory ? id.startsWith(directory) : true) && - (tags ? data.tags?.some((v: string) => tags.includes(v)) : true) && (products ? data.products?.some((v) => products.some((p) => p.id === (typeof v === "object" ? v.id : v)), diff --git a/src/components/TagsUsage.astro b/src/components/TagsUsage.astro deleted file mode 100644 index 90fb598b2f045b5..000000000000000 --- a/src/components/TagsUsage.astro +++ /dev/null @@ -1,71 +0,0 @@ ---- -import { getCollection } from "astro:content"; -import { tags as allowedTags } from "~/schemas/tags"; - -import AnchorHeading from "./AnchorHeading.astro"; -import Details from "./Details.astro"; - -const entries = await getCollection("docs", (e) => Boolean(e.data.tags)); - -const byTag: Record = {}; - -for (const entry of entries) { - for (const tag of entry.data.tags!) { - byTag[tag] ??= []; - byTag[tag].push(entry.id); - } -} - -const flattened = Object.values(allowedTags).flat(); ---- - -{ - Object.entries(byTag) - .sort() - .map(([tag, pages]) => { - const pretty = flattened.find( - (x) => - x.label.toLowerCase() === tag.toLowerCase() || - x.variants?.find((v) => v.toLowerCase() === tag.toLowerCase()), - ); - - if (!pretty) { - throw new Error( - `[TagsUsage] Tag ${tag} not found in /src/schemas/tags.ts`, - ); - } - - return ( - <> - - {pretty.variants && pretty.variants.length > 0 && ( -

- Variants: -

-
    - {pretty.variants?.map((variant) => ( -
  • - {variant} -
  • - ))} -
- )} -

- Used on {pages.length}{" "} - pages. -

-
- -
- - ); - }) -} diff --git a/src/components/index.ts b/src/components/index.ts index f99215e898a3558..8265b8bdb5fa12a 100644 --- a/src/components/index.ts +++ b/src/components/index.ts @@ -58,7 +58,6 @@ export { default as ResourcesBySelector } from "./ResourcesBySelector.astro"; export { default as RSSButton } from "./RSSButton.astro"; export { default as RuleID } from "./RuleID.astro"; export { default as Stream } from "./Stream.astro"; -export { default as TagsUsage } from "./TagsUsage.astro"; export { default as TunnelCalculator } from "./TunnelCalculator.astro"; export { default as Type } from "./Type.astro"; export { default as TypeScriptExample } from "./TypeScriptExample.astro"; diff --git a/src/components/overrides/Head.astro b/src/components/overrides/Head.astro index f82482b1643f919..ba9f8ee92e9ffbb 100644 --- a/src/components/overrides/Head.astro +++ b/src/components/overrides/Head.astro @@ -176,13 +176,6 @@ if (frontmatter.products) { }); } -if (frontmatter.tags) { - metaTags.push({ - name: "pcx_tags", - content: frontmatter.tags.toString(), - }); -} - if (lastUpdated) { const daysBetween = differenceInCalendarDays(new Date(), lastUpdated); @@ -272,7 +265,6 @@ metaTags.map((attrs) => { }); --- - diff --git a/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx b/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx index e9b76decdc4697d..b256783f6f644e7 100644 --- a/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx +++ b/src/content/docs/pages/framework-guides/deploy-a-hono-site.mdx @@ -79,16 +79,6 @@ Every time you commit new code to your Hono site, Cloudflare Pages will automati ## Related resources -### Tutorials - -For more tutorials involving Hono and Cloudflare Pages, refer to the following resources: - - - ### Demo apps For demo applications using Hono and Cloudflare Pages, refer to the following resources: diff --git a/src/content/docs/pages/framework-guides/deploy-a-nuxt-site.mdx b/src/content/docs/pages/framework-guides/deploy-a-nuxt-site.mdx index 8c91a367a090b1c..d26165c7dabc5a0 100644 --- a/src/content/docs/pages/framework-guides/deploy-a-nuxt-site.mdx +++ b/src/content/docs/pages/framework-guides/deploy-a-nuxt-site.mdx @@ -177,12 +177,6 @@ export default defineEventHandler(({ context }) => { ## Related resources -### Tutorials - -For more tutorials involving Nuxt, refer to the following resources: - - - ### Demo apps For demo applications using Nuxt, refer to the following resources: diff --git a/src/content/docs/rules/examples.mdx b/src/content/docs/rules/examples.mdx index fdeaff01be1be2e..fb9036e451017a7 100644 --- a/src/content/docs/rules/examples.mdx +++ b/src/content/docs/rules/examples.mdx @@ -22,5 +22,5 @@ We have a separate listing for [Cache rules examples](/cache/how-to/cache-rules/ diff --git a/src/content/docs/rules/snippets/examples/index.mdx b/src/content/docs/rules/snippets/examples/index.mdx index dc36eaabd58f84d..622ded327f04fca 100644 --- a/src/content/docs/rules/snippets/examples/index.mdx +++ b/src/content/docs/rules/snippets/examples/index.mdx @@ -17,8 +17,4 @@ Refer to the following examples to get started creating your snippet code. Refer to [How Snippets work](/rules/snippets/how-it-works/) and [Create a snippet in the dashboard](/rules/snippets/create-dashboard/) for overall guidance. - + diff --git a/src/content/docs/rules/transform/examples/index.mdx b/src/content/docs/rules/transform/examples/index.mdx index a0bddccc51845e0..a2200ef9d61a49b 100644 --- a/src/content/docs/rules/transform/examples/index.mdx +++ b/src/content/docs/rules/transform/examples/index.mdx @@ -15,5 +15,4 @@ import { ResourcesBySelector } from "~/components"; diff --git a/src/content/docs/style-guide/components/resources-by-selector.mdx b/src/content/docs/style-guide/components/resources-by-selector.mdx index 204f9e370c57ea1..a9de6af5742c3f7 100644 --- a/src/content/docs/style-guide/components/resources-by-selector.mdx +++ b/src/content/docs/style-guide/components/resources-by-selector.mdx @@ -19,7 +19,7 @@ import { ResourcesBySelector } from "~/components"; ``` diff --git a/src/content/docs/workers/examples/index.mdx b/src/content/docs/workers/examples/index.mdx index ddb61bdb288b6e0..1f5fd31b95f178c 100644 --- a/src/content/docs/workers/examples/index.mdx +++ b/src/content/docs/workers/examples/index.mdx @@ -13,8 +13,4 @@ import { GlossaryTooltip, ResourcesBySelector } from "~/components"; Explore the following examples for Workers. - + diff --git a/src/plugins/starlight/route-data.ts b/src/plugins/starlight/route-data.ts deleted file mode 100644 index a5dc83885317a00..000000000000000 --- a/src/plugins/starlight/route-data.ts +++ /dev/null @@ -1,29 +0,0 @@ -import { defineRouteMiddleware } from "@astrojs/starlight/route-data"; -import { tags as allowedTags } from "~/schemas/tags"; - -const tagValues = Object.values(allowedTags).flat(); - -export const onRequest = defineRouteMiddleware(({ locals }) => { - const { entry } = locals.starlightRoute; - const { tags } = entry.data; - - if (tags) { - const transformed = tags.map((tag) => { - const match = tagValues.find( - (val) => - val.label.toLowerCase() === tag.toLowerCase() || - val.variants?.find((v) => v.toLowerCase() === tag.toLowerCase()), - ); - - if (!match) { - throw new Error( - `Invalid tag on ${entry.id}: ${tag}, please refer to the style guide: https://developers.cloudflare.com/style-guide/frontmatter/tags/`, - ); - } - - return match.label; - }); - - entry.data.tags = transformed; - } -}); diff --git a/src/schemas/base.ts b/src/schemas/base.ts index 72920a701effd43..09fc6446ee2f2fa 100644 --- a/src/schemas/base.ts +++ b/src/schemas/base.ts @@ -16,7 +16,7 @@ export const baseSchema = (_context: SchemaContext) => .array() .optional() .describe( - "A group of related keywords relating to the purpose of the page. Refer to [Tags](/style-guide/frontmatter/tags/).", + "A group of related keywords relating to the purpose of the page.", ), external_link: z .string() diff --git a/src/schemas/tags.ts b/src/schemas/tags.ts deleted file mode 100644 index 83282c241185749..000000000000000 --- a/src/schemas/tags.ts +++ /dev/null @@ -1,186 +0,0 @@ -/* This is the allowlist for the tags we allow -in our page frontmatter. Refer to https://developers.cloudflare.com/style-guide/frontmatter/custom-properties/#tags -and https://developers.cloudflare.com/style-guide/frontmatter/tags/ for more details. -*/ - -type Tag = { label: string; variants?: string[] }; - -const data_structures: Array = [ - { label: "JSON" }, - { label: "TOML" }, - { label: "XML" }, - { label: "YAML" }, -]; - -const frameworks: Array = [ - { label: "Angular" }, - { label: "Astro" }, - { label: "Hono" }, - { label: "Next.js", variants: ["nextjs"] }, - { label: "Node.js", variants: ["node", "nodejs"] }, - { label: "Nuxt" }, - { label: "REST API" }, - { label: "Remix" }, - { label: "Ruby", variants: ["rb", "ruby on rails"] }, - { label: "Svelte" }, - { label: "SvelteKit" }, - { label: "Vue.js", variants: ["vue", "vuejs"] }, - { label: ".NET" }, -]; - -const integrations: Array = [ - { label: "Azure", variants: ["Microsoft Azure", "MS Azure"] }, - { label: "AWS", variants: ["Amazon Web Services"] }, - { label: "Docker" }, - { label: "GCP", variants: ["Google Cloud", "Google Cloud Platform"] }, - { label: "Google" }, - { label: "G Suite Group", variants: ["gsuite", "g suite"] }, - { label: "CrowdStrike" }, - { label: "GitHub" }, - { label: "Gitlab" }, - { label: "Grafana" }, - { label: "Kubernetes", variants: ["K8s"] }, - { - label: "Microsoft Entra ID", - variants: ["AzureAD", "Azure Active Directory", "MS Entra ID", "Entra ID"], - }, - { label: "Microsoft" }, - { label: "OpenAI" }, - { label: "MongoDB" }, - { label: "MotherDuck" }, - { label: "PlanetScale" }, - { label: "Postgres", variants: ["PostgreSQL"] }, - { label: "S3" }, - { label: "Salesforce" }, - { label: "SentinelOne", variants: ["Sentinel One"] }, - { label: "Sentry" }, - { label: "Splunk" }, - { label: "ServiceNow", variants: ["Service Now"] }, - { label: "Slack" }, - { label: "Stripe" }, - { label: "Sumo Logic", variants: ["sumo"] }, - { label: "Terraform" }, - { label: "Okta" }, - { label: "WordPress" }, -]; - -const languages: Array = [ - { label: "Go" }, - { label: "GraphQL" }, - { label: "Java" }, - { label: "JavaScript", variants: ["js"] }, - { label: "Markdown", variants: ["md"] }, - { label: "MySQL" }, - { label: "NoSQL" }, - { label: "PowerShell", variants: ["ps"] }, - { label: "Python", variants: ["py"] }, - { label: "Rust", variants: ["rs"] }, - { label: "Shell", variants: ["sh"] }, - { label: "SQL" }, - { label: "TypeScript", variants: ["ts"] }, - { label: "WebAssembly", variants: ["Web Assembly", "wasm"] }, -]; - -const operating_systems: Array = [ - { label: "Android", variants: ["ChromeOS"] }, - { label: "iOS" }, - { label: "Linux" }, - { label: "MacOS", variants: ["OS X"] }, - { label: "Windows", variants: ["ms windows"] }, -]; - -const presentation: Array = [{ label: "Video" }]; - -const product_features: Array = [ - { label: "Web Crypto", variants: ["webcrypto"] }, - { label: "RPC" }, -]; - -const protocols: Array = [ - { label: "FTP", variants: ["file transfer protocol", "ftps"] }, - { label: "ICMP" }, - { label: "IPsec" }, - { label: "IPv4" }, - { label: "IPv6" }, - { label: "JSON web token (JWT)", variants: ["jwt"] }, - { label: "MASQUE" }, - { label: "mTLS" }, - { label: "NetFlow" }, - { label: "MQTT" }, - { label: "OIDC", variants: ["OpenID Connect", "oidc"] }, - { label: "Post-quantum", variants: ["pqc", "post-quantum cryptography"] }, - { label: "QUIC" }, - { label: "RDP" }, - { label: "SAML" }, - { label: "SCIM" }, - { label: "SMTP" }, - { label: "SFTP" }, - { label: "SSH" }, - { label: "SSO" }, - { label: "TCP" }, - { label: "TLS" }, - { label: "UDP" }, - { label: "WebSockets", variants: ["websocket"] }, - { label: "Wireguard" }, -]; - -const use_cases: Array = [ - { label: "A11y", variants: ["accessibility"] }, - { label: "Account takeover" }, - { label: "AI" }, - { label: "AI Agents", variants: ["agentic"] }, - { label: "Analytics" }, - { label: "Authentication", variants: ["auth"] }, - { label: "Automation", variants: ["automations"] }, - { label: "A/B testing", variants: ["ab test"] }, - { label: "Bindings", variants: ["binding"] }, - { label: "Caching", variants: ["cache"] }, - { label: "CLI" }, - { label: "CMS" }, - { label: "Compliance" }, - { label: "Cookies" }, - { label: "CORS" }, - { label: "CSP" }, - { label: "Debugging", variants: ["debug", "troubleshooting"] }, - { label: "DNS" }, - { label: "Forms" }, - { label: "Full stack", variants: ["full-stack"] }, - { label: "Geolocation" }, - { label: "Headers", variants: ["header"] }, - { label: "Integration" }, - { label: "LLM", variants: ["llms"] }, - { label: "Localization" }, - { label: "Logging" }, - { label: "Middleware" }, - { label: "Migration" }, - { label: "MCP" }, - { label: "Phishing" }, - { label: "Playback" }, - { label: "Posture", variants: ["security posture", "device posture"] }, - { label: "Prisma ORM" }, - { label: "Privacy" }, - { label: "Proxying" }, - { label: "Private networks" }, - { label: "Redirects", variants: ["redirect"] }, - { label: "Request modification", variants: ["request"] }, - { label: "Response modification", variants: ["response"] }, - { label: "Scraping" }, - { label: "Security" }, - { label: "SIEM" }, - { label: "SPA" }, - { label: "SSG" }, - { label: "URL rewrite", variants: ["rewrite"] }, - { label: "Voice" }, -]; - -export const tags = { - data_structures, - frameworks, - integrations, - languages, - presentation, - product_features, - protocols, - operating_systems, - use_cases, -}; From 26b9f9903e4443188542e6911b58ea101d3c446f Mon Sep 17 00:00:00 2001 From: kodster28 Date: Mon, 18 May 2026 14:12:20 -0500 Subject: [PATCH 2/6] Remove style guide page --- .../docs/style-guide/frontmatter/tags.mdx | 36 ------------------- 1 file changed, 36 deletions(-) delete mode 100644 src/content/docs/style-guide/frontmatter/tags.mdx diff --git a/src/content/docs/style-guide/frontmatter/tags.mdx b/src/content/docs/style-guide/frontmatter/tags.mdx deleted file mode 100644 index 95cf2d2120a08ed..000000000000000 --- a/src/content/docs/style-guide/frontmatter/tags.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Tags -description: Use validated tags in documentation frontmatter. -products: - - style-guide ---- - -import { TagsUsage } from "~/components"; - -Tags are currently used to filter content in the [`ExternalResources`](/style-guide/components/external-resources/) and the [`ResourcesBySelector`](/style-guide/components/resources-by-selector/) components. - -## Example - -```mdx ---- -title: Example -products: - - product-a -tags: - - foo - - bar ---- -``` - -## Allowed tags and where they are being used - -Tags are validated against an allowlist in [`/src/schemas/tags.ts`](https://github.com/cloudflare/cloudflare-docs/blob/production/src/schemas/tags.ts) which defines the user-facing representation (`label`) and any associated variants. - -The matching is case-insensitive. For example, all of the following values are accepted in the `tags` frontmatter array and will be transformed into `Node.js`: - -- `node.js` -- `NoDe.JS` -- `node` -- `nodejs` - - From 5c13d7dab3ea5dc348102c1f7762b1e66a5bdbf8 Mon Sep 17 00:00:00 2001 From: kodster28 Date: Mon, 18 May 2026 14:14:12 -0500 Subject: [PATCH 3/6] updates --- .../docs/style-guide/components/external-resources.mdx | 4 ++-- .../docs/style-guide/components/resources-by-selector.mdx | 6 ------ src/content/docs/style-guide/how-we-docs/metadata.mdx | 1 - 3 files changed, 2 insertions(+), 9 deletions(-) diff --git a/src/content/docs/style-guide/components/external-resources.mdx b/src/content/docs/style-guide/components/external-resources.mdx index a682de4fc91c1cc..24a6d2a9c0a47a2 100644 --- a/src/content/docs/style-guide/components/external-resources.mdx +++ b/src/content/docs/style-guide/components/external-resources.mdx @@ -21,9 +21,11 @@ import { ExternalResources } from "~/components"; import { ExternalResources } from "~/components"; ## Demo apps + ## Videos + ``` @@ -43,8 +45,6 @@ The type of resources to show, apps or videos. Filter resources down to those where the `tags` property contains any of these strings. -To see a list of the available tags, and which pages are associated with them, refer to [this list](/style-guide/frontmatter/tags/). - ### `products` **type:** `string[]` diff --git a/src/content/docs/style-guide/components/resources-by-selector.mdx b/src/content/docs/style-guide/components/resources-by-selector.mdx index a9de6af5742c3f7..46f238a7049318d 100644 --- a/src/content/docs/style-guide/components/resources-by-selector.mdx +++ b/src/content/docs/style-guide/components/resources-by-selector.mdx @@ -37,12 +37,6 @@ import { ResourcesBySelector } from "~/components"; An array of `pcx_content_type` values to filter which content gets pulled into the component. For example, `types={["example"]}`. -- `tags` - - An array of `tags` values to filter which content gets pulled into the component. For example, `tags={["AI"]}`. - - To see a list of the available tags, and which pages are associated with them, refer to [this list](/style-guide/frontmatter/tags/). - - `products` An array of `products` values to filter which content gets pulled into the component. For example, `products={["D1"]}`. diff --git a/src/content/docs/style-guide/how-we-docs/metadata.mdx b/src/content/docs/style-guide/how-we-docs/metadata.mdx index 329d388c94c9efe..88a42e32eed962b 100644 --- a/src/content/docs/style-guide/how-we-docs/metadata.mdx +++ b/src/content/docs/style-guide/how-we-docs/metadata.mdx @@ -34,7 +34,6 @@ At Cloudflare, we track the following information about different pages: | **Description** | A 1-2 sentence summary that populates the `` tag. Required for all pages with a `pcx_content_type`. | Refer to [frontmatter guidance](/style-guide/frontmatter/#writing-a-description). | | **Product** | The top-level subfolder of the page. | `dns`, `bots` | | **Product Group** | The primary area that each product falls into. | `Application Performance`, `Developer Platform` | -| **Tags** | Specific [attributes](/style-guide/frontmatter/tags/) related to a page's content or purpose. | `AI`, `JavaScript`, `Headers` | | **Content type** | The primary purpose of the page, which corresponds to our listed [content types](/style-guide/documentation-content-strategy/content-types/). | `how-to`, `faq` | | **Last modified** | How many days ago was this page last updated? | `63` | | **Last reviewed** (optional) | How many days ago was this page last reviewed? | `100` | From 11ca86a2b4fce265e595b64466c773dadfa76048 Mon Sep 17 00:00:00 2001 From: "ask-bonk[bot]" Date: Mon, 18 May 2026 19:33:00 +0000 Subject: [PATCH 4/6] Fixed 4 stale tag references in docs. Co-authored-by: kodster28 --- .agents/references/components.md | 2 +- src/content/docs/style-guide/components/index.mdx | 2 +- .../docs/style-guide/components/resources-by-selector.mdx | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/references/components.md b/.agents/references/components.md index 8e2fc5358adb2c9..a07a1d77d5d114b 100644 --- a/.agents/references/components.md +++ b/.agents/references/components.md @@ -758,7 +758,7 @@ Props: `type` (required, `"apps"` or `"videos"`), `tags` (string array, filter b ## ResourcesBySelector -Displays a filterable list of docs pages pulled by `pcx_content_type`, `tags`, and/or `products` frontmatter. Used on example and tutorial index pages. +Displays a filterable list of docs pages pulled by `pcx_content_type` and/or `products` frontmatter. Used on example and tutorial index pages. ```mdx import { ResourcesBySelector } from "~/components"; diff --git a/src/content/docs/style-guide/components/index.mdx b/src/content/docs/style-guide/components/index.mdx index 9482bdc1f46022b..9e3a5cdd70357de 100644 --- a/src/content/docs/style-guide/components/index.mdx +++ b/src/content/docs/style-guide/components/index.mdx @@ -83,7 +83,7 @@ To choose the right component for your use case, browse this table which contain | [`PackageManagers`](/style-guide/components/package-managers) |

Command switcher tabs. Display equivalent installation or execution commands for different package managers.

![DirectoryListing component example](~/assets/images/style-guide/ui-elements/packagemanagers-example.png) | | [`Plan`](/style-guide/components/plan/) |

Product plan availability badge. Show the plan required for a product or specific feature.

![Plan component example](~/assets/images/style-guide/ui-elements/plan-example.png) | | [`RelatedProduct`](/style-guide/components/related-product/) |

Formatted product reference. Visually highlight and link to a specific, complementary Cloudflare product, also featuring the product's logo.

![RelatedProduct component example](~/assets/images/style-guide/ui-elements/relatedproduct-example.png) | -| [`ResourcesBySelector`](/style-guide/components/resources-by-selector/) |

Filterable code example library. Pull and display lists of code examples and resources based on tags and content type.

![ResourcesBySelector component example](~/assets/images/style-guide/ui-elements/resourcesbyselector-example.png) | +| [`ResourcesBySelector`](/style-guide/components/resources-by-selector/) |

Filterable code example library. Pull and display lists of code examples and resources based on content type and products.

![ResourcesBySelector component example](~/assets/images/style-guide/ui-elements/resourcesbyselector-example.png) | | [`Stream`](/style-guide/components/stream/) |

Embeddable video player. Display a video player optimized for Cloudflare Stream.

![Stream example](~/assets/images/style-guide/ui-elements/stream-example.png) | | [`Tabs` and `TabItem`](/style-guide/components/tabs/) |

Switchable content tabs. Allow easy switching between content views for different code languages or configuration methods.

![Tabs example](~/assets/images/style-guide/ui-elements/tabs-example.png) | | [`Type` and `MetaInfo`](/style-guide/components/type-highlighting/) |

Pill-shaped data type badge and metadata annotation about a field or property. `Type` indicates API parameter data types (`String`, `Integer`) and `MetaInfo` indicates metadata constraints (`Required`, `Optional`, `Read-only`).

![Type and MetaInfo example](~/assets/images/style-guide/ui-elements/type-example.png) | diff --git a/src/content/docs/style-guide/components/resources-by-selector.mdx b/src/content/docs/style-guide/components/resources-by-selector.mdx index 46f238a7049318d..4ad6d1f7cde56dd 100644 --- a/src/content/docs/style-guide/components/resources-by-selector.mdx +++ b/src/content/docs/style-guide/components/resources-by-selector.mdx @@ -9,7 +9,7 @@ products: import { Type, MetaInfo } from "~/components"; -The `ResourcesBySelector` component allows you to pull in documentation resources based on the `pcx_content_type`, `tags` and `products` frontmatter properties. +The `ResourcesBySelector` component allows you to pull in documentation resources based on the `pcx_content_type` and `products` frontmatter properties. ## Component @@ -31,7 +31,7 @@ import { ResourcesBySelector } from "~/components"; - `filterables` - An array of frontmatter properties to show in the frontend filter dropdown. For example, `filterables={["tags"]}` will allow users to filter based on each pages' `tags` frontmatter. + An array of frontmatter properties to show in the frontend filter dropdown. For example, `filterables={["products"]}` will allow users to filter based on each pages' `products` frontmatter. - `types` From 4f0fffe679ba7d20d604faa0d123d21ad8031590 Mon Sep 17 00:00:00 2001 From: Kody Jackson Date: Mon, 18 May 2026 14:50:11 -0500 Subject: [PATCH 5/6] Apply suggestion from @kodster28 --- src/content/docs/style-guide/components/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/style-guide/components/index.mdx b/src/content/docs/style-guide/components/index.mdx index 9e3a5cdd70357de..542526879c1994d 100644 --- a/src/content/docs/style-guide/components/index.mdx +++ b/src/content/docs/style-guide/components/index.mdx @@ -83,7 +83,7 @@ To choose the right component for your use case, browse this table which contain | [`PackageManagers`](/style-guide/components/package-managers) |

Command switcher tabs. Display equivalent installation or execution commands for different package managers.

![DirectoryListing component example](~/assets/images/style-guide/ui-elements/packagemanagers-example.png) | | [`Plan`](/style-guide/components/plan/) |

Product plan availability badge. Show the plan required for a product or specific feature.

![Plan component example](~/assets/images/style-guide/ui-elements/plan-example.png) | | [`RelatedProduct`](/style-guide/components/related-product/) |

Formatted product reference. Visually highlight and link to a specific, complementary Cloudflare product, also featuring the product's logo.

![RelatedProduct component example](~/assets/images/style-guide/ui-elements/relatedproduct-example.png) | -| [`ResourcesBySelector`](/style-guide/components/resources-by-selector/) |

Filterable code example library. Pull and display lists of code examples and resources based on content type and products.

![ResourcesBySelector component example](~/assets/images/style-guide/ui-elements/resourcesbyselector-example.png) | +| [`ResourcesBySelector`](/style-guide/components/resources-by-selector/) |

Filterable code example library. Pull and display lists of code examples and resources based on content type or products.

![ResourcesBySelector component example](~/assets/images/style-guide/ui-elements/resourcesbyselector-example.png) | | [`Stream`](/style-guide/components/stream/) |

Embeddable video player. Display a video player optimized for Cloudflare Stream.

![Stream example](~/assets/images/style-guide/ui-elements/stream-example.png) | | [`Tabs` and `TabItem`](/style-guide/components/tabs/) |

Switchable content tabs. Allow easy switching between content views for different code languages or configuration methods.

![Tabs example](~/assets/images/style-guide/ui-elements/tabs-example.png) | | [`Type` and `MetaInfo`](/style-guide/components/type-highlighting/) |

Pill-shaped data type badge and metadata annotation about a field or property. `Type` indicates API parameter data types (`String`, `Integer`) and `MetaInfo` indicates metadata constraints (`Required`, `Optional`, `Read-only`).

![Type and MetaInfo example](~/assets/images/style-guide/ui-elements/type-example.png) | From 170745410194cacb33920f69c6f4b335a91ceaff Mon Sep 17 00:00:00 2001 From: kodster28 Date: Tue, 19 May 2026 10:08:46 -0500 Subject: [PATCH 6/6] keep tags metadata for now --- src/components/overrides/Head.astro | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/components/overrides/Head.astro b/src/components/overrides/Head.astro index ba9f8ee92e9ffbb..3dc7772de790ecb 100644 --- a/src/components/overrides/Head.astro +++ b/src/components/overrides/Head.astro @@ -176,6 +176,13 @@ if (frontmatter.products) { }); } +if (frontmatter.tags) { + metaTags.push({ + name: "pcx_tags", + content: frontmatter.tags.toString(), + }); +} + if (lastUpdated) { const daysBetween = differenceInCalendarDays(new Date(), lastUpdated);