As an added feature for contributors to MDN, we have 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 article 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 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:
- 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.
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 12865 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 just 6 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 4935 of them. These are evil and have to go; 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 29 results. That's a surprisingly low number of links to the www.mozilla.org site!
Searching for KumaScript macro usage
This searches for uses of the macro
unimplemented_header. Six 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 result 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 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 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.