Authoring spec — webhook-architecture.com expansion phase

You are writing/upgrading Eleventy markdown pages under content/. Every page is an index.md whose URL is its folder path. Match the existing site’s dense, expert, production-grade tone (read a sibling file first). All code uses Python for delivery/retry/ops topics and TypeScript for schema/validation/security topics, consistent within a page.

File anatomy (EVERY page, in this exact order)

  1. YAML frontmatter — only a title:
    ---
title: "Concise Page Title (< 60 chars, no site name)"
---
  2. Inline JSON-LD <script type="application/ld+json"> with an @graph containing:
  3. # H1 Title — a fuller title than the frontmatter one.
  4. Lead paragraph(s) with the required up-link (see Interlinking).
  5. Body sections per the page-type blueprint below. Use ##/### headings that NAME the specific technical concept (never “Introduction”/“Conclusion”/“Overview” alone).
  6. One custom inline SVG diagram (see SVG rules) placed where it explains the hardest concept — usually right after the lead or inside the architecture section.
  7. ## Related block at the very end: a markdown bullet list of 3–5 links (see Interlinking).

Page-type blueprints

Pillar (~1500-1900 words): lead defining the domain + up-link to home /; an architecture/lifecycle section (carry the overview SVG here); 3 core-concept sections with trade-offs; a numbered “Production Implementation Checklist” (mirror it in HowTo JSON-LD); a failure-mode table (mode | impact | mitigation, ≥4 rows); one runnable annotated code block; an operational/observability section; Related block = 4–6 links to child clusters + 1–2 cross-pillar links.

Cluster (~1200-1600 words): lead with narrow problem + up-link to parent pillar IN THE FIRST SENTENCE; 2–4 named implementation patterns with trade-offs; a security/validation section; an operational/CI-CD section; failure-mode table (≥4 rows); one runnable code block; a debugging checklist (markdown task list - [ ]); Related = 2–3 sibling clusters + 1–2 child long-tails + up-link to pillar.

Long-tail (~1100-1500 words): lead framing ONE specific scenario + up-link to parent cluster + cross-link to one sibling; a Prerequisites list; numbered step-by-step with runnable code at each critical step; a Verification/testing section (unit test, curl, or log assertion); a “Failure modes and gotchas” section (2–4 specific pitfalls + fixes); Related = 2–3 sibling long-tails + up-link to cluster.

Every table needs a header row + ≥4 data rows.

Interlinking (mandatory)

Inline-link the FIRST mention of any concept that has its own page, woven into prose (not footnotes). Use the link map below. Cluster pages link back to their pillar in the first sentence; long-tail pages link to their cluster and ≥2 sibling long-tails. End every page with a ## Related bullet list.

Term hygiene (CI-enforced)

NEVER use the words pillar, cluster (in the IA sense), long-tail, hub-and-spoke, supporting page, content silo, internal linking structure in reader-facing prose. “Kafka cluster”/“DB cluster” is fine.

SVG rules (CI-enforced — read carefully, broken SVGs fail the build)

Wrap each diagram:

<figure class="diagram">
<svg viewBox="0 0 760 360" role="img" aria-label="short description" xmlns="http://www.w3.org/2000/svg">
  <title>Short title</title>
  <desc>One-sentence description.</desc>
  ... shapes ...
</svg>
<figcaption>Caption naming what the diagram shows.</figcaption>
</figure>

HARD REQUIREMENTS so it survives the headless render check:

PILLARS:

FUNDAMENTALS children:

SECURITY children:

RESILIENCE children:

TESTING & LOCAL DEV (NEW pillar) children: