ドキュメントでリンクを使用する
この記事では、Microsoft Learn でホストされているページからハイパーリンクを使用する方法について説明します。 いくつかの規則が変更されていますが、リンクは Markdown に簡単に追加できます。 リンクは、同じページ内か、近くにある他のページ内か、外部のサイトや URL 上のコンテンツを指します。
Microsoft Learn のバックエンドでは、Open Publishing Services (OPS) が使われています。これは、Markdig 解析エンジンを使って解析される CommonMark 準拠の Markdown をサポートしています。 この Markdown 仕様は GitHub Flavored Markdown (GFM) とほぼ互換性があるため、ほとんどのドキュメントが GitHub に保存され、そこで編集可能です。 Markdown の拡張機能を通じて、その他の機能が追加されています。
重要
リンク先がサポートしている場合は、すべてのリンクをセキュアにする (http ではなく https にする) 必要があります。
リンク テキスト
リンク テキストに含める単語はわかりやすくすることをお勧めします。 つまり、通常の英単語にするか、リンク先のページのタイトルにします。
重要
リンク テキストとして「ここをクリック」を使用しないでください。 検索エンジンの最適化としては好ましくなく、リンク先の説明としても的確ではありません。
正しい例:
For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.
誤った例:
For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).
1 つの記事から別の記事へのリンク
公開システムでサポートされているハイパーリンクには、URL とファイル リンクの 2 種類があります。
URL リンクは、https://learn.microsoft.com のルートに対して相対的な URL パス、または完全な URL 構文を含む絶対 URL (たとえば、https://github.com/MicrosoftDocs/PowerShell-Docs) のいずれかです。
- 現在の docset 以外のフォルダーにあるコンテンツにリンクする場合、または docset 内の自動生成されたリファレンスおよび概念説明の記事の間でリンクする場合は、URL リンクを使用します。
- 相対リンクを作成する最も簡単な方法は、ブラウザーから URL をコピーし、マークダウンに貼り付けた値から
https://learn.microsoft.com/en-usを削除することです。 - Microsoft のプロパティの URL にロケールを含めないでください (たとえば、URL から
/en-usを削除してください)。
ファイル リンクは、docset 内のある記事から別の記事にリンクするために使用します。
すべてのファイル パスで、バックスラッシュ文字ではなくスラッシュ (
/) 文字を使用します。記事を同じディレクトリの別の記事にリンクする場合:
[link text](article-name.md)記事を現在のディレクトリの親ディレクトリにある記事にリンクする場合:
[link text](../article-name.md)記事を現在のディレクトリのサブディレクトリにある記事にリンクする場合:
[link text](directory/article-name.md)記事を現在のディレクトリの親ディレクトリのサブディレクトリにある記事にリンクする場合:
[link text](../directory/article-name.md)一部の記事は、
.ymlファイルと.mdファイルの両方で構成されています。.ymlファイルにはメタデータが含まれ、.mdファイルにはコンテンツが含まれています。 その場合は、.ymlファイルにリンクします。[link text](../directory/article-name.yml)(誤[link text](../directory/article-name-content.md))
Note
前述の例で ~/ をリンクの一部としているものはありません。 リポジトリのルートから始まる絶対パスにリンクするには、リンクを / から始めます。 GitHub のソース リポジトリを移動するときに ~/ が生成する無効なリンクを含みます。 / が正しく解決するパスから始めます。
Microsoft Learn でのリンクの構造
Microsoft Learn で公開されているコンテンツの URL 構造は次のとおりです。
https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]
例 :
https://learn.microsoft.com/azure/load-balancer/load-balancer-overview
https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
<locale>- 記事の言語を識別します (例: en-us、de-de)<product-service>- 製品またはサービスの名前 (例: powershell、dotnet、azure)[<feature-service>]- (省略可能) 製品の機能またはサブサービスの名前 (例: csharp、load-balancer)[<subfolder>]- (省略可能) 機能内のサブフォルダーの名前<topic>- トピックの記事ファイルの名前 (例: load-balancer-overview、overview)[?view=\<view-name>]- (省略可能) 複数のバージョンが使用可能なコンテンツのバージョン セレクターで使用されるビュー名 (例: azps-3.5.0)
ヒント
ほとんどの場合、同じ docset 内の記事は、<product-service> URL フラグメントが同じになります。 次に例を示します。
- 同じ docset:
https://learn.microsoft.com/dotnet/core/get-startedhttps://learn.microsoft.com/dotnet/framework/install
- 異なる docset:
https://learn.microsoft.com/dotnet/core/get-startedhttps://learn.microsoft.com/visualstudio/whats-new
ブックマーク リンク
"現在の" ファイル内にある見出しへのブックマーク リンクについては、ハッシュ記号を使用し、その後に見出しの語を小文字で続けます。 見出しから句読点を削除し、スペースをダッシュに置き換えます。
[Managed Disks](#managed-disks)
別の記事にあるブックマーク見出しにリンクするには、ファイル相対リンクまたはサイト相対リンクに加えてハッシュ記号を使用し、その後に見出しの語を続けます。 見出しから句読点を削除し、スペースをダッシュに置き換えます。
[Managed Disks](../../linux/overview.md#managed-disks)
また、URL からブックマーク リンクをコピーすることもできます。 URL を確認するには、Microsoft Learn の見出し行にマウス ポインターを合わせます。 リンク アイコンが表示されます。
リンク アイコンをクリックして、URL からブックマークのアンカー テキストをコピーします。
Note
Learn Markdown 拡張機能には、リンクの作成に役立つツールもあります。
明示的なアンカー リンク
ハブ ページとランディング ページを除いて、<a> HTML タグを使用して明示的なアンカー リンクを追加する必要はなく、推奨されません。 代わりに、「ブックマーク リンク」の説明に従って、自動生成されたブックマークを使用します。 ハブとランディングのページについては、アンカーを次のように宣言します。
## <a id="anchortext" />Header text
または
## <a name="anchortext" />Header text
アンカーへのリンクは次のようになります。
To go to a section on the same page:
[text](#anchortext)
To go to a section on another page.
[text](filename.md#anchortext)
Note
アンカー テキストは必ず小文字で、スペースは使用できません。
XRef (相互参照) リンク
XRef リンクは、リンク テキストを簡単にカスタマイズできるため、API へのリンクにお勧めします。 また、XRef リンクはビルド時に検証されるため、API 参照の URL が変更されても、リンクは引き続き機能します。 現在の docset または他の docset 内の自動生成された API リファレンス ページにリンクするには、種類またはメンバーの一意な ID (UID) を含む XRef リンクを使用します。
ヒント
VS Code 用の API Reference Link Helper 拡張機能を使用すると、.NET API XRef リンクを Markdown ファイルや XML ファイルに非常に簡単に挿入できます。
リンク先の API が Microsoft Learn で公開されているかどうかを確認します。このためには、.NET API ブラウザーまたは Windows UWP 検索ボックスに、完全な名前の全部または一部を入力します。 結果が何も表示されない場合、その API はまだ Microsoft Learn に公開されていません。
次のいずれかの構文を使用できます。
自動リンク:
<xref:UID> <xref:UID?displayProperty=nameWithType>既定では、リンクテキストには、メンバーまたは型の名前のみが表示されます。 オプションの
displayProperty=nameWithTypeクエリ パラメーターは、完全修飾されたリンク テキストを生成します。つまり、型の場合は namespace.type、列挙型メンバーを含む型メンバーの場合は type.member になります。Markdown スタイルのリンク:
[link text](xref:UID)表示されるリンク テキストをカスタマイズする場合は、Markdown スタイルの XRef リンクを使用します。
例 :
<xref:System.String> は String として表示されます
<xref:System.String?displayProperty=nameWithType> は System.String として表示されます
[String class](xref:System.String) は String class として表示されます。
displayProperty=fullName クエリ パラメーターは、クラスの displayProperty=nameWithType と同様に動作します。 つまり、リンク テキストは、namespace.classname になります。 ただし、メンバーに対しては、リンク テキストが namespace.classname.membername として表示されます。この長い形式は望ましくない場合があります。
Note
UID は、大文字と小文字が区別されます。 たとえば、<xref:System.Object> は正しく解決されますが、<xref:system.object> は正しく解決されません。
UID を決定する
通常、UID は、完全修飾されたクラスまたはメンバーの名前です。 UID を確認するには、型またはメンバーの Microsoft Learn ページで右クリックして、[ソースの表示] を選択し、ms.assetid の content の値をコピーします。
URL のパーセント エンコード
UID 内の特殊文字は、次のようにパーセントエンコードする必要があります。
| 文字 | HTML エンコード |
|---|---|
* |
* |
エンコードの例:
System.Exception.#ctorは、System.Exception.%23ctorとしてエンコードされます
ジェネリック型
ジェネリック型は、System.Collections.Generic.List<T> などの型です。 .NET API ブラウザーでこの型を参照し、その URL を調べると、<T> は、URL で -1 として記述されていることがわかります。これは、実際には、`1 を表します。
https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1
メソッド
メソッドにリンクするには、メソッド名の後にアスタリスク (*) を追加してメソッドの全般ページにリンクするか、特定のオーバーロードにリンクします。 たとえば、特定のパラメーター型を指定しないで <xref:System.Object.Equals*?displayProperty=nameWithType> メソッドにリンクする場合に全般ページを使用します。 次に例を示します。
Object.Equalsへの <xref:System.Object.Equals*?displayProperty=nameWithType> リンク
特定のオーバーロードにリンクするには、メソッド名の後にかっこを追加し、各パラメーターの完全な型名を含めます。 型名の間に空白文字を挿入しないでください。そうしなければ、リンクは機能しません。 次に例を示します。
Object.Equals(Object, Object)への <xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> リンク
インクルードからのリンク
インクルード ファイルは別のディレクトリにあるため、より長い相対パスを使用する必要があります。 インクルード ファイルから記事にリンクするには、次のフォーマットを使用します。
[link text](../articles/folder/article-name.md)
ヒント
Visual Studio Code 用の Learn Authoring Pack 拡張機能は、パスを確認するという面倒な作業を行わずに、相対リンクやブックマークを挿入するのに役立ちます。
セレクターのリンク
セレクターは、ドロップダウン リストとしてドキュメント記事に表示されるナビゲーション コンポーネントです。 閲覧者がドロップダウンの値を選択すると、選択した記事がブラウザーで開きます。 通常、セレクター リストには、関連性の高い記事のリンクが含まれます。たとえば、同じ題目が複数のプログラミング言語で提示されたり、関連性の高い一連の記事が提示されたりします。
セレクターがインクルードに埋め込まれている場合、次のリンク構造を使用してください。
> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)
参照形式のリンク
参照形式のリンクを使用することで、ソース コンテンツをさらに読みやすくすることができます。 参照形式のリンクを使用すると、インライン リンク構文を、簡素化された構文で置き換えることができます。この構文によって、長い URL を記事の最後に移動することができます。 Daring Fireball の例を次に示します。
インライン テキスト:
I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].
記事の最後のリンク参照:
<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/
コロンの後、リンクの前に必ずスペースを入れます。 他の技術情報記事にリンクする際に、スペースを入れ忘れてしまった場合、リンクが破損した状態で記事が公開されます。
技術ドキュメント セットではないページへのリンク
別の Microsoft 資産のページ (価格のページ、SLA のページ、その他ドキュメントの記事ではないもの) にリンクする場合は、絶対 URL を使用しますが、ロケールは省略します。 ここでの目的は、リンクが GitHub と次に示すサイトで作動することです。
[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)
第三者サイトへのリンク
最高のユーザー体験は、別サイトへのユーザーの誘導を最小限に抑えます。 そのため、サード パーティのサイトにリンクする必要がある場合は、次の情報に基づいて行ってください。
- アカウンタビリティ: 共有する情報がサード パーティの情報である場合に、サード パーティのコンテンツにリンクする。 たとえば、Microsoft のサイトで Android Developer Tools の使用方法の説明はしません。これは、Google が説明するべきことです。 必要であれば、Azure で Android 開発者用ツールを使用する方法を説明することはできますが、Google のツールの使用方法は、Google が説明することです。
- PM サインオフ: サードパーティ コンテンツの Microsoft サインオフを要求する。 サード パーティのコンテンツにリンクすることは、Microsoft がそのコンテンツを信頼していること、またユーザーがその指示に従った場合の Microsoft の責任を意味することになります
- 情報の鮮度のレビュー: サード パーティの情報が現在も有効で、間違いがなく、関連性を保っていて、また、リンクが変更されていないことを確認する。
- オフサイト: 別のサイトに移動していることをユーザーが認識できるようにする。 それが明確でない状況の場合は、適切なフレーズを追加します。 たとえば、「必要条件に Android Developer Tools が含まれます。このツールは Android Studio サイトでダウンロードできます」などです。
- 次のステップ: 「次のステップ」セクションに、MVP のブログなどへのリンクを追加しても構いません。 この場合も必ず、サイトを離れることをユーザーが認識できるようにしてください。
- 法的情報: Microsoft は、microsoft.com のすべてのページにある利用条件フッター内のサード パーティ サイトへのリンク条項により、法的に保護されています。