Search on MDN - The MDN project 编辑

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:

/wiki/en-US/search

Use this base URL to get a standard MDN search results page as output.

/wiki/en-US/search.json

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:

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 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.

per_page=

Must be a number <=100. By default Kuma displays 10 results per page. Use this parameter to choose a different value.

Examples

Here are some sample searches.

Searching by locale

/wiki/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

/wiki/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

/wiki/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:

/wiki/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

/wiki/en-US/search?locale=en-US&kumascript_macros=TemplateLink

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:

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.

See also

There are some additional admin-only search functions for things like finding pages whose slugs start with a specific string, for example.