多くの文書間だけでなく、単一の文書内でも、リンクは wiki において重大な構成要素であり、 MDN はそれにかなり依存しています。運の良いことに、リンクは作成が簡単でもありますが、更にたくさんの作り方があります!
メモ: 特にリンクの推奨される方法があります。これらは MDN 書式ガイドで説明されています。
ツールバーの使用
リンクを作成するのに最も分かりやすい方法は、ツールバーの「リンク」ボタンをクリックするか、 Ctl+K (Mac では Command-K) を押してリンク作成することです。リンクボタンは のような外見です。この機能を使用して、最初からリンクを作成したり、既存の選択したテキストにリンクを追加したりすることができます。
最初からリンクを作成する
リンクボタンをクリックすると、次のようなハイパーリンクエディターのダイアログが表示されます。
ここで新規のリンクを作ることができます。ダイアログ内のコントロールは次の通りです。
- リンクタイプ
- 作成しているリンクのタイプ。既定は「URL」で、 MDN またはサイト外のウェブ上のどこかの URL です。「ページ内のアンカー」または「E-Mail」を選択することもできます。「ページ内のアンカー」を使用すると、ツールバーのアンカーボタンを使用して以前に挿入したアンカーにリンクすることができます。「E-Mail」を使用すると、受信者の電子メールアドレス、件名、および既定のメッセージ内容を入力して
mailto:
URL を設定できます。ほとんどの場合は「URL」を使用します。 - 記事タイトル検索/リンクテキスト
- このフィールドには2つの目的があります。まず、リンク先として使用される特定のテキストを指定します (または、ダイアログボックスを開く前にドキュメント内のテキストを選択していた場合、そのテキストがリンク先として表示されます)。ここに入力されたテキストは、入力した内容と一致する MDN 上の記事を検索して、可能な宛先ページを見つけるために使用されます。たとえば、このボックスに "Array" と入力すると、次のように表示されます。
- ここに、入力したテキストがタイトルに含まれる MDN のすべてのページのリストが表示されます。リストをスクロールしてそれらのページの1つを選択するか、入力を続けてリストを絞り込むことができます。一覧の項目にはロケールが表示されます(この場合、"[en-US]")。そのテキストはリンク先のテキストでは使用されませんが、編集中のロケールと同じロケールの記事にリンクしていることを確認するのに役立ちます。
- 添付ファイル
- また、このリストから添付ファイルを選択して、リンクを現在のページに添付されているファイルのいずれかへのリンクにすることもできます。これはコードサンプルなどをダウンロードするためのリンクを提供する素晴らしい方法です。
- URL
- 最後に、 URL フィールドで実際に URL を直接入力できます。「記事タイトル検索」または「添付ファイル」メニューで選択した URL も表示されます。一般的な方法は、 MDN の他の場所で作業しているページに URL を貼り付けることです。 MDN の別の記事にリンクする場合は、 URL の先頭からドメイン名 ("https://developer.mozilla.org") を削除してください。
リンクを設定したら、 OK ボタンをクリックしてそれを挿入します。
注意していると、ハイパーリンクエディターダイアログに2番目のタブ (Advanced、高度な設定) があることがわかります。少なくとも現時点では、定期的に使用することをお勧めするオプションはありません。将来はリンクのための代替スタイルが存在する可能性がありますが、新しいツールバーウィジェットを追加して、それらの機能が利用可能になったらそれを使用する可能性があります。
既存テキストのリンク
既存のテキストをリンクにする場合は、プロセスをいくらか簡略化することができます。ハイパーリンクエディタを開く前に、リンクにするテキストを選択します。記事タイトル検索/リンクテキストフィールドに選択したテキストがあらかじめ入力されます。たとえば、次のテキストがあるとします。
このプロジェクトの作業中に JavaScript 配列を使用すると便利です。
"arrays" を適切なコンテンツへのリンクにする必要があります。その単語を選択してリンクエディタを起動するだけです。前のケースと同様の事前入力済みのダイアログが表示されます。提案された記事の上にマウスを「ホバーする」と、相対スラグ (developer.mozilla.org
を基準にした相対 URL) が表示され、その場所と記事の種類をより正確に把握できます。
ここでは一致候補として提案された記事のうち、"Arrays" は良い選択のように見えるので、それを選択することができます。これは自動的に URL フィールドに入力されるので、 OK をクリックすれば、テキストは次のようなリンクに変わります。
このプロジェクトの作業中に JavaScript の配列を使用すると便利です。
リンクマクロを使う
MDN はマクロを大量に使用しており、与えられた用語に適切なコンテンツへのリンクを自動的に作成したり、スタイルガイドに従ってスタイルを設定したりしています。これを考えてみましょう。私たちのスタイルガイドは、API の用語名、HTML の要素と属性、 CSS のプロパティ、関数名などは <code>
要素でスタイリングする必要があることを示しています。それらはまた、通常は、 MDN の適切なページへのリンクにする必要があります。
マクロを使用してこれらのリンクを作成するには少し慣れが必要ですが、多くの利点があります。
- 適切なスタイルがあなたのために適用されます
- リンクがあなたのために作成されます — 将来 MDN がどのように構成されていくかを将来的に見直すことができます
- 適切なツールチップをあなたのために作成することもできます
これらのマクロはたくさんありますが、ここではそれらをすべて見ないようにします。代わりに、最も一般的なもののいくつかの特定の例を見ていきます。詳細なリストについては、 MDN のカスタムマクロガイドのハイパーリンクの作成を参照してください。これらのマクロのいずれかの KumaScript ソースコードをいつでも見ることができます。ほとんどは、どのように動作するのか、もしあれば、さまざまなパラメータが何であるかを説明するコメントを先頭に付けています。
API 文書へのリンク
API へのスタイル付きリンクを作成するために非常に役立つマクロが多数あります。ここには最も有用なものがいくつかあります。いずれの場合も、 (<code>
スタイリングの自動追加を抑制するなど) 出力をより詳細に制御できるようにパラメータを追加することができます。下の各マクロ名をクリックすると、マクロコード自体を読むことができます。それらはすべて、どのように動作するのか、すべてのパラメータが何であるかを説明するコメントを先頭に付けています。
HTMLElement
- 適切にスタイル付けされ、リンクされた HTML 要素の名前を挿入します。たとえば、
{{HTMLElement("table")}}
は<table>
を生成します。 cssxref
- CSS リファレンスの CSS プロパティ、 @-規則、セレクターの文書を挿入します。たとえば、
{{cssxref("background-color")}}
はbackground-color
になります。 domxref
- 指定された API 用語の Web API リファレンスへのリンクを挿入します。たとえば、
{{domxref("window")}}
はwindow
を生成し、{{domxref("window.scrollBy()")}}
はwindow.scrollBy()
を挿入します。テキストをオーバーライドする追加のパラメータを指定することもでき、{{domxref("window.scrollBy", "scrollBy()")}}
はscrollBy()
になります。 SVGElement
- SVG 要素の名前を適切にスタイル付けしてリンクしたものを挿入します。たとえば、
{{SVGElement("circle")}}
は<circle>
を生成します。
同じ記事のセクションにリンクする
同じ記事内のセクションにリンクするには、anch マクロを使用できます。構文は簡単です: {{anch("宛先セクション名")}}
。デフォルトでは、表示されているリンクテキストはそのセクションのタイトルですが、代わりに使用する代替テキストを示す2番目のオプションのパラメータを追加できます。いくつかの例を示します。
{{anch("Using the toolbar")}}
は Using the toolbar のようになります。{{anch("Using the toolbar", "この記事の前半")}}
は この記事の前半 のようになります。
バグにリンクする
bug
マクロを使って、Mozilla の Bugzilla データベースのバグにリンクすることができます。このマクロは、リンクするバグ番号という単一のパラメータを受け入れます。たとえば、{{bug(765642)}}
は バグ 765642 のようになります。
同様に、他のブラウザーやウェブエンジンのバグへのリンクを作成することもできます。
- WebKit (Safari, etc.)
WebkitBug
:{{webkitbug(31277)}}
は WebKit bug 31277 を生成します。
RFCにリンクする
インターネットがコアレベルで動作する方法の多くは、 RFC に文書化されています。 RFC
マクロを使用して簡単に RFC を参照できます。たとえば、 {{RFC(2616)}}
は RFC 2616 になります。オプションで、記事の選択されたテキスト部分、および/またはリンク先の仕様内のセクション番号の代わりに、使用する代替リンクテキストを提供することもできます。
XPCOM インターフェイスに関する情報へリンクする
MDN スタッフはもはや XPCOM の文書を積極的に管理していませんが、ボランティアの貢献は歓迎します。
Mozilla の内部を文書化している場合は、 XPCOM のインタフェース文書へのリンクを簡単に作成できることが役立ちます。これにはいくつかのマクロが使われています。
XPCOM インターフェイスの文書全体にリンクするための構文は、 {{interface("interfacename")}}
です。たとえば、次のように書くことができます。
When you need to parse or create URIs, the {{interface("nsIIOService")}} interface can help.
結果は次のようになります。
When you need to parse or create URIs, the
nsIIOService
interface can help.
XPCOM インターフェイス上の特定のメソッドまたは属性に関する情報にリンクする必要がある場合は、 ifmethod
および ifattribute
マクロが必要です。これらは、インターフェイスの名前と、参照したいメソッドまたは属性の名前を引数として受け入れます。 ifmethod
マクロは、メソッドの名前の後にスタイルガイドに必須のカッコを追加することによって特別なフォーマットを行うので、特に興味深いです。たとえば、 {{ifmethod("nsIIOService", "newURI")}}
の結果は nsIIOService.newURI()
になります。それは、あなたが将来的にスタイルガイドの変更の可能性から保護されているケースです!
Mozilla 設定文書へのリンク
Mozilla プリファレンスの名前を挿入し、プリファレンスリファレンスの対応するページにリンクするには、 pref
マクロを使用します。これには1つのパラメータ、つまりリンク先のプリファレンスのフルネームが指定されています。たとえば、 {{pref("javascript.options.showInConsole")}}
を使用すると、 javascript.options.showInConsole
を作成できます。
Mozilla ソースファイルへリンクする
source マクロを使用して、 Mozilla のソースツリー内のファイルにリンクすることができます (おそらくこれは頻繁ではありません)。ファイルの完全な URL を指定する代わりに、単に /source/
ディレクトリを基準にしたパスを指定することができます。例: {{source("browser/Makefile.in")}}
は browser/Makefile.in
というリンクを生成します。
オプションで、リンクに使用する代替テキストを指定することもできます。たとえば、 {{source("browser/Makefile.in", "ブラウザーの makefile")}}
を使用すると、 ブラウザーの makefile のような結果になります。
マクロの使用方法について詳しく知りたい場合は、 Using macros のドキュメントを参照してください。また、マクロシステムの詳細については、 KumaScript のドキュメントを参照してください。
推奨コンテンツのリンク
関連ページやその他のお勧め資料のリストを作成する場合は、サイドバーにクイックリンクボックスを作成してください。このメカニズムは、記事の末尾にある古い「関連情報」の見出しを置き換えるものです。クイックリンクボックスの作成方法の詳細については、クイックリンクを参照してください。
URL スキーム
セキュリティ上の理由から、作成するのは以下のスキームを使用するリンクのみにしてください。
http://
https://
ftp://
mailto:
他のものは動作するかもしれないし、動作しないかもしれませんが、対応しておらず、おそらく編集スタッフによって削除されます。
about:
や chrome:
のような特別な URL スキームは、 Firefox、 Google Chrome、その他のブラウザーで、設定、デバッグ情報などの特別なコンテンツへのアクセスを提供するために使用されます。これらのリンクは記事のコンテンツからは機能しませんので、 MDN の記事内でこれらのスキームを使用してリンクを作成しないでください。同様のことは javascript:
と jar:
スキームにも適用され、これらはセキュリティ上の予防策から、最新のブラウザーではブロックされています。