Design a documentation site like MDN

Requirements: many pages, many readers, few writers

A documentation site is a library. Thousands of pages change slowly, a few hundred writers edit them, and millions of developers read them. Most readers land on one page from a search engine, find the line they need, copy a snippet, and leave. Some stay and browse the sidebar to learn a whole topic.

That shape decides almost everything. Pages are read far more often than they change, and every reader of a page sees the same text. So the pages can be built ahead of time into plain HTML files and served from a content delivery network (CDN): a set of servers around the world that keep copies of files close to readers.

Before drawing boxes, ask the questions whose answers move the design. The table lists them, the answer this guide assumes, and what changes if the interviewer answers differently.

Functional requirements

• Read a page: title, summary, body with headings, code blocks, tables, notes, compatibility tables, and a last-updated date.
• Navigate: a sidebar tree for the section, breadcrumbs, an 'on this page' table of contents, and previous and next links.
• Search all pages of the current version and language, with results that jump to the right section.
• Switch version and language while staying on the same topic when it exists.
• Run and edit small code examples inside the page.
• Give feedback: 'Was this page helpful?', a link to edit the page on GitHub, and a link to report a problem.
• Writers: propose a change as a pull request, see a preview of the built site, and get told about broken links before merging.

Non-functional requirements

• Fast first view on a mid-range phone: Largest Contentful Paint (LCP) of 2.5 seconds or less at the 75th percentile, the Core Web Vitals good threshold.
• Little JavaScript: the page reads fine with JavaScript off; scripts only add search, examples, and small widgets.
• Links never break: moved pages redirect, and headings keep their anchors.
• Search friendly: one canonical URL per topic, correct hreflang links, sitemaps, and structured data.
• Build and deploy a merged change in under 10 minutes; a pull request preview in a similar time.
• Accessible: skip link, ordered headings, keyboard-friendly sidebar and search, readable code colours in light and dark themes.

Out of scope

Several parts are their own design problems, and this guide uses them without repeating them. The translation workflow is in Design an internationalization system, a web-based editor for pages in Design a markdown editor with live preview, and the full playground in Design an online code playground like CodePen. The search box widget is in Design an autocomplete, and the shared components and theme of the site are in Design a design system for many teams.

What makes a documentation site hard

A docs page looks simple: text, headings, code. The difficulty is in the numbers and in time. Five properties drive every later chapter.

1. Many pages, built from shared parts. One change to a shared layout, sidebar, macro, or data file can touch thousands of pages, and the build must know which ones.
2. Content is code. Pages change through reviewed pull requests that must pass checks, such as no broken links, before they merge.
3. URLs are a public contract. Answers, blog posts, and code comments link to pages and headings for a decade, so moves and renames must never break them.
4. Several copies of each topic. One topic can exist in three versions and ten languages, some missing or outdated, and both readers and search engines must find the right copy.
5. Mostly static, with a few live parts. Search, the theme toggle, and runnable examples need JavaScript. The rest is fixed HTML, so a full single-page app would waste the reader's phone.

The wireframe below names the parts of a reference page, and each later chapter zooms into one of its regions. Only the search box, the example panel, and the theme toggle need JavaScript to work. The sidebar, breadcrumbs, and table of contents are plain links that script only upgrades, for example by highlighting the current section.

That split is the basis for islands: static HTML everywhere, with small interactive parts that each load and start their own script. The lesson Islands and partial hydration covers the general idea, and the guides Design breadcrumbs and Design a file-explorer tree view cover those two widgets in depth.

Content as code: from Markdown in git to HTML

Start with where the words live, because the build, the review flow, and the link checks all follow from it. The naive answer is a database behind an admin screen, like a blog's content management system (CMS), which works for 200 pages. At 14,000 pages with hundreds of outside contributors, it lacks three things: a review step before a change goes live, a history you can diff and revert per line, and a check that a change does not break links on other pages.

Front matter: the page's metadata

Front matter is a YAML block at the top of the file. It holds what the build needs but the reader does not see as prose: the title, the URL slug, the page type (which picks a layout), and keys into shared data. Validate it with a schema in CI, so a missing page-type fails the pull request instead of rendering a broken page.

