MDN Web Docs — JavaScript & Web API Reference

Overview

Covers the full read workflow on MDN Web Docs: searching for APIs, reading reference pages, navigating article sections, and retrieving structured results via the JSON search API. The search API is the recommended path for automation — no browser, no JS required, returns clean JSON with article summaries.

Not covered here: Editing articles, MDN Plus subscriptions, account management. All reading is fully public.

Auth required for: None for reading. All documentation is public.

Agent Paths

Programmatic [API] — No browser needed

• Search: GET https://developer.mozilla.org/api/v1/search?q={query}&locale=en-US&limit=10
• Direct article fetch: GET https://developer.mozilla.org/en-US/docs/Web/API/{name} (returns full HTML)

Required headers: None

Browser [Browser] — Requires browser control

• Use selectors and Navigation Flows below
• Required when: reading rendered article sections, navigating between related APIs via sidebar, checking browser compatibility tables interactively

When to use which

• Default to Programmatic for search and finding the right article URL
• Use Browser when: the task requires reading a specific article section, following sidebar links, or confirming browser compatibility data
• Direct URL navigation beats search when you know the API name — URL pattern is predictable: https://developer.mozilla.org/en-US/docs/Web/API/{APIName}

Agent Knowledge Note

Most frontier LLMs have extensive MDN content in training data — JavaScript, Web APIs, HTML, CSS are all well-covered. This skill adds value via:

• MDN redesigned in 2025–2026 — class names changed significantly. Old selectors (.document-toc, article.main-page-content, [aria-label*="breadcrumb"]) no longer exist. See Page Structures for current selectors.
• Homepage has no static search input — the search bar is JS-triggered only (keyboard shortcut or button interaction). There is no <input> in the static HTML. Use the JSON API for all search.
• mdn_url needs base URL prepended — the API returns paths like /en-US/docs/Web/API/Fetch_API, not full URLs. Add https://developer.mozilla.org prefix.
• Stable section anchors — #browser_compatibility, #specifications, #parameters, #return_value are present on all reference pages and have not changed. These are reliable navigation targets.
• Browser compat table is JS-rendered — the #browser_compatibility section loads data dynamically. For programmatic compat data, use the @mdn/browser-compat-data npm package.

For private/internal documentation systems built on MDN's architecture, treat all sections as primary.

Site Map

Page Structures

Homepage

No static search input exists. The search bar is dynamically triggered. Use the JSON API for all search: GET /api/v1/search?q={query}&locale=en-US.

Article Page (/docs/Web/API/{name})

Standard section IDs on reference pages (these have not changed in the redesign):

Search Results (/en-US/search?q={query})

Note: The search results page is JavaScript-rendered. Use the JSON API instead.

Navigation Flows

Flow: Search via JSON API [API] (Recommended)

Starting point: None — direct HTTP fetch Prerequisites: None

Success state: JSON with documents[], metadata, suggestions.

Branching:

• If metadata.total.value === 0 → check suggestions[] and retry with suggested term
• If you know the API name → skip search, navigate directly: https://developer.mozilla.org/en-US/docs/Web/API/{APIName}

Flow: Navigate to an Article [Browser]

Starting point: Any page or direct URL Prerequisites: None

Success state: Article page with div.layout__body visible. ol.breadcrumbs a confirms the correct page (last link = API name).

Flow: Browse Article Sections [Browser]

Starting point: Any MDN article page Prerequisites: Must be on article page

Navigate to a specific section by anchor (fastest):

Or click a ToC entry:

Success state: Page scrolled to section; target h2[id] or h3[id] is visible in viewport.

Flow: Navigate Between Related APIs [Browser]

Starting point: Any MDN article page Prerequisites: None

Or go up via breadcrumb:

API Response Shapes

GET /api/v1/search?q={query}&locale=en-US&limit=10

{
  "documents": [
    {
      "mdn_url": "/en-US/docs/Web/API/Fetch_API",
      "score": 179.04,
      "title": "Fetch API",
      "locale": "en-US",
      "slug": "Web/API/Fetch_API",
      "popularity": 0.967,
      "summary": "The Fetch API provides an interface for fetching resources (including across the network).",
      "highlight": {
        "body": ["The <mark>Fetch</mark> API provides an interface..."],
        "title": ["<mark>Fetch</mark> API"]
      }
    }
  ],
  "metadata": {
    "took_ms": 18,
    "total": {
      "value": 1482,
      "relation": "eq"
    },
    "size": 10,
    "page": 1
  },
  "suggestions": []
}

Key fields:

Pagination: Add &page=2 to get next page of results.

Common Agent Tasks

"What does {API} do?"

