MDN のコードサンプル
MDN では、私たちが文書化しているウェブプラットフォーム機能の使用方法を示す多数のコード例を見ることができます。 この記事では、ページにコード例を追加する方法、使用できる種類、使用するタイミングについて説明します。
メモ: このページでは、 MDN のページにコードを記載する方法について説明します。 もし、コードを掲載する様々な方法ではなく、 MDN の記事に記載するコードの lint やスタイルについてヒントが欲しいなら、コードスタイルガイドを参照してください。
利用できるコードサンプルの種類
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 デモ: 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 と CSS では UI が異なり、それぞれ 1 つの技術だけを単独で示します。 例えば、特定の HTML/CSS/JS 構造をどのように組み合わせるかを示したい場合には適していません。
- これは大きなコードサンプルを扱うためのものではありません。 UI は固定された高さの範囲に対応していますが、これが実に動作するのは短い（例えば 10 ～ 15 行）サンプルのみです。
- MDN のページは、インタラクティブサンプルを 1 つだけ持つことができます。
ライブサンプル
ライブサンプルは、 EmbedLiveSample マクロを使ってページに挿入します。
{{EmbedLiveSample}} マクロはページからコードブロックを取り出し、組み合わせて <iframe> に入れ、ページ内に結果を挿入します。
詳しくはライブサンプルガイドをご覧ください。
GitHub ライブサンプル
GitHub ライブサンプルは、 EmbedGHLiveSample マクロを使ってページに挿入します。
{{EmbedGHLiveSample}} を呼び出すと、指定された URL （GitHub の MDN のリポジトリーになければなりません）のコンテンツを取得し、ページ内の <iframe> 内に挿入します。
マクロの引数は 3 つあります。
- 埋め込む文書の URL — これは、
https://mdn.github.io/にある最上位のディレクトリーである mdn 組織からの相対 URL です。ですから、この引数には、my-subdirectory/example.htmlのように、URL の後の部分を含める必要があります。index.htmlの場合は、ファイル名を省略できます。 <iframe>の幅、パーセント値またはピクセル単位で表すことができます。<iframe>の高さ、パーセント値またはピクセル単位で表すことができます。
例を見てみましょう。 https://mdn.github.io/learning-area/html/introduction-to-html/getting-started/ のコードを埋め込みたいとします。次のように呼び出すことができます。
{{EmbedGHLiveSample("learning-area/html/introduction-to-html/getting-started/", '100%', 100)}}
表示されるときには次のようになります。