Search on MDN

The on-site search feature of MDN offers a number of features that may not be available when using an external search engine to search for MDN articles. This article describes how to leverage MDN's search engine.

Basic search options

Filtering results

When viewing the results of a search query on MDN, you have the option of filtering the results by topic, skill level, and document type. This can be useful, for example, when you are looking for a method where the relevant keywords might appear in multiple contexts; you can use the topic filter to view only results in the API you are most interested in. These filters rely on the tags on pages to determine which pages to include or exclude (which is the reason for properly tagging pages when creating or editing them). You can apply the following types of filters:

Topics: Filter the results according to topic tags
Skill level: Filter based on Beginner, Intermediate or Advanced tags.
Document type: Filter the results based on tags Example, Guide, or Tools.

Advanced search options

MDN has an advanced search mechanism that lets you search the page source — that is, the raw HTML of the site, with macros in place rather than their output — in order to find uses of specific macros, use of given HTML attributes, and the like.

There is not currently a user interface for this advanced search mechanism, but you can access it by URL. You can get the output either as a standard MDN search results page or in JSON format (the latter means you can use this mechanism from KumaScript code, for example). This section covers how to use it.

Note: These search queries are not intended for the construction of URLs to be distributed; they're for use by tools and utilities. They could change in the future, and are not necessarily high-performance queries.

Search query format

Advanced search queries are performed by constructing URLs with the appropriate parameters. The base URL is one of the following:

https://developer.mozilla.org/en-US/search: Use this base URL to get a standard MDN search results page as output.
https://developer.mozilla.org/en-US/search.json: Use this base URL to get the results in JSON format. See JSON result format for information about the result format.

In addition, you need to add the appropriate parameters to get the results you want. You may use any combination of these:

q=: The search query to match. This is the same parameter used for basic search.
locale=: The locale to match against. By default, all locales are considered. You may also specify "all locales" with the wildcard "*". For example, you can specify locale=en-US to limit a search to English pages.
css_classnames=: The CSS classes to match. This limits the search results to pages whose HTML includes at least one use of the specified classes.
html_attributes=: The HTML attribute text to match. This is a leading text search; that is, if the specified text appears at the beginning of an attribute string in the HTML, it's considered a match. See below for details.
kumascript_macros=: A list of one or more KumaScript macros to search for. This lets you find articles using a specific macro; this would be useful, for instance, if a macro is obsolete, or if its parameters have changed and you need to update existing uses.
highlight=: Must be either true or false; defaults to true. Determines whether or not to include <mark> elements around result phrases that match the search query.

Examples

Here are some sample searches.

Searching by locale

https://developer.mozilla.org/en-US/search?locale=en-US

This example returns a list of all articles that are in English, with no other restrictions. At the time of writing, this results in 13513 pages (that'll be higher by the time you see this, of course, since we're constantly growing)!

Searching by CSS class name

https://developer.mozilla.org/en-US/search?locale=en-US&css_classnames=smaller

In this example, we add a search for uses of the CSS class "smaller"; at the time of writing, this narrowed the results down to 35 pages.

Searching by HTML attribute string

https://developer.mozilla.org/en-US/search?locale=en-US&html_attributes=style

Now we're looking for uses of the "style" attribute on HTML elements. At the time of writing, we found 6416 of them. This usage is deprecated on MDN; we are going to be replacing them all with uses of our standard classes instead.

You can also include the value of the attribute, but keep in mind that if you wish to include characters like "=" and "/" in your search, you'll need to URL-encode them. For example, to find pages that link to www.mozilla.org, you would do:

https://developer.mozilla.org/en-US/search?locale=en-US&html_attributes=href%3D%22https%3A%2F%2Fwww.mozilla.org

This search results in 98 results. That's a relatively low number of links to the www.mozilla.org site!

Searching for KumaScript macro usage

https://developer.mozilla.org/en-US/search?locale=en-US&kumascript_macros=unimplemented_header

This searches for uses of the macro unimplemented_header. Two are found at the time this page was written. This lets us find macros whose parameters have changed, or that we wish to stop using (the latter is the case for this particular macro).

JSON response body format

When you request the results in JSON format, you still receive the results one page at a time. Each page is a KumaScript object which consists of several pieces of metadata about the results, plus an array of standard page objects with the addition of one extra field: the URL to begin editing the page.

The data contained in the resulting object is:

count: The total number of results found.
next: A URL that will return the next page of results (or null on the last page).
previous: A URL that will return the previous page of results (or null, for the first page).
query: The search query that was used to find the results.
page: The page number of the results that are described by this object.
pages: The total number of pages in the results.
start: The item number of the first item in this page of results.
end: The item number of the last item in this page of results.
filters: An array of the configurations of the various search filters. These are the filters available to the standard search.
documents: An array of Page objects describing each matching page.

Page objects

Each page object contains the following fields:

title: The article's title.
slug: The article's slug. This is everything in the URL of the page following the locale and the subsequent slash character.
locale: The page's locale.
excerpt: A snippet of the page's content; this is either the first block of regular text in the article or, if available, the content marked with the "SEO Summary" class. The excerpt will contain <mark> elements unless you specify highlight=false in the search query parameters.
url: The full URL for the page.
edit_url: The full URL to get into edit mode for the page.
tags: An array of the page's tags.
score: A scoring value assigned by the search engine.
explanation: Assorted information from the search engine about how and why the page matched your query. The description of this content is beyond the scope of this document.