---
title: "Element: scrollIntoView() method"
slug: Web/API/Element/scrollIntoView
page-type: web-api-instance-method
browser-compat: api.Element.scrollIntoView
---

{{APIRef("DOM")}}

The **`scrollIntoView()`** method of the {{domxref("Element")}}
interface scrolls the element's ancestors so it becomes visible.

## Syntax

```js
scrollIntoView(options)
```

## Browser compatibility

{{Compat}}

The build pipeline, step by step

The build turns each file into a page in a few separate passes, so each is easy to test and the cache can store each pass's output.

1. Read and validate: parse front matter, check it against the schema, and record the page in a manifest (slug, title, locale, parent).
2. Expand macros: replace {{domxref("Element")}} with a link to the Element page, and {{Compat}} with a table built from shared compatibility data. This is where pages start to depend on other pages and on data files.
3. Markdown to HTML: parse to a syntax tree, add heading ids, highlight code at build time (so no highlighter ships to the browser), and mark live examples.
4. Render the page: put the HTML into the layout for its page-type, with the sidebar, breadcrumbs, table of contents, and metadata tags.
5. Check: every internal link points at a page that exists, and every #anchor points at a heading id on that page.

MDN splits these passes across two tools. A build tool turns Markdown into HTML plus JSON metadata for each page, and the frontend assembles full pages from that JSON. Today the build tool is rari, written in Rust, which replaced the build in the older Node.js project yari; the frontend was rebuilt as server-rendered Lit web components. The split is the useful idea: content transforms and page layout change at different speeds and can be cached separately.

Review with a preview per pull request

A writer who fixes a table wants to see it rendered before merging, and so does the reviewer. So CI builds every pull request and deploys it to its own URL, such as pr-41823.preview.docs.example. Build only the pages the pull request touches plus their dependents (the next chapter shows how), so a preview takes a minute or two. A CI bot then comments the preview links and any problems the checks found on the pull request; MDN's content repository runs a 'PR review companion' workflow for this.

Link checking and broken anchors

Broken links are among the most common docs bugs. A link checker runs on the built HTML, not the Markdown, because macros create links too. It loads every page's set of ids once, then checks every href for two kinds of failure: the target page does not exist (and has no redirect), or the page exists but the #fragment matches no id on it.

The second kind is easy to miss. Someone renames the heading 'Parameters' to 'Arguments', its id changes, and 2,000 links to #parameters silently land at the top of the page.

const ids = new Map(); // url -> Set of ids on that page
for (const page of builtPages) ids.set(page.url, collectIds(page.html));

const errors = [];
for (const page of builtPages) {
  for (const href of collectHrefs(page.html)) {
    const url = new URL(href, page.url);
    if (url.origin !== SITE_ORIGIN) continue;
    const target = redirects.get(url.pathname) ?? url.pathname;
    if (!ids.has(target)) {
      errors.push({ page: page.url, href, kind: "missing-page" });
    } else if (url.hash && !ids.get(target).has(decodeURIComponent(url.hash.slice(1)))) {
      errors.push({ page: page.url, href, kind: "missing-anchor" });
    }
  }
}
if (errors.length) process.exitCode = 1;

Static generation at scale: building 50,000 pages fast

Every page is the same for every reader and changes only when a pull request merges. That is the textbook case for static site generation (SSG): render every page to an HTML file at build time and serve the files from a CDN. The lesson Static generation and ISR covers the idea; here the problem is size.

Do the arithmetic. Over 14,000 English pages plus translations is roughly 50,000 pages (estimate). If one page takes 20 ms to parse, expand macros, highlight code, and render, a single-threaded full build takes 50,000 x 20 ms = 1,000 seconds, about 17 minutes, before upload.

Our budget is 10 minutes from merge to live, and most merges change one page. Rebuilding 50,000 pages to publish a typo fix is the naive approach, and it fails the budget.

Which pages does a change touch?

During a build, record every input each page reads. The kinds of edges, from most to least common:

