Использование продвинутого поиска

В качестве дополнительной возможности внесения для вкладчиков в MDN у нас есть продвинутый механизм поиска, который позволяется вам искать по исходному коду страницы — то есть, по сырому HTML сайта, с макросами вместо их вывода — что позволяет искать использования определённых макросов, атрибутов HTML и тому подобное.

На текущий момент для использования продвинутого механизма поиска нет пользовательского интерфейса, но вы можете получить к нему доступ посредством специально сформированных URL. Вы можете получить вывод либо на стандартную страницу с результатами поиска по MDN, либо в формате JSON (последнее означает, что вы можете использовать этот механизм, например, из кода на KumaScript). Эта статья описывает, как всем этим пользоваться.

Примечание: эти поисковые запросы не предназначены для конструирования распространяемых URL; а предназначены для использования во вспомогательных инструментах и утилитах. В будущем они могут измениться, также не обязательно, что эти запросы самые эффективные.

Формат поискового запроса

Продвинутые поисковые запросы позволяются конструировать URL с соответствующими параметрами. Базовый URL может быть одним из следующих:

https://developer.mozilla.org/en-US/search: Используйте этот базовый URL для получения стандартной страницы с результатами поиска по MDN.
https://developer.mozilla.org/en-US/search.json: Используйте этот базовый URL для получения результатов в формате JSON. О формате результата смотрите раздел формат JSON для результата.

Кроме того, вам нужно добавить соответствующие параметры для получения желаемого результата. Вы можете использовать любую комбинацию следующих параметров:

locale=: Рассматриваемая локаль. По умолчанию рассматриваются все локали. Также вы можете явно указать «все локали» при помощи шаблона "*". Например, вы можете определить locale=en-US для ограничения поиска только по англоязычным страницам.
css_classnames=: Классы CSS для сопоставления. Этот параметр ограничивает результат поиска страницами, чей HTML-код включает в сеся как минимум одно использование указанных классов.
html_attributes=: Текст атрибутов HTML для сопоставления. Поиск ведётся по началу текста; то есть, если указаный текст появляется в начале строки атрибута HTML, он будет считаться совпавшим. Подробности смотрите ниже.
kumascript_macros=: Список искомых макросов KumaScript. Этот параметр позволяет вам находить статьи, использующие определённый макрос; это может быть полезно в тех случаях, если, к примеру, макрос устарел или его параметры поменялись и вам нужно обновить существующие варианты его использования.

Примеры

Здесь приведено несколько примеров поисковых запросов.

Поиск по локали

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

В этом примере возвращается список всех англоязычных статей без каких-либо иных ограничений. На момент написания этой статьи их было 12865 (к тому времени, как вы прочитаете эту статью, их, конечно же, станет больше, поскольку мы постоянно растём)!

Поиск по имени CSS-класса

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

В этом примере мы добавили к поисковому условию использование CSS-класса "smaller"; на момент написания этой статьи количество результатов снизилось всего до 6 страниц.

Поиск по строке атрибута HTML

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

Здесь мы ищем использования атрибута "style" на элементах HTML. На момент написания этой статьи мы нашли 4935 таких страниц. Это плохо и это нужно искоренять; мы собираемся заменить все такие вхождения на наши стандартные классы.

Также вы можете включать в поисковый запрос значение атрибута, но помните, что если вы захотите включить символы вроде "=" или "/" в ваш поисковый запрос, вы должны их закодировать для использования в URL. Например, чтобы найти страницы, ссылающиеся на www.mozilla.org, вы можете сделать так:

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

Этот поиск вернул 29 результатов. Это удивительно малое количество ссылок на сайт www.mozilla.org!

Поиск по используемому макросу KumaScript

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

Этот поисковый запрос ищет использования макроса unimplemented_header. На момент написания этой статьи было найдено шесть страниц. Он позволяет нам искать макросы, чьи параметры были изменены, либо те, которые мы хотим прекратить использовать (последний случай как раз относится к рассматриваемому макросу).

Формат JSON для результата

Когда вы запрашиваете результат в формате JSON, вы по прежнему получаете результаты по одной странице за раз. Каждая страница является объектом KumaScript, который состоит из нескольких частей с метаданными о результатах, плюс массив стандартных объектов страницы с одним дополнительным полем: URL-адресом для начала редактирования страницы.

В результирующем объекте содержатся следующие данные:

count: Общее количество найденных результатов.
next: URL, по которому можно перейти на следующую страницу с результатами (либо null для последней страницы).
previous: URL, по которому можно перейти на предыдущую страницу с результатами (либо null для первой страницы).
query: ???
page: Номер страницы с результатами, описываемой этим объектом.
pages: Общее количество страниц с результатами.
start: Номер первого элемента на этой странице с результатами.
end: Номер последнего элемента на этой странице с результатами.
filters: Массив конфигураций расличных поисковых фильтров. Эти фильтры доступны в стандартном поиске.
documents: Массив объектов страницы, описывающих каждую совпавшую страницу.

Объекты страницы

Каждый объект страницы содержит следующие поля:

title: Заголовок статьи.
slug: Идентификатор статьи. Это вся часть URL страницы, следующая за локалью и последующим символом слеша.
locale: Локаль страницы.
excerpt: Фрагмент содержания страницы; это либо первый блок обычного текста статьи, либо содержимое, отмеченное классом "SEO Summary".
url: Полный URL страницы.
edit_url: Полный URL страницы в режиме редактирования.
tags: Массив меток страницы.
score: Значение очков, присвоенное странице поисковым движком.
explanation: Различная информация от поискового движка о том, почему страница соответствует вашему запросу. Описание этого содержимого выходит за рамки данного документа.