MDN が動作している Kuma プラットフォームは、幅広い作業の自動化を可能にする強力なマクロシステムである KumaScript を提供しています。この記事は MDN のマクロを記事中で呼び出す方法について情報を提供します。
KumaScript ガイドでは MDN 上でマクロを利用する方法について詳細な情報を提供しているので、このセクションではむしろ全体の簡潔なまとめをします。
マクロはどのように実装されているか
MDN 上で動作するマクロは、サーバーで実行される JavaScript コードを使用して実装され、 Node.js によって解釈されます。そのうえ数多くのライブラリを用意しており、 Wiki 風のサービスを提供します。また、 Wiki プラットフォームとそのコンテンツを、マクロと連携させる機能を提供します。もっと詳細に興味があるのであれば、 KumaScript ガイドを参照して下さい。
コンテンツでのマクロの利用
実際にマクロを使うには、マクロの呼び出しを二重の中括弧で囲むだけです。引数があれば括弧で囲みます。つまり以下のようになります。
{{macroname(parameter-list)}}
マクロ呼び出しに関するいくつかのポイント
- マクロ名は大文字と小文字を区別します。それに関するエラーはよくあるので幾つかののパターンがあります。例えば、マクロ名に大文字があるのに全て小文字で入力しているかもしれません。また、小文字から始まる所を大文字にしてしまっているのかもしれません。
- 引数はコンマで区切ります。
- 引数が無ければ括弧は取ってしまって構いません。
{{macroname()}}
と{{macroname}}
はまったく同等です。 - 数値の引数は引用符で囲む必要がありませんが、囲んでも構いません(ただし、複数のピリオドを含むバージョン番号を渡す場合などは、引用符で囲む必要があります)。
- エラーが発生した場合は、コードを丁寧に読み返して下さい。何が問題なのかそれでも特定できなかった場合には、 KumaScript エラーのトラブルシューティングを参照して下さい。
マクロは高度にキャッシュ化されています。どの入力値についても(引数や、マクロを動作させる URL といった環境変数のいずれでも)、その結果は記憶され再利用されます。つまり、入力が変化した時だけマクロは実行されます。
注: ブラウザーでページを強制的に再読み込み(つまり、 Shift を押しながら再読み込み)すると、そのページのマクロを再評価することが出来ます。
マクロは大きなテキストブロックを挿入したり、 MDN の他記事からの内容で置き換えたりするようなシンプルなこともできますし、サイトを走査して目次をまるごと作り上げたり、出力のスタイリングをしたり、リンクを張ったりといった複雑なこともできます。
最もよく使われるマクロについて良く使われるマクロのページで学習することが出来ます。また、マクロの完全なリストもあります。そして多くのマクロには最上部のコメントとして、ソースに説明が組み込まれています。