Writing spec — api-rate-limiting.com (expansion phase)

You are writing/uplifting ONE or more pages for a production-engineering reference site about API rate limiting & throttling architecture. Audience: backend engineers, frontend leads, platform teams. Tone: direct, technical, production-focused. No marketing language. Match the register of the existing site (precise, code-heavy, opinionated about tradeoffs).

Output is an 11ty (Eleventy) markdown file at content/<path>/index.md. Markdown allows raw HTML (html: true), so inline <svg>, <details>, and <script type="application/ld+json"> all pass through to the page.

1. Frontmatter (EVERY page — exact keys)

---
layout: <section|topic|subtopic>
title: "<≤60 char title>"
description: "<140–160 char meta description, specific, no fluff>"
slug: <kebab-slug matching the directory name>
type: <pillar|cluster|long_tail>
breadcrumb: "<short breadcrumb label>"
datePublished: 2026-06-20
dateModified: 2026-06-20
---

2. Page anatomy (by type)

Pillar (section layout, ~4000+ words): H1; lead paragraph defining scope/audience + an inline link to a sibling pillar; conceptual overview (vocabulary, no code yet); a comparison table (mechanism / memory / burst tolerance / precision / distributed complexity); one H2 section per child cluster with an inline link to it in the first sentence; architecture & deployment (edge vs origin, fail-open vs fail-closed); operational considerations (X-RateLimit headers, metrics, alerting); a decision guide (bulleted selection rules); a Related block. Top-level overview SVG diagram required.

Cluster (topic layout, ~3000+ words): H1; lead paragraph stating the specific problem + an up-link to the parent pillar in the FIRST sentence; mechanism/spec section (state variables, invariants, O-notation); a configuration reference table (param / type / default / range / effect); implementation walkthrough with runnable, commented code (≥1 Redis/Lua or language-native example); distributed/scaling considerations; failure modes & mitigations; response contract (X-RateLimit-Limit / -Remaining / Retry-After, status codes); an index of child long-tail pages with inline links (if any); a Related block. One strong SVG diagram required.

Long-tail (subtopic layout, ~2000+ words): H1; lead paragraph naming the exact decision/task + an up-link to the parent CLUSTER in the second sentence; problem framing with realistic traffic numbers; a decision/comparison table; step-by-step implementation with runnable code AND an operator checklist using - [ ] task items; gotchas & edge cases (bullets); verification & testing (curl/load-test/metric); a FAQ accordion (3–5 Qs); a Related block. One SVG diagram strongly encouraged (state/sequence/decision).

Every cluster & long-tail MUST contain at least one decision/comparison table (engineers scan for a quick answer). All code blocks use fenced markdown with explicit language tags (typescript, lua, python, javascript, yaml, bash, http).

3. Interlinking (mandatory)

Use the canonical URLs in §7. Link only the FIRST mention of each target. Don’t over-link (one link per target per page).

4. Canonical SVG (RENDER-SAFE — read carefully)

The QA renders built pages in headless chromium with the real site CSS and FAILS if page typography leaks into <text> and overflows the SVG box, if the SVG is zero-size/empty, or references an undefined id.

⚠️ CRITICAL markdown rule: the ENTIRE opening <svg …> tag MUST be on ONE physical line, with a blank line immediately before <svg and a blank line after </svg>. If you split the opening tag across lines, markdown-it closes a <p> mid-tag and the SVG renders EMPTY (a guaranteed QA FAIL). Child elements (<rect>, <text>, …) may each be on their own line.

Follow this template exactly:

<svg viewBox="0 0 760 360" role="img" aria-labelledby="SLUG-t SLUG-d" style="width:100%;height:auto;max-width:760px;display:block;margin:1.75rem auto;font-family:var(--font-sans);">
  <title id="SLUG-t">Short accessible title</title>
  <desc id="SLUG-d">One-sentence description of what the diagram shows.</desc>
  <!-- shapes: use the palette hex values below or currentColor -->
  <rect x="20" y="20" width="200" height="80" rx="10" fill="#e8f0f8" stroke="#1a7fa8" stroke-width="2"/>
  <text x="120" y="65" font-size="16" fill="#0d1f3c" text-anchor="middle" font-family="var(--font-sans)">Label</text>
