文書の構造

MDN 全体を通して、MDN の記事内の情報を一貫して表現するために使用する文書化構造があります。 このページは、あなたが書いたり、編集したり、対応させたりする文書に対して、ページの内容を適切に変更することができるように、これらの構造を記述した記事を掲載しています。

MDN のコードサンプル

MDN では、私たちが文書化しているウェブプラットフォーム機能の使用方法を示す多数のコード例を見ることができます。 この記事では、ページにコード例を追加する方法、使用できる種類、使用するタイミングについて説明します。

サイドバー

すべての MDN のページにはサイドバーを付けるべきです。 そのほとんどは、 YAML ファイルでデータ構造を定義し、フロントマターまたはマクロによってページにサイドバーを記載するシステムを使用して作成されています。

バナーと注意

特定の API リファレンスのページでは、記述するコンテンツの使用方法に影響する重要な要素を強調するために、バナーやお知らせを表示しています。 例えば、バナーは特定のインターフェイス、メソッド、プロパティが非推奨であり、実運用コードで使用すべきではない、または保護されたコンテキストでのみ使用することができる場合に強調表示するために使用します。

ページの種類

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

マクロの使用

rari バックエンドは MDN のビルドシステムで、よくあるタスクのマクロ構文を提供します。

ライブサンプル (EmbedLiveSample)

MDN は、記事中のコードブロックを「ライブサンプル」として表示することに対応しており、読者はウェブページで見ていくようなコードとその出力結果の両方を見ることができます。 この機能により、読者は実行されたコードが何を生成するかを正確に理解することができ、文書化がダイナミックで有益なものになります。 また、文書内のコードブロックが期待される出力を持ち、さまざまなブラウザーで使用したときに適切に動作することを、書き手が絶対的に確認することができます。

リンクマクロ

MDN には MDN コンテンツへの常に最新のリンクを作成するためのマクロが数多く指定されています。このガイドでは、別のページへの単一のリンクや、文書のサブページすべてへのリンクのリストを含めるために使用することができる MDN 相互参照マクロについて学びます。

互換性一覧表とブラウザー互換性データリポジトリー (BCD)

MDN には、DOM, HTML, CSS, JavaScript, SVG などの、あらゆるブラウザーで共有される技術についての互換性を表す一覧表の標準フォーマットがあります。 このデータを複数のプロジェクトで機械的に利用できるようにするため、Node.js パッケージが browser-compat-data リポジトリーからビルドされ、npm に公開されています。

仕様書一覧表

MDN 上のすべてのリファレンスページでは、 API または技術が定義されている仕様書に関する情報を提供するようにしてください。この記事ではこれらの表の外見を示し、構築方法を説明します。

構文の節

MDN リファレンスページの構文の節には、機能が持つ正確な構文を定義する構文ボックスがあります（例えば、どのような引数が受け入れられるか、どれがオプションかなど）。この記事では、リファレンス記事の構文ボックスの書き方を説明します。

機能の状態

機能の状態は、ブラウザーベンダー間での機能の実装段階に関する情報を開発者に提供するもので、以下のいずれかに該当します。