Docs site performance

Readers hit documentation mid-task, often from a search result. A slow page loses them. Fortunately docs are the ideal workload for static rendering.

Performance budget#

Set targets and fail CI when they regress.

Render statically#

With the Next.js App Router, prerender every docs page at build time. Pages are plain HTML on a CDN and only interactive pieces hydrate.

export function generateStaticParams() {
  return docs.map((doc) => ({ slug: doc.slug }));
}

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const doc = docs.find((d) => d.slug === slug);
  if (!doc) notFound();
  return <Article doc={doc} />;
}

Keep client JavaScript small#

• Render Markdown on the server. Send HTML, not the parser.
• Hydrate only what needs state: search, code-copy buttons, the theme toggle.
• Load heavy widgets, like an API console, after the main content.

Make search instant#

Build a compact index at build time (titles and headings) and filter it in memory. Add a hosted search service only when full-text across thousands of pages is needed.

Accessibility is performance#

A page that a screen reader can't navigate has failed just as surely as one that takes ten seconds to load.

• Use real headings and landmarks
• Keep visible focus styles
• Respect prefers-reduced-motion and prefers-color-scheme
• Give every code block a copy button reachable by keyboard

{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.95 }],
        "categories:accessibility": ["error", { "minScore": 0.95 }]
      }
    }
  }
}