MDN の検索機能

MDN のオンサイト検索機能では、外部の検索エンジンで MDN の記事を検索した時には得られない多くの機能が提供されます。この記事では MDN の検索エンジンを最大限に活用する方法を記します。

MDN で検索クエリの結果を表示する際に、トピック、技術レベル、文書タイプで結果をフィルタリングするオプションがあります。これは、関連するキーワードが複数の文脈で表示される可能性のあるメソッドを探している場合などに便利です。トピックフィルターを使用して、最も興味のある API の結果のみを表示することができます。これらのフィルターは、ページに設定されたタグによって、どのページを含めるか除外するかを決定します (ページを作成または編集する際に適切にタグ付けするのはこれが理由です)。以下の種類のフィルターを適用することができます。

トピック: トピックのタグに従って検索結果を絞り込む
技術レベル: Beginner, Intermediate, Advanced の各タグで絞り込む
文書タイプ: Example, Guide, Tools の各タグで絞り込む

高度な検索オプション

MDN 貢献者向けに特定のマクロや HTML 属性などを検索できるよう、マクロの出力ではなく生の HTML でページのソースを検索できる高度な検索機能を用意しています。

今のところこの高度な検索用のユーザーインターフェイスは用意しておらず、URL で直接アクセスすることで利用できます。検索結果は通常の MDN の検索結果ページあるいは JSON フォーマットのいずれかで得られます (後者の検索結果は例えば KumaScript などから使うこともできます)。この節ではその使い方を説明します。

注: ここで紹介する検索クエリーは広く利用される目的で作る URL ではありません。ツールやユーティリティから使用するためのものであり、将来変更される可能性があります。クエリーのパフォーマンスも高くない場合があります。

検索クエリーの書式

高度な検索クエリーは検索に適切な引数を付けた URL で実行してください。ベースとなる URL は次のいずれかです。

https://developer.mozilla.org/ja/search: 通常の MDN 検索結果ページを出力とする場合はこちらを使います。
https://developer.mozilla.org/ja/search.json: JSON 形式で結果を取得する場合はこちらを使います。検索結果の書式については JSON response body format をご覧ください。

これに続けて、欲しい結果を得るには適切なパラメータを追加してください。次のパラメータを組み合わせて利用できます:

q=: マッチする検索クエリー。これは基本検索で使われるパラメーターと同じです。
locale=: 検索対象とするロケール。既定ではすべてのロケールが対象となります。すべてのロケールを明示的に指定するにはワイルドカード "*" を指定することもできます。例えば、 locale=ja とすれば検索結果を日本語だけに絞り込めます。
css_classnames=: 検索対象とする CSS クラス名。ページの HTML に少なくとも指定されたクラスが 1 つ以上含まれているページを検索します。
html_attributes=: 検索対象とする HTML 属性テキスト。これは前方一致検索です。つまり、指定したテキストが HTML の属性文字列の始めにある場合、検索にマッチします。詳しくは下記をご覧ください。
kumascript_macros=: 検索対象とする 1 つ以上の KumaScript のリスト。これをつかって特定のマクロを使った記事を検索できます。例えば、マクロを廃止する場合や、パラメータが変更され既存のページを更新する必要がある場合に便利です。
highlight=: true か false のどちらかで、既定では true です。検索クエリーにマッチする結果の周りに <mark> 要素を含めるかどうかを決めます。
per_page=: 100以下の数値です。既定では Kuma はページ当たり10個の結果を出力します。それとは異なる値を使用する場合にこの引数を使用してください。

例

検索例をいくつか示します。

ロケールによる検索

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

この例では日本語の記事のリストが得られます。言語 (ロケール) 以外での絞り込みはされません。このページの翻訳時点では 12092 ページが見つかります (もちろん翻訳ページは増え続けているのであなたが試すときにはもっと大きな数になっているはずです！)

CSS クラス名による検索

https://developer.mozilla.org/ja/search?locale=ja&css_classnames=smaller

この例では CSS で smaller クラスを使っている記事のリストが得られます。ページ翻訳時点では 42 ページに絞り込まれます。

HTML 属性文字列による検索

https://developer.mozilla.org/ja/search?locale=ja&html_attributes=style

この例では HTML 要素に style 属性が使われている記事のリストが得られます。ページ翻訳時点では 7277 ページが該当します。これらはダメなページで修正されるべきものです。少しずつ標準化したクラスで置き換えていく必要があります。

属性値も含めて検索することはできますが、検索文字列に = や / を含める場合にはこれらを URL エンコードする必要があることに注意してください。例えば、www.mozilla.org にリンクしているページは次のように検索します:

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

この検索結果は 80 件になりました。www.mozilla.org にリンクしているページは意外と少ないですね！

KumaScript マクロの使用状況による検索

https://developer.mozilla.org/ja/search?locale=ja&kumascript_macros=TemplateLink

この例では TemplateLink マクロを使用しているページを検索します。マクロの引数が変更された時や、マクロの使用をやめたいときに検索することができます。

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" クラスが使われていればそのクラスで指定されたコンテンツ。検索クエリ引数内で highlight=false を指定しない限り、excerpt には <mark> 要素が入ります。
url: ページの完全な URL
edit_url: ページを編集モードで開く完全な URL
tags: ページのタグの配列
score: 検索エンジンで割り当てられたスコア値
explanation: 検索クエリーにどのように何故マッチしたかという検索エンジンからの雑多な情報。このコンテンツの詳細についてはこのページでは解説しません。