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
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:
- 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:
- Use this base URL to get a standard MDN search results page as output.
- Use this base URL to get the results in JSON format. See JSON response body 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:
- The search query to match. This is the same parameter used for basic search.
- 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-USto limit a search to English pages.
- The CSS classes to match. This limits the search results to pages whose HTML includes at least one use of the specified classes.
- 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.
- 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.
- Must be either
false; defaults to
true. Determines whether the excerpt shows the page's first section or portions of the page that contain the query. If true, there will also be
<mark>elements around result phrases that match the search query.
- Must be a number <=100. By default Kuma displays 10 results per page. Use this parameter to choose a different value.
Here are some sample searches.
Searching by locale
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
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
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
/ in your search, you'll need to URL-encode them. For example, to find pages that link to www.mozilla.org, you would do:
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
This searches for uses of the macro
TemplateLink. This lets us find macros whose parameters have changed, or that we wish to stop using.
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:
- The total number of results found.
- A URL that will return the next page of results (or
nullon the last page).
- A URL that will return the previous page of results (or
null, for the first page).
- The search query that was used to find the results.
- The page number of the results that are described by this object.
- The total number of pages in the results.
- The item number of the first item in this page of results.
- The item number of the last item in this page of results.
- An array of the configurations of the various search filters. These are the filters available to the standard search.
- An array of Page objects describing each matching page.
Each page object contains the following fields:
- The article's title.
- The article's slug. This is everything in the URL of the page following the locale and the subsequent slash character.
- The page's locale.
- 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=falsein the search query parameters.
- The full URL for the page.
- The full URL to get into edit mode for the page.
- An array of the page's tags.
- A scoring value assigned by the search engine.
- 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.
There are some additional admin-only search functions for things like finding pages whose slugs start with a specific string, for example.