Use when looking up Web APIs, CSS properties, HTML elements, or JavaScript docs on MDN. Provides search API and navigation flows for developer.mozilla.org.

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	URL Pattern	Notes
Homepage	`https://developer.mozilla.org/en-US/`	No static search input — use API
Search results	`https://developer.mozilla.org/en-US/search?q={query}`	JS-rendered — use API instead
API Reference root	`https://developer.mozilla.org/en-US/docs/Web/API`	Index of all Web APIs
Specific API	`https://developer.mozilla.org/en-US/docs/Web/API/{APIName}`	Main reference page
Method / property	`https://developer.mozilla.org/en-US/docs/Web/API/{APIName}/{method}`	e.g. `/Fetch_API/fetch`
JavaScript reference	`https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference`	JS built-ins
JS global object	`https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Name}`	e.g. `Promise`, `Array`
HTML elements	`https://developer.mozilla.org/en-US/docs/Web/HTML/Element/{tag}`	e.g. `/Element/input`
CSS properties	`https://developer.mozilla.org/en-US/docs/Web/CSS/{property}`	e.g. `/CSS/grid-template-columns`
JSON Search API	`https://developer.mozilla.org/api/v1/search?q={query}&locale=en-US`	Structured results, no browser needed

Page Structures

Homepage

Element	Selector	Notes
Navigation toggle	`button.navigation__button`	Opens full nav panel
Top-level topic tabs	`button.menu__tab-button`	HTML, CSS, JavaScript, Web APIs, All, Learn, Tools, About

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}`)

Element	Selector	Notes
Breadcrumb links	`ol.breadcrumbs a`	e.g. Web → Web APIs → Fetch API (3 links)
Right sidebar ToC	`nav.reference-toc a`	Links to `#section-id` anchors on this page
Left sidebar related links	`nav.left-sidebar a`	Sibling/child pages for this API
Main content area	`div.layout__body`	Wraps all article content sections
Content sections	`section.content-section`	Each major section is wrapped in this
Section headings	`h2[id]`, `h3[id]`	`id` is the anchor (e.g. `id="browser_compatibility"`)
Navigation toggle	`button.navigation__button`	Opens sidebar nav on all viewports
Topic tab buttons	`button.menu__tab-button`	HTML, CSS, JavaScript, Web APIs, All, Learn, Tools, About

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

Section	`id` value	Present on
Syntax	`#syntax`	Methods, properties
Parameters	`#parameters`	Methods
Return value	`#return_value`	Methods
Exceptions	`#exceptions`	Methods
Examples	`#examples`	Most pages
Browser compatibility	`#browser_compatibility`	All reference pages
Specifications	`#specifications`	All reference pages
See also	`#see_also`	Most pages

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

Step	Action	Target	Notes
1	fetch	`https://developer.mozilla.org/api/v1/search?q={query}&locale=en-US&limit=10`	No auth, no CAPTCHA
2	read	`documents[].title`, `documents[].mdn_url`, `documents[].summary`	Core result fields
3	build URL	`https://developer.mozilla.org` + `documents[0].mdn_url`	Full article URL

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

Step	Action	Target	Value	Wait For	Timeout
1	navigate	—	`https://developer.mozilla.org/en-US/docs/Web/API/{name}`	`div.layout__body` visible	5s
2	read	`div.layout__body`, `ol.breadcrumbs a`	—	Content loaded	—

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):

Step	Action	Notes
1	navigate	Append `#section-id` to article URL, e.g. `.../Fetch_API#browser_compatibility`

Or click a ToC entry:

Step	Action	Target	Wait For	Timeout
1	click	`nav.reference-toc a[href="#browser_compatibility"]`	Section scrolled into view	1s

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

Step	Action	Target	Wait For	Timeout
1	read	`nav.left-sidebar a`	Sidebar links visible	—
2	click	target `nav.left-sidebar a[href*="/docs/"]`	New article loads	3s

Or go up via breadcrumb:

Step	Action	Target	Wait For	Timeout
1	click	`ol.breadcrumbs a` (second-to-last = parent)	Parent page loads	3s

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:

Field	Description
`documents[].mdn_url`	Path — prepend `https://developer.mozilla.org` for full URL
`documents[].slug`	Article slug — matches the URL path after `/en-US/docs/`
`documents[].summary`	One-paragraph plain-text description
`documents[].popularity`	0.0–1.0 — higher = more-visited page
`documents[].highlight.body[]`	Matched sentences with `<mark>` tags around search term
`metadata.total.value`	Total matching documents (may be >10 if paginated)
`suggestions[]`	Alternative search queries if results are sparse

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

Common Agent Tasks

"What does {API} do?"

Fetch: GET /api/v1/search?q={API}&locale=en-US&limit=5
Read documents[0].summary — this is the one-paragraph description
If more detail needed: navigate browser to https://developer.mozilla.org + documents[0].mdn_url
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}?"

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

Output: Parameter names, types, descriptions

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

Navigate browser to the relevant MDN article, append #browser_compatibility
Wait 2s for the JS-rendered compat table to load
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

Transition	Wait For	Typical Delay
Article page navigation	`domcontentloaded`	0.5–2s
In-page anchor navigation	No wait — instant scroll	<100ms
Sidebar link click	`domcontentloaded`	0.5–2s
JSON API fetch	Response body	0.2–1s
Browser compat table	JS render after domcontentloaded	0.5–2s

Rate Limits

Scope	Limit	Notes
JSON Search API	No documented limit	CDN-backed; very permissive
Article pages	No documented limit	Standard web crawling is fine

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

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
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 → /.
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.
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.
Section IDs use underscores. MDN section anchors are #browser_compatibility, #return_value, #see_also (underscores, lowercase). Not camelCase or hyphens.
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.
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.
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


Skill verified	2026-02-20
API stable since	2020 — `/api/v1/search` has been stable; no breaking changes observed
Selector stability	MEDIUM — MDN uses intentional BEM class names (not hashed), but underwent a significant redesign in 2025. Section ID anchors (`#browser_compatibility` etc.) are stable.
Breaking change risk	Low for API and section anchors, Medium for CSS class selectors

mdn-web-docs