ページの種類

MDN には繰り返し使用されるいくつかの種類のページがあります。 この記事では、これらのページの種類とその目的、および新しいページを作成するときに使用するそれぞれのテンプレートの例と使用方法について説明します。

MDN には大きく分けて 3 種類のページがありますが、いくつかの種類のページは複数のカテゴリーに分類されます。

  • リファレンスページは何かの詳細を記述し、記述されているものの構造に従って編成されています
  • ガイドページには、何かを行う方法や使う方法が書かれており、読者の目標に基づいて編成されています
  • ナビゲーションページは、主に関連するトピックに関する他のページへのリンクを提供するために存在します

新しいページの作成

MDN に新しいページを作成するには、 GitHub を使用する必要があります。詳しくは content リポジトリーの新しい文書を追加するの節を見てください。

テンプレートの使い方

新しいページを作成する際、ページテンプレートを参照することで、正しいページ構成やコンテンツを使用したことを確認することができます。 （コピーしたい場合は）各テンプレートの下にある "Source on GitHub" リンクをたどると、正確なソースコードを見つけることができます。 これらのページテンプレートは、公開されたページとしてはあまり意味を持ちませんが、ソースコードを見ると、多くの有用なコメント、プレースホルダー、不足する情報を埋めてページを作成する方法の詳細なヒントが含まれていることがわかります。

各テンプレートの上部には、Remove before publishing というセクションがあります。ここには、ページのタイトル、スラッグ、サイドバーメニュー、タグ（例えば、実際には記事の本文に表示されない情報）を記入する方法についての情報が記載されています。 このセクションの指示に従った後、ページが完成したとみなされる前に、このセクションを削除する必要があります。

古い様式のページレイアウト

時々、ここで紹介するテンプレートとは明らかに異なる古い様式のリファレンスページを見かけることがあります。 例えば、古い様式のインターフェイスページでは、インターフェイスの全てのメンバーの詳細が 1 つのページ上にあり、個々のメソッド/プロパティ/コンストラクター/イベントリスナーページは存在しませんでした。

もし、古い様式のページを見つけたら、ぜひ新しい様式に更新してください。 しかし、これは大変な作業となる可能性があることを承知しています。 更新する情報がそれほど多くなく、お時間があるようでしたら、ぜひ新しい様式に更新してみてください。

もし作業量が多い場合は、いくつかの要素を考慮して作業の優先順位を決めるとよいでしょう。

  • どの程度古い情報なのか？
  • その情報はどの程度古いか、どの程度品質が低いか
  • その特集はどの程度人気があるか？その情報はどの程度求められているか？

もし、チームを結成して更新作業を行いたい場合、または単に更新が必要なコンテンツを報告または議論したい場合は、お気軽にコンテンツの問題を報告または助けを求めるまでお問い合わせください。

フロントマターの page-type キー

MDN ページの種類を明確に識別するために、フロントマターキー page-type を定義しました。下記リンクのテンプレートは、各ページ種類にどの page-type 値を設定すべきかを示しています。

ページ種類の完全なリストは、フロントマターの page-type キーを参照してください。

ページテンプレート

下記は MDN で見られる様々なページの例と、表示するコンテンツの種類に応じて新しいコンテンツを作成する際に使用することができるテンプレートです。

それぞれの節には、そのページ種類のライブサンプルページへのリンクが記載されています。

API ランディングページ

API ランディングページでは、特定の API が行うことの概要と、その API が提供する各インターフェイス、グローバル、関数などのドキュメントへのリンクが提供されます。 概要テキストのコンテキストを除いて、 API のクラス内の特定のメソッドやプロパティに直接リンクすることはありません。 このページは主にナビゲーションページですが、 API の一目でわかるリファレンスページとしても機能します。

複数の API が存在し、それぞれ独自の仕様で定義されていますが、それらは密接に関連しているため、 1 つの API ランディングページでカバーすることが理にかなっている場合があります。 例えば、 Generic Sensor API は一般的なセンサーに関する事項をカバーしていますが、より具体的な事項は Ambient Light Sensor や Motion Sensor など、他の API でカバーされています。 このような場合、高レベルの概念の多くが同じであるため、複数のランディングページにわたってそれらを繰り返すことは意味がありません。 そのような場合は、 1 つの「ウェブセンサー」ランディングページですべてをカバーする方が、繰り返しの意味でも見つけやすさの意味でも理にかなっています。

例

テンプレート

API リファレンスページ

メモ: インターフェイスランディングページとも呼ばれます。

API リファレンスページは、特定のインターフェイスやクラスのメンバーであるすべてのメソッド、プロパティ、イベントなどを列挙します。 クラスまたはインターフェイスが何を行うか、または何のために使用されるかの概要を提供し、これらの各メンバーのドキュメントへのリンクを提供します。 通常、複数の API リファレンスページにリンクしている API ランディングページよりも、より詳細な情報を提供します。

例

テンプレート

API リファレンスサブページ

API リファレンスサブページは、 API リファレンスページの子ページです。 これは、インターフェイスの単一のメンバーを詳細に記述します。

例

テンプレート

HTML 要素リファレンスページ

HTML リファレンスページは、 HTML 要素で利用可能なすべての属性を列挙し、要素の目的や使用方法を説明し、例やブラウザーの互換性情報、その他の重要なデータを提供します。

例

テンプレート

SVG 要素リファレンスページ

SVG リファレンスページは、 SVG 要素で利用可能なすべての属性の一覧、要素の目的および使用法の説明、例、ブラウザーの互換性情報、その他の重要なデータを提供するものです。

例

テンプレート

CSS モジュールランディングページ

それぞれの CSS モジュールは、CSS の特定の機能や実装に対応する CSS 仕様書を表します。例えば、 CSS ボックスモデルモジュールは、CSS のボックスの中や周りに空間を作成するための margin および padding プロパティを記述する仕様書を表します。

CSS モジュールランディングページは、モジュールが提供する機能の概要を提供し、モジュールが提供するすべてのプロパティ、データ型、CSS 関数などを一覧表示します。可能な場合、 CSS モジュールのランディングページでは、モジュールのプロパティを使用することで、どのようなことが実現できるかを対話式の例で簡単に示すことができます。モジュールランディングページは主にナビゲーションページとして機能しますが、モジュールの一目でわかるリファレンスページとしても機能します。

他のモジュール内のプロパティや機能であっても、文書化するモジュールが提供する機能と密接に関連しているものについては、「関連概念」の節で扱うことができます。 例えば、 <easing-function> データ型と prefers-reduced-motion メディアクエリーは CSS アニメーションモジュールでは扱われていませんが、CSS アニメーションと密接に関連しているため、CSS アニメーションモジュールのランディングページの関連概念の節で強調するとよいでしょう。

例

テンプレート

CSS 機能リファレンスページ

CSS リファレンスページは、セレクターやプロパティなどの CSS 機能について、利用可能なすべての構文を列挙し、その目的や使い方を説明するものです。また、例やブラウザーの互換性などの重要なデータも提供します。

例

テンプレート

HTTP ヘッダーリファレンスページ

HTTP ヘッダーのリファレンスページは、 HTTP ヘッダーが含むことのできるすべてのディレクティブを列挙し、ヘッダーの目的と使用法を説明します。 また、例やブラウザーの互換性、その他の重要な説明も含まれています。

例

テンプレート

概念ページ

概念ページは、何かを説明したり教えたりするガイドページです。 一般に、あるページが主に散文で書かれており、他のページ種別に分類されない場合、それはおそらく概念ページです。 あるトピックに関する幅広い議論は、複数の概念ページにまたがり、 Next と Previous マクロを使用してリンクされるかもしれません。

例

用語集ページ

用語集ページは、用語、トピック、概念の簡単な説明を含んでいます。 最初の段落は、その用語の簡単で自己完結した説明であるべきで、 2 文以下でなければなりません。 その後に、さらに詳しい情報へのリンクを 関連情報 セクションに記述することができます。 ページが画面いっぱいになるほど大きくなる場合は、長すぎるので、概念ページに変換する必要があります。詳しくは、用語集の項目の書き方と参照方法を参照してください。

例

テンプレート

ランディングページ

ランディングページは、サブページのメニューのような役割を果たすため、主にナビゲーションページと呼ばれます。 ランディングページのレイアウトは、通常、特定のトピックに関するページのツリーのルートページに使用されます。 トピックの簡単な要約で始まり、サブページへのリンクの構造化されたリストが表示され、オプションとして読者に役立つ追加資料が表示されます。

サブページのリストは、テンプレート SubpagesWithSummaries, LandingPageListSubpages を使用して自動的に生成することができます。 しかし、より複雑なケースでは、リストを手作業で作成する必要があるかもしれません（そして、メンテナンスも必要です）。

例

関連情報