</svg>

Hard rules — every one matters:

  1. ALWAYS include viewBox. Use the inline style above so it scales with height:auto (preserves aspect, prevents distortion) and never exceeds ~760px.
  2. EVERY <text> MUST carry an explicit numeric font-size attribute (use 12–18 user units). Never rely on inherited size. Also set font-family="var(--font-sans)" on <text>.
  3. Keep ALL text inside the viewBox with ≥10 units of padding from every edge. Estimate label width ≈ 0.62 × font-size × characters; if a label is wide, lower the font-size, shorten it, split into two <text> lines, or widen the viewBox. Text overflowing the box by >2px is a FAIL.
  4. Make every id unique and page-scoped by replacing SLUG with the page’s slug (e.g. token-bucket-impl-t). Two SVGs on one page must not share ids.
  5. Provide <title> + <desc> and role="img". Reference them in aria-labelledby.
  6. Prefer ONE strong diagram that explains the hardest concept (data-flow, sequence, state machine, decision tree, comparison matrix, timeline). No decorative/stock imagery.
  7. Palette (use these hex or currentColor): navy #0d1f3c, navy-mid #162d52, deep-ocean #1a7fa8, sky-blue #5bc8f5, mango #ffb347, tangerine #ff7f2a, light-gray fill #e8f0f8, off-white #f4f8fc, white #ffffff, muted text #6b85a0. Stroke-width 1.5–2. Use text-anchor="middle" for centered labels.
  8. Test mentally: at max-width 760, a font-size="16" label of N chars needs ≈10N px width — keep it within its shape.

5. FAQ accordion + inline schema (long-tail pages)

Use native <details>/<summary> (the site CSS styles these as accordions). Place under a ## Frequently Asked Questions heading:

<details class="faq-item">
  <summary>Question text engineers actually ask?</summary>
  <div class="details-body">
    <p>Concise, concrete answer (2–4 sentences). Code/inline-code allowed.</p>
  </div>
</details>

Then, ALSO emit a matching FAQPage JSON-LD block (escape quotes; plain text answers) right after the FAQ:

<script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [
  { "@type": "Question", "name": "Question text?", "acceptedAnswer": { "@type": "Answer", "text": "Plain-text answer." } }
] }
</script>

6. HowTo schema (pages that are step-by-step how-tos)

For long-tail pages whose core is a numbered build/config procedure (e.g. “Emitting X-RateLimit Headers”, “Prometheus Metrics for Rate Limiting”, “Per-Tier Quota Enforcement With Redis”, “Exponential Backoff With Jitter in the Browser”, “Alerting on 429 Error Rates”), add a HowTo JSON-LD block (in addition to FAQPage) reflecting the page’s steps:

<script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "HowTo", "name": "<page title>",
  "step": [
    { "@type": "HowToStep", "name": "Step 1 name", "text": "What to do." },
    { "@type": "HowToStep", "name": "Step 2 name", "text": "What to do." }
  ] }
</script>

Pillars:

Core Algorithms clusters/long-tails:

Backend Middleware clusters/long-tails:

Frontend Resilience clusters/long-tails:

Observability & Operations (NEW pillar) clusters/long-tails:

8. Forbidden vocabulary (term_lint will FAIL the build)

These are INTERNAL labels — never in reader-facing prose:

⚠️ A real Redis/Kafka/DB cluster is fine ONLY if not preceded by the/a/this/each (e.g. “across Redis cluster nodes” is OK; “a Redis cluster” → reword to “Redis cluster nodes”). Safest: avoid the bare word; say “Redis Cluster mode” / “Redis nodes”.

9. Quality bar