Building docs.recurly.com

Anatomy of a guide page

1. Overview rp-overview

   Two to four sentences on what the page covers.

2. Plan pill rp-plan

   Who can use the feature, with fixed wording per plan so availability reads the same everywhere.

3. Callout rp-callout

   Four variants (note, tip, important, warning), each with its own icon and color.

4. Section pills rp-toc

   Numbered jump links to every top-level section, generated from the headings.

5. Requirements list rp-list

   Under a Prerequisites or Limitations heading.

6. Definition rp-definition

   Plain-language “what is this and why does it exist,” distinct from the overview.

7. Key benefits rp-benefits

   Three or five auto-fit; exactly four switch to a 2×2 grid.

// Capture phase: runs before ReadMe's
// own React click handlers
window.addEventListener("click", handleClick, true);

// Child-list changes only, so this script's
// own class/href writes can't loop back
state.observer = new MutationObserver(handleRouteCheck);
state.observer.observe(document.body, {
  childList: true, subtree: true,
});

// ReadMe updates URL, article, and active
// classes in separate render passes
[50, 150, 400, 900].forEach((ms) =>
  setTimeout(queueApply, ms));

• Stable hooks only

  Targets ReadMe’s rm- classes and ARIA labels, never the hashed CSS-module names that change on every deploy.

• Idempotent by construction

  A global key with destroy() tears down the previous instance if the script loads twice.

• Respects user intent

  Cmd/Ctrl/Shift-clicks and middle-clicks keep native behavior, with the corrected URL already in place.

Guardrails learned the hard way

• No blank lines inside a div

  ReadMe’s MDX parser exits HTML context on a blank line and renders the rest as raw code.

• {curly} placeholders become ALL_CAPS

  A single {site_id} is evaluated as JSX and blocks the whole page.

• CodeTabs, not Tabs, for code

  Consecutive fences with no blank line render as one multi-language block.

• Never invent; never alter code

  Suspect code gets a TODO for developer review instead of a silent fix.

135/146

Engage pages last updated in September–October 2026, the window in which the hub moved onto the design system

ReadMe updatedAt, read from each published page