Case Study: Stripe Docs Performance

Introduction

Stripe Docs set industry bar for developer documentation performance: fast TTFB, readable HTML source, syntax-highlighted code blocks without megabytes of JS, and navigation that works before hydration. Stripe publicly optimized docs for Core Web Vitals while keeping technical content crawlable — a case study in HTML structure for content-heavy developer sites.

Business problem

Business pressure: Developers abandon slow docs during integration — directly delays Stripe revenue activation. Docs compete with MDN and Google — SEO for API reference terms drives top-of-funnel. HTML architecture must make code samples copy-pasteable in view-source and fast on conference WiFi.

• Activation: Faster docs → faster integrations → more processed volume.
• SEO: API reference pages compete for "[term] API" queries — need clean semantic HTML.
• Brand: Stripe's polish includes sub-second doc pages — perf is credibility.

Why this feature exists

Engineering motivation: Early docs on heavy client frameworks hurt mobile perf. Stripe migrated toward static generation and selective enhancement — HTML-first docs with minimal client JS for search and sidebar.

• Decision: Pre-render reference HTML at build time vs client fetch navigation graph.
• Rejected: SPA docs with empty shell — bad for SEO and first paint.
• Public write-ups: Stripe engineering blog documented CDN, prefetch, and font strategies tied to HTML output.

Browser internals

Inside the engine: Docs pages ship full article HTML in first response — pre/code blocks in DOM for immediate read and copy. Sidebar nav uses real links — cmd+click works without JS. Syntax colors via CSS classes on spans from build-time highlighter — not client Prism on every page load.

• Preload: Critical doc font subset preloaded; mono font for code blocks async.
• Nav: Link prefetch on hover optional — must not starve LCP bandwidth.

Rendering workflow

Rendering path: MDX/Markdown → static site generator → HTML files to CDN → edge serves immutable HTML per doc version → client adds search and theme toggle as enhancement. Version switcher links to versioned URL paths — real hrefs for bookmarking and crawl.

• ISR rare: Docs mostly immutable post-deploy — cache aggressively.
• Search: Algolia or similar — search UI is enhancement; sitemap.xml lists all reference URLs in HTML ecosystem.

Feature deep dive

Docs HTML patterns: article landmark, h1 api resource name, h2 sections Parameters/Returns, pre>code with language class, table for parameter lists (thead/th), aside for notes, breadcrumb nav, link rel=canonical per versioned URL.

• Anchor headings: id on h2 for deep links — hash navigation works without JS.
• Code copy: Button enhances pre block — code still selectable in HTML without JS.

<article>
  <nav aria-label="Breadcrumb"><a href="/docs/api">API</a> › PaymentIntent</nav>
  <h1>PaymentIntent</h1>
  <p>Create a PaymentIntent object…</p>
  <h2 id="parameters">Parameters</h2>
  <table>
    <thead><tr><th>Name</th><th>Type</th></tr></thead>
    <tbody><tr><td><code>amount</code></td><td>integer</td></tr></tbody>
  </table>
  <pre><code class="language-bash">curl https://api.stripe.com/v1/payment_intents</code></pre>
</article>

Accessibility analysis

A11y architecture: Docs tables need th scope; code blocks announced with language; skip to content link in shell; theme toggle respects prefers-color-scheme in CSS before JS flash.

• Contrast: Syntax theme meets WCAG in light and dark HTML class on html element.

SEO impact

SEO architecture: Each API object page unique title/description in head HTML. Structured data optional for tech docs; clean headings outperform spammy FAQ schema. Sitemap lists reference URLs; internal linking in sidebar HTML exposes graph to crawlers.

• Duplicate: Versioned docs use canonical to latest or explicit version policy — documented in HTML head.

Security considerations

Security boundary: Docs include user-supplied example keys — must sanitize MDX components. CSP on docs domain limits inline script — code samples are text not executable. Third-party search scripts allowlisted narrowly.

• XSS: MDX custom components vetted — no raw HTML passthrough from community edits without review.

Performance impact

Performance (core case): Stripe documented removing unnecessary JS, self-hosting fonts, optimizing HTML cache headers, and measuring LCP on code block + heading. Static HTML eliminated client routing waterfall. Perf budget per page type — reference vs guide vs homepage. RUM on docs with segment by country CDN PoP.

• LCP: Often h1 + intro paragraph — in first HTML without waiting for sidebar JS.
• CLS: Reserve space for code blocks with min-height or font metrics in CSS linked early.
• TTFB: CDN cache hit ratio KPI — HTML immutable naming with content hash on assets not on HTML path.

Real production example

Real engineering decision: Stripe moved docs toward static HTML generation with minimal client JavaScript, public engineering posts described shedding client-side routing for reference pages, pre-rendering navigation links, and optimizing font loading in the document head. Code highlighting shifted build-time where possible. Result: materially better Lighthouse scores and developer NPS on slow networks — measured before/after with RUM and Search Console crawl stats stable/improved.

• Metric: LCP and TTFB p75 improved on mobile emerging markets after static HTML push.
• Trade-off: Less flashy client transitions — accepted for docs use case.
• Lesson: Developer docs should be SSG HTML first; interactivity is garnish.

Enterprise usage

Enterprise takeaway: Internal API portals should copy Stripe pattern — SSG reference HTML, table semantics for params, versioned real URLs, perf budgets in CI Lighthouse on sample pages.

• Portal: Same HTML discipline for partner docs behind login — perf still matters.

Common production failures

What breaks in prod: Client-only sidebar — Google indexed pages without nav context temporarily during bad deploy. Font swap caused CLS on code blocks — fixed with metric-matched fallback in @font-face. Accidentally shipped 2MB JS search bundle on every page — rolled back via bundle analysis gate.

• Incident: Hydration mismatch on theme toggle doubled h1 — hotfix same-day; added DOM snapshot test.

Architecture review questions

• Is full article content in first HTML response?
• Are nav links real hrefs crawlable without JS?
• Is syntax highlighting build-time or client blocking?
• What Lighthouse perf budget on reference page template?
• Are versioned docs canonical policy explicit in head?

Hands-on project

Project: Build one API reference page SSG HTML with table params, pre/code sample, breadcrumb links, and Lighthouse perf ≥95. Add CI job failing if JS bundle on page exceeds 50KB.

• Deliverable: HTML output + Lighthouse CI config.

Interview questions

Try it yourself

Edit the HTML, CSS, or JS panels — the preview updates as you type.

Summary

Stripe Docs performance HTML demonstrates static generation, semantic reference markup, build-time highlighting, crawlable navigation links, and strict JS/font budgets — the model for fast, SEO-visible developer documentation sites.