1. Fetch: GET /api/v1/search?q={API}&locale=en-US&limit=5
2. Read documents[0].summary — this is the one-paragraph description
3. If more detail needed: navigate browser to https://developer.mozilla.org + documents[0].mdn_url
4. Read div.layout__body content up to the first h2 — this is the intro paragraph

Output: Summary + link to full article

"What are the parameters of {method}?"

1. If you know the API: navigate directly to https://developer.mozilla.org/en-US/docs/Web/API/{APIName}/{method}
2. If not: search GET /api/v1/search?q={method}&locale=en-US&limit=5 → pick best match
3. Navigate browser to the article page (append #parameters to URL)
4. Read section.content-section following the #parameters heading

Output: Parameter names, types, descriptions

"Is {feature} supported in all major browsers?"

1. Navigate browser to the relevant MDN article, append #browser_compatibility
2. Wait 2s for the JS-rendered compat table to load
3. Read the table — look for red/partial cells in Chrome, Firefox, Safari, Edge columns

Alternative (programmatic, no browser): Use the @mdn/browser-compat-data npm package:

const bcd = require('@mdn/browser-compat-data');
console.log(bcd.api.fetch.__compat.support);

Returns structured compat data without a browser request.

Dynamic Content Patterns

• Server-rendered MPA: Article pages are fully server-rendered HTML. Use domcontentloaded — no JS wait needed for content text.
• Search results page is JS-rendered: The /search page loads article cards via JavaScript. Do NOT use it for automation — use the JSON API at /api/v1/search instead.
• Homepage has no static search input: The search UI is JS-triggered. No <input> exists in the static HTML on any page at load time.
• Browser compatibility table is JS-rendered: The #browser_compatibility section shows a loading state until JS runs. Section anchor is always present; table data is not.
• BEM-style class names, but not immutable: MDN uses intentional BEM class names (not hashed), but has undergone at least one major redesign. Classes like nav.reference-toc, ol.breadcrumbs, div.layout__body are stable within the current design but may change on major rebuilds.
• No CAPTCHA: MDN has no bot protection on article pages or the search API.

Timing & Waiting

Rate Limits

Parallel requests: Safe to fire multiple search or article requests in parallel — MDN is CDN-backed.

robots.txt note: /api/ is listed as Disallow for some crawlers, but the public search API at /api/v1/search is intended for programmatic use. Agent usage (not bulk scraping) is fine.

Common Gotchas

1. Search results page is JavaScript-rendered. The /search page doesn't have a visible input in static HTML — it renders via JS. For any automated search, call the JSON API: GET https://developer.mozilla.org/api/v1/search?q={query}&locale=en-US&limit=10
2. Direct article URLs are always best for known APIs. If you know the API name, go straight to the URL: https://developer.mozilla.org/en-US/docs/Web/API/{APIName}. The URL pattern is very predictable: spaces → underscores, method separator → /.
3. mdn_url from the API needs a base URL prepended. The API returns paths like /en-US/docs/Web/API/Fetch_API. Prepend https://developer.mozilla.org to get the full URL.
4. Browser compat table requires JS to render. The #browser_compatibility section shows a "Loading..." state until JS runs. Use @mdn/browser-compat-data for programmatic access.
5. Section IDs use underscores. MDN section anchors are #browser_compatibility, #return_value, #see_also (underscores, lowercase). Not camelCase or hyphens.
6. No static search input on any page. Unlike PyPI or crates.io, MDN has no <input type="search"> in static HTML anywhere. All search is JS-triggered. Use the API.
7. Multiple method pages for one API. An API like Fetch_API has sub-pages: /Fetch_API/fetch, /Fetch_API/Headers, /Fetch_API/Request, /Fetch_API/Response. The parent page lists them; navigate to the method page for parameter/return details.
8. Left sidebar vs right sidebar. nav.left-sidebar = related pages in this API (sibling/child articles). nav.reference-toc = on-page section anchors (ToC for the current article). Don't confuse them.

Anti-Patterns

• NEVER use pre-2025 MDN selectors — .document-toc, article.main-page-content, [aria-label*="breadcrumb"] no longer exist. The page was redesigned. Use nav.reference-toc, div.layout__body, ol.breadcrumbs instead.
• NEVER look for a search input in the HTML — no <input> exists in static HTML on any MDN page. Use GET /api/v1/search?q={query} instead.
• NEVER use mdn_url as a full URL — the API returns relative paths (/en-US/docs/...). Always prepend https://developer.mozilla.org.
• NEVER wait for the browser compat table if you just need data — it's JS-rendered and slow. Use @mdn/browser-compat-data npm package for programmatic access.
• NEVER use aside a — aside in the current DOM wraps the right sidebar ToC, returning 18+ links including unrelated nav. Use nav.reference-toc a for ToC links and nav.left-sidebar a for related-pages links.

Freshness