Cache each pass separately, keyed by a hash of everything that pass read. The content pass reads the page's own file, the data files its macros use, the title and summary of each page it links to, and the build tool's version. The render pass reads the content pass's output plus the layout and the sidebar. If a key is in the cache, reuse the old output; content addressing makes this safe, because any change to any input changes the key, so a stale entry can never match.

type Inputs = { own: string; deps: string[] }; // file paths, or ids of other pages' title and summary

function keyOf(pass: string, inputs: Inputs): string {
  const parts = [pass, TOOL_VERSION, hashOf(inputs.own), ...[...inputs.deps].sort().map(hashOf)];
  return sha256(parts.join("\n"));
}

async function cached(key: string, run: () => Promise<string>): Promise<string> {
  const hit = await cache.get(key);
  if (hit !== undefined) return hit;
  const out = await run();
  await cache.put(key, out);
  return out;
}

async function buildPage(page: Page): Promise<string> {
  const body = await cached(keyOf("content", page.contentInputs), () => renderContent(page));
  const layoutInputs = { own: sha256(body), deps: [page.layoutFile, page.sidebarFile] };
  return cached(keyOf("render", layoutInputs), () => renderLayout(page, body));
}

An alternative is to keep the sidebar out of the page, as a separate cached HTML fragment or JSON file per section, so a sidebar edit rebuilds one file instead of 2,000. The cost is one extra request and a sidebar that appears a moment later, or an include at the edge. Many sites accept the re-render instead, because the content pass is a cache hit and the render pass takes seconds.

Try it. Pick a site size, a change, and whether the cache is warm, and see what rebuilds, how long it takes, and what the CDN must drop.

Deploying to a CDN without broken pages

The output is two kinds of files with opposite caching needs. The lessons HTTP caching and CDN caching explain the headers; here is how they apply.

• Hashed assets (CSS, JavaScript, fonts, images) get a content hash in the file name, such as main.3f9a1c.css. The name changes when the content does, so they can be cached forever: Cache-Control: public, max-age=31536000, immutable.
• HTML pages keep stable URLs, so browsers must recheck them: Cache-Control: public, max-age=0, must-revalidate for the browser, with a longer shared-cache lifetime at the CDN (for example s-maxage=86400) and an explicit purge of the changed URLs on deploy.
• Upload order matters. Upload new hashed assets first, then the HTML that references them, and keep old assets for a few days for readers who still have an old page open.
• Purge only what changed. The build knows which output files changed, so purge exactly those URLs. Purging the whole CDN after every merge sends a wave of cache misses to the origin storage.

Navigation for thousands of pages, and links that never break

A reader on the scrollIntoView() page needs to know where they are (breadcrumbs), what else is nearby (the sidebar), what is on this page (the table of contents), and what to read next (previous and next links). All four are generated at build time from the same source: the page tree.

A sidebar that stays usable at 900 items

• Render the tree as nested lists of links inside a nav landmark with an aria-label such as 'Web APIs'. Groups use details and summary, so collapsing works with no JavaScript and with the keyboard. A links sidebar does not need the full ARIA tree pattern from Design a file-explorer tree view.
• Open only the groups on the path to the current page in the HTML (the open attribute), mark the current link with aria-current="page", and load the rest of a very large tree on demand.
• Keep the current item in view: on load, scroll only the sidebar's own scroll container so the current item sits about one third from the top. Do not call scrollIntoView() on it: that also scrolls the window, which jumps the reader past the page title.

'On this page' with a scroll spy

The table of contents is a list of links to the page's h2 and h3 headings, built at build time from the syntax tree. The upgrade is a scroll spy: highlighting the section the reader is in. The naive version measures every heading with getBoundingClientRect() on each scroll event, which forces layout many times per second. IntersectionObserver lets the browser track the headings itself and calls back only when a heading enters or leaves a band of the viewport.

const links = new Map(
  [...document.querySelectorAll<HTMLAnchorElement>(".toc a")].map((a) => [a.hash.slice(1), a]),
);
const visible = new Set<string>();

const io = new IntersectionObserver(
  (entries) => {
    for (const e of entries) {
      if (e.isIntersecting) visible.add(e.target.id);
      else visible.delete(e.target.id);
    }
    const first = [...links.keys()].find((id) => visible.has(id));
    if (!first) return; // keep the last highlight between headings
    for (const [id, a] of links) {
      if (id === first) a.setAttribute("aria-current", "true");
      else a.removeAttribute("aria-current");
    }
  },
  { rootMargin: "-64px 0px -60% 0px" }, // a band below the sticky header
);

for (const id of links.keys()) {
  const h = document.getElementById(id);
  if (h) io.observe(h);
}

Stable heading anchors

Heading ids are generated from the text: 'Return value' becomes return_value on MDN (lowercase, spaces to underscores) and return-value on most other generators. That makes anchors fragile, because editing the text changes the id.

• Allow an explicit id in the Markdown, such as ## Returns {#return_value} (Docusaurus supports this syntax), and add one whenever a heading people link to is renamed.
• Never change the slug function. Changing it once breaks every deep link on the site.
• De-duplicate ids on a page by appending _2, _3 in document order, so the same page always gets the same ids.

For renamed headings that external sites already link to, a small inline script can map old fragments to new ids. On load, if location.hash matches no id, it looks the hash up in a per-page alias list from front matter and scrolls to the new heading. The server cannot help here, because browsers never send the fragment.

Redirects when pages move

Pages move: sections get reorganized, APIs get renamed. Each move adds a line to a redirects file that lives in git next to the content. MDN keeps one per locale, such as files/en-us/_redirects.txt, with one tab-separated 'from' and 'to' pair per line, written by its command-line tool and checked by a CI workflow. The build turns the list into CDN rules that answer with 301 Moved Permanently, so search engines move the ranking to the new URL.

• Collapse chains. If A moved to B and later B moved to C, rewrite A to point at C directly. Every hop costs a round trip and search engines may stop following long chains.
• Reject loops and dead targets in CI: a redirect to a missing page is still a broken link.
• Move and redirect in one pull request. A move command renames the folder, rewrites internal links, and appends the redirect; MDN's redirects file even says not to edit it by hand.
• Never delete redirects. Old links live for years, and a file of tens of thousands of lines is fine once compiled to a hash map at the CDN.

Versions and languages: many copies of one topic

Product docs (not MDN, which documents one evolving platform) must keep v1, v2, and v3 readable side by side, because customers run old versions for years. With ten locales, one topic can have 30 copies. The questions are how to build them, where the switcher sends a reader when a copy is missing, and which copy search engines should rank.

Where the switcher lands

The reader is on /v3/guides/streaming and picks v1. The naive switcher sends them to the v1 home page, and they must find the topic again. A good switcher tries, in order: the same path in v1; a mapping from the version's redirects file (the page was renamed between versions); the closest parent that exists, such as /v1/guides/; and only then the version's home page. The build writes one small manifest per version listing its paths, so the decision runs in the browser with no server.

Locales add one step before the parent: when the topic exists in English but not in the reader's language, show the English content at the French URL, with a notice in French. Docusaurus behaves the same way, since a page with no translated file is built from the original. A reader who wanted French and gets the right English page is better served than one who gets a French section index.

Translations that lag behind English

English changes daily; volunteers translate weeks or years later. A translated page that silently disagrees with English is worse than no translation, because the code in it may be wrong. So record which English commit a translation was made from in its front matter, as MDN's translated-content repository does with an l10n.sourceCommit field.

At build time, compare that commit with the last commit that changed the English source. If English has moved on, render a banner: 'This page was translated from English and may be out of date. View the English page.' Sort a dashboard of outdated pages by traffic, so translators fix the most read ones first.

Canonical URLs and hreflang

• Translations are not duplicates. Each locale's page has a canonical URL pointing at itself, never at English. Pointing a French page's canonical at English tells search engines to drop the French page.
• hreflang links tell search engines which pages are the same topic in other languages. Each page lists every locale's copy, including itself, and the links must point both ways: Google ignores a pair that does not. Add x-default for the page to show when no locale matches. The lesson i18n performance and SEO covers the details.
• Fallback pages (English content served under a French URL) are duplicates of the English page. Point their canonical where the English page's canonical points, and leave them out of hreflang and the sitemap. Google advises against noindex for this, because a canonical does the job.
• Old versions usually point their canonical at the same topic in the latest version when the content is nearly the same, so ranking goes to the current docs; Read the Docs, for example, builds canonical URLs from the project's default version. When a topic exists only in v1, it keeps a self canonical. A canonical is a strong hint, not a rule, and only canonical URLs belong in hreflang.
• Banners on old versions: 'You are reading v1 docs. The latest is v3', with a link to the same page in v3 when it exists.

<link rel="canonical" href="https://docs.example/fr/v3/guides/streaming" />
<link rel="alternate" hreflang="en" href="https://docs.example/en/v3/guides/streaming" />
<link rel="alternate" hreflang="fr" href="https://docs.example/fr/v3/guides/streaming" />
<link rel="alternate" hreflang="ja" href="https://docs.example/ja/v3/guides/streaming" />
<link rel="alternate" hreflang="x-default" href="https://docs.example/en/v3/guides/streaming" />

Search across thousands of pages

Search is the second front door, after the search engine that brought the reader in. Readers type an API name ('scrollint') and expect that page first, or a task ('center a div') and expect the right section of the right guide. The search box widget, its keyboard behaviour, and the results list are covered in the guides Design an autocomplete and Design a search results page. The docs-specific question is where the index lives.

The naive approach builds one full-text index with Lunr or FlexSearch at build time and downloads it on first search. For over 14,000 pages of text that index is many megabytes per locale (estimate), downloaded by a reader who wanted one result on a phone. It also grows with every version you add.

Making docs search feel instant

• Two tiers. Ship a small title index (slug, title, and a short type label, about 15 bytes per page compressed, so roughly 200 kB for 14,000 pages: estimate) that answers API-name queries in under 10 ms, and query the full-text index in parallel for prose. Show title hits first.
• Load on intent. Import the search code when the reader focuses the box, presses /, or presses Ctrl+K (Cmd+K on macOS), not on page load. Starting the import on hover or focus hides most of the delay. The guide Design a command palette covers the shortcut and modal patterns.
• Results with sections. Each result shows the page title, the matched heading, and a snippet; the link goes to page#heading-id, so stable anchors from the navigation chapter pay off again.
• Filters that match docs. Type (guide, reference, tutorial), and a default scope of the current version and locale with a link to 'search all versions'.
• Log zero-result queries. They show which pages and synonyms are missing.

let pagefind: Promise<Pagefind> | null = null;

function loadSearch() {
  // The bundle path includes locale and version, so each has its own index.
  pagefind ??= import(/* @vite-ignore */ `/${locale}/${version}/pagefind/pagefind.js`);
  return pagefind;
}

async function onQuery(q: string, filters: { type?: string }) {
  const pf = await loadSearch();
  const res = await pf.debouncedSearch(q, { filters }, 150);
  if (res === null) return; // a newer keystroke replaced this search
  const top = await Promise.all(res.results.slice(0, 8).map((r) => r.data()));
  render(
    top.flatMap((page) =>
      page.sub_results.slice(0, 2).map((s) => ({ title: page.meta.title, section: s.title, url: s.url, excerpt: s.excerpt })),
    ),
  );
}

Live code examples without a heavy page

A reference page is better when the reader can change x * 2 to x * 3 and see the output. MDN does this in two ways. Many reference pages open with an interactive example: the writer puts an {{InteractiveExample}} macro in the Markdown, followed by code blocks marked interactive-example, and the page renders them as an editor with a console or a live output. Longer live samples render their HTML, CSS, and JavaScript in an iframe, and a Play button opens the code in the separate MDN Playground.

{{InteractiveExample("JavaScript Demo: Array.prototype.map()")}}

```js interactive-example
const array = [1, 4, 9, 16];
const mapped = array.map((x) => x * 2);
console.log(mapped);
// Expected output: Array [2, 8, 18, 32]
```

Two problems follow. Weight: a real code editor with syntax highlighting and autocomplete is hundreds of kilobytes of JavaScript, and loading it on thousands of pages for the few readers who click Run would wreck the performance budget. Safety: the code the reader types runs on our origin unless we isolate it, so a pasted snippet could read cookies or rewrite the page.

The upgrade has more states than it looks, and each one needs a visible label: the download can fail, the code can throw, and an infinite loop can freeze the iframe. The state machine below covers them.

• Start the import on hover or focus of the Run button, which removes most of the wait on desktop.
• Reserve the space. The output panel has a fixed minimum height in the static HTML, so running the example does not shift the text below it (Cumulative Layout Shift).
• One editor bundle per page, shared by all examples on it; each example gets its own iframe only when run.
• Guard against loops. The parent cannot interrupt a busy iframe, but a separate-origin iframe can run in its own process, and the parent can show 'Not responding: Reset' after a timeout and replace the iframe.
• Test the examples in CI. Run each JavaScript example in a headless browser and compare the console output with the 'Expected output' comment, so examples never rot.

Architecture and data model: a build system, a CDN, and a few islands

Almost all the work happens before a reader arrives: in CI, the content becomes files on a CDN. In the browser, a static page starts only a few small islands, each with its own script. There is no app shell and no client-side router; a link click is a normal page load, which is fast because the next page is a small cached HTML file. The lesson Routing explains when a multi-page site beats a single-page app, and a docs site is the clearest case.

Why these boundaries? The build sits in CI because that is where review happens: a page that fails a check never reaches the CDN. The CDN does only simple, cacheable work (redirects, headers), not rendering, so there is no server to scale on a traffic spike.

Each island loads its own code, so the reader who only reads downloads only the small enhancers, a few kilobytes. The feedback API is separate because it is the only thing that writes, and it must never be able to slow down a page view.

How data moves

Follow one merged pull request to one reader. The commit triggers the build, which writes changed HTML, manifests, and search chunks to storage and purges the changed URLs. A reader's request misses the CDN once and is then served from the edge; the browser renders the HTML at once and fetches the search bundle only if the reader starts a search. The only data going back up is feedback votes and analytics beacons.

Data model: the files are the interfaces

A docs site has almost no runtime API. Its real interfaces are files: the front matter writers fill in, the manifests the build writes for the browser, and the search index. Getting these shapes right matters more than any endpoint, because thousands of files and every client script depend on them. Most data is fixed at build time and baked into HTML or small JSON files on the CDN; very little is per reader.

type PageType = "guide" | "web-api-interface" | "web-api-instance-method" | "css-property";

type PageMeta = {
  slug: string;                 // "Web/API/Element/scrollIntoView"
  locale: string;               // "en-US"
  version: string;              // "v3", or "current" for unversioned docs
  title: string;
  pageType: PageType;
  browserCompat?: string;       // key into shared compatibility data
  sidebar?: string;             // which sidebar config to use
  headings: { id: string; text: string; level: 2 | 3 }[];
  lastModified: string;         // ISO date of the last git commit touching the file
  sourceCommit?: string;        // translations: English commit it was made from
  outdated?: boolean;           // computed: English changed since sourceCommit
};

// /v3/manifest.3c1e9a.json: which paths exist, per locale, for the switcher.
type VersionManifest = {
  version: string;
  locales: Record<string, string[]>;   // "fr" -> list of slugs that exist in French
  renamed: Record<string, string>;     // old slug -> new slug within this version
};

The few runtime interfaces

The browser makes only three kinds of requests after the page: manifest and search files (static, cacheable forever because their names are hashed), the example runner iframe (static, on its own origin), and feedback. Feedback is the only API that needs a server, and it is write-only from the page's point of view.

POST /api/feedback HTTP/1.1
Content-Type: application/json

{ "page": "/en-US/docs/Web/API/Element/scrollIntoView",
  "version": "current", "helpful": false,
  "reason": "code-sample-wrong", "comment": "The options example throws in Safari",
  "clientId": "a91f..." }

HTTP/1.1 202 Accepted

HTTP/1.1 429 Too Many Requests
Retry-After: 60

The page sends the vote with fetch(url, { method: "POST", keepalive: true }), so it survives the reader navigating away, and shows 'Thanks' at once without waiting for the reply. The clientId is a random id in localStorage, so a reader who clicks twice changes their vote instead of adding another. A free-text comment is sent only if the reader types one, and the server strips anything that looks like an email or API key before storing it.

Performance, SEO, accessibility, and feedback

The design already avoids the big costs: no server rendering per request and no framework runtime for reading. This chapter covers what is left, with the docs-specific details.

Performance budget

Set a budget per page type and fail CI when a pull request breaks it. A reasonable budget for a reference page (estimates): HTML 30 to 80 kB compressed, CSS under 40 kB, JavaScript under 30 kB before any island loads, and no web font on the critical path for body text. Code is already highlighted at build time; the other levers are below.

• Fonts. Use the system font stack for prose or one self-hosted variable font with font-display: swap; a monospace font for code can load later because code blocks have a fallback that fits.
• Compatibility tables and big diagrams below the fold get content-visibility: auto with a size hint, so the browser skips their layout until the reader scrolls near.
• Measure in the field. Collect Core Web Vitals from real readers, split by page type and locale, so a regression after a macro change shows up on the page type it hit (see the lesson Core Web Vitals).

SEO and sharing

• Titles that match searches. 'Element: scrollIntoView() method' beats 'scrollIntoView'. Put the API name first and the section after.
• Structured data. Add JSON-LD with a BreadcrumbList, which Google can show as the path in desktop results (the guide Design breadcrumbs covers the markup). Describe the page as a schema.org TechArticle, a subtype of Article, with its headline and modification date; Google documents only Article, NewsArticle, and BlogPosting for its article features, so treat the subtype as extra meaning, not a promised rich result.
• Open Graph images per page, generated at build time from one template, so a shared link shows 'scrollIntoView() method, Web APIs' instead of a generic logo. Regenerate one only when its title changes.
• Sitemaps per version and locale, joined by a sitemap index. A single sitemap file may list at most 50,000 URLs, so 50,000 pages need splitting anyway. Leave out fallback pages and old versions whose canonical points elsewhere.
• Last modified dates from git in the sitemap, matching the date shown on the page.

Accessibility

• A skip link as the first focusable element jumps past the header and a 900-item sidebar to the main landmark. Without it a keyboard user tabs through hundreds of links on every page.
• One h1, then h2 and h3 in order. Screen reader users jump by heading; the table of contents is built from the same headings, so a lint rule on heading order fixes both. The lessons Semantic HTML and Keyboard navigation cover the basics.
• Code blocks: a pre that scrolls sideways gets tabindex="0" and a label so keyboard users can scroll it. The copy button has a specific accessible name such as 'Copy JavaScript example' and announces 'Copied' through a polite live region.
• Dark mode with readable code. Pick a code theme for each mode and check every token colour against its background for 4.5 to 1 contrast. Apply the saved theme with a tiny blocking script in the head so the page does not flash light first.

Offline docs, briefly

Developers read docs on planes and trains. A service worker can cache pages as they are visited, so the last 50 pages read work offline, and the search island can keep its loaded chunks. For HTML use network first with a cache fallback, so readers online always see the latest page; the lesson Service worker caching covers the strategies.

Full offline copies are a bigger feature. DevDocs, for example, lets readers pick documentation sets to download and stores them in the browser. For a site of this size, offer downloads per section ('Download CSS docs, about 15 MB': estimate) rather than for everything.

Feedback loops

• 'Was this page helpful?' with a reason when the answer is no (wrong code, missing info, hard to follow). Rank pages by 'no' votes per thousand views to find the worst pages, not the most viewed ones.
• 'Edit on GitHub' links to the source file of the current version and locale, a path the build already knows.
• 'Report a problem' opens a prefilled issue with the page URL, version, locale, and browser.
• Last updated from the last git commit that touched the file, with a link to its history.

Running it in the interview

In 45 minutes you cannot cover every chapter. The interviewer wants to see that you spot the shape early (static, huge, versioned, linked from everywhere) and spend your time on the decisions that shape implies. A plan that works:

Draw the pipeline first, not the page. Many candidates start with a component tree; the stronger move is to notice that the hard parts of this problem are in the build and in URL design. Then sketch the page wireframe quickly, naming the islands.

Follow-up questions to expect