MDN のコードサンプル

4 種類のコードサンプルが利用できます。

• 静的サンプル — プレーンなコードブロックで、そのようなコードを実行した場合の結果を静的に示すスクリーンショットが付いている場合があります。
• ライブサンプル — ページ内のコードブロック群を取り出し、組み合わせて <iframe> 要素内の文書に動的に配置し、ページに iframe を埋め込んで結果を表示するマクロです。 公開されたページには、ソースコードブロックと結果が横に並んで表示されます。
• インタラクティブサンプル — ソースコードをページにレンダリングし、ソースの横にあるパネルに結果をレンダリングするマクロです。 読者はソースコードを編集し、例えばこの例を再実行して、変更の効果を確認することができます。
• GitHub 埋め込み — MDN 組織内の GitHub リポジトリーにある文書を取り込んで <iframe> 要素の中に入れ、それをページに埋め込んでコードをライブで表示するマクロです。

コードサンプルの種類ごとに、それぞれの用途があります。

• 静的サンプルは、コードを示す必要があり、かつ公開されたページ上でコードの実行結果を提示する必要がない場合や、記事の中で中間段階を示したい場合に便利です。 読者は、機能の使用方法を示すコードブロックをよく見ていくでしょう。そうすることで、自分のプロジェクトにコピー＆ペーストできる最小限の例を見つけることができます。 さらに、 API やライブサンプルとしてうまく動作しない機能を示す静的なコードブロックが必要になる場合もあります。
• ライブサンプルは、ソースコードを示し、それを実行している様子を示したい場合に便利です。また、それがスタンドアロンの例であることにそれほどこだわらない場合にも便利です。 ページ上のコードブロックとライブ結果の両方を横に並んでいるものを更新するには、コードを一度更新するだけでよいので、有益な機能です。
• インタラクティブサンプルは、リファレンスページで使用されています。 これらは 1 ページにつき 1 回のみの使用に制限されており、また、ページ上の特定の場所（導入部の後）に置く必要があります。 それらは、その機能が一般的に、または実用的に使用されていることを示すのに有益なものです。
• GitHub 埋め込みは、埋め込みたい既存の例をがあり、そのソースコードを表示させたくない場合、またはその例がスタンドアロンという形で利用できることを確認したい場合に便利です。 オンページコードとソースコードが 2 つの異なる場所に置かれているため、メンテナンスの手間が大きくなります。

MDN でサンプルを追加・更新する際には、スタイルやコンテンツについても考慮する必要があります。

• サンプルをページに掲載する際には、書かれている API や概念のすべての機能やオプションをカバーするようにしてください。 少なくとも、最も一般的なオプションやプロパティは提示すべきです。
• それぞれのサンプルの前で、そのサンプルが何をしているのか、なぜそれが興味深いのか、役に立つのかを説明してください。
• コードのそれぞれの部分の後には、それが何をするものなのかを説明してください。
• 可能な限り、大きなサンプルは小さく分割してください。例えば、「ライブサンプル」システムでは、サンプルを実行する前に、すべてのコードを自動的に 1 つにまとめてくれますが、実際には、JavaScript、HTML、CSS をより細かく分割し、それぞれの部分の後に説明文を付けることができます。これは、長いコードや複雑なコードをよりわかりやすく説明するためのよい方法です。
• APIや技術の各部分がどのように動作するのかを説明するだけに留まらないようにしましょう。 実世界で実現可能な用途を考慮し、それを説明するようにしましょう。

静的サンプルとは、ソースコード上で機能がどのように表示されるかを示すコードブロックです。 これらは Markdown の「コードフェンス」を使って、サンプルコードブロックで記述されているようにページに配置されます。 ドキュメントページで使用すると、次のようになります。

// これは JS の例です
const test = "Hello";
console.log(test);

InteractiveExample マクロを使用すると、 MDN のリファレンスページの冒頭に操作可能なサンプルを埋め込むことができます。 例えば、トピックや機能に関する記事全体を読むことなく、サンプルを試してみたい読者向けです。

InteractiveExample マクロは、文字列としてサンプルのタイトルをまず受け入れ、次のキーワードでサンプルの高さを指定します。 サンプルに含めるコードブロックはマクロの呼び出しの後ろに現れ、コードブロックの言語名の後の情報文字列にキーワード interactive-example を記載します。 JavaScript の Array.concat() の使用法は、このマクロの良くできた例であり、markdown ソースでは次のようになります。

{{InteractiveExample("JavaScript Demo: Array.concat()", "shorter")}}

```js interactive-example
const array1 = ["a", "b", "c"];
const array2 = ["d", "e", "f"];
const array3 = array1.concat(array2);

console.log(array3);
// 期待される出力: Array ["a", "b", "c", "d", "e", "f"]
```

インタラクティブサンプルについては、いくつかの制限事項があります。

• インタラクティブサンプルは、技術ごとに特化しています。 — JavaScript の UI と CSS の UI は異なりますし、 1 つの技術を独立させて説明しているだけです。 例えば、特定の HTML/CSS/JS 構造をどのように組み合わせるかを示したい場合には適していません。
• これは大きなコードサンプルを扱うためのものではありません。 UI は固定された高さの範囲に対応していますが、これが実に動作するのは短い（例えば 10 ～ 15 行）サンプルのみです。
• MDN のページは、インタラクティブサンプルを 1 つだけ持つことができます。

ライブサンプルは、 EmbedLiveSample マクロを使ってページに挿入します。 {{EmbedLiveSample}} マクロはページからコードブロックを取り出し、組み合わせて <iframe> に入れ、ページ内に結果を挿入します。 詳しくはライブサンプルガイドをご覧ください。

GitHub ライブサンプルは、 EmbedGHLiveSample マクロを使ってページに挿入します。 {{EmbedGHLiveSample}} を呼び出すと、指定された URL （GitHub の MDN のリポジトリーになければなりません）のコンテンツを取得し、ページ内の <iframe> 内に挿入します。

マクロの引数は 3 つあります。

1. 埋め込む文書の URL — これは、 https://mdn.github.io/ にある最上位のディレクトリーである mdn 組織からの相対 URL です。ですから、この引数には、 my-subdirectory/example.html のように、URL の後の部分を含める必要があります。 index.html の場合は、ファイル名を省略できます。
2. <iframe> の幅、パーセント値またはピクセル単位で表すことができます。
3. <iframe> の高さ、パーセント値またはピクセル単位で表すことができます。

例を見てみましょう。 https://mdn.github.io/learning-area/css/styling-boxes/backgrounds/ のコードを埋め込みたいとします。次のように呼び出すことができます。

{{EmbedGHLiveSample("learning-area/css/styling-boxes/backgrounds/", '100%', 100)}}

表示されるときには次のようになります。