ドキュメントでリンクを使用する
この記事では、Microsoft Learn でホストされているページからのハイパーリンクを使用する方法について説明します。 いくつかの規則が変更されていますが、リンクは Markdown に簡単に追加できます。 リンクは、同じページ内か、近くにある他のページ内か、外部のサイトや URL 上のコンテンツを指します。
Microsoft Learn バックエンドでは、Open Publishing Services (OPS) を使用します。これは、Markdig 解析エンジンを介して解析される CommonMark 準拠のマークダウンをサポートします。 ほとんどのドキュメントが GitHub に格納され、そこで編集可能であるように、このマークダウンのフレーバーのほとんどは GitHub Flavored Markdown (GFM) と互換性があります。 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)一部の記事は、 ファイルと
.mdファイルの両方.ymlで構成され、.ymlファイルにはメタデータが含まれており、.mdにはコンテンツが含まれています。 その場合は、ファイルに.ymlリンクします。[link text](../directory/article-name.yml)(ない[link text](../directory/article-name-content.md))
注意
前述の例で ~/ をリンクの一部としているものはありません。 リポジトリのルートから始まる絶対パスにリンクするには、リンクを / から始めます。 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 フラグメントが同じになります。 次に例を示します。
- 同じドキュメントセット:
https://learn.microsoft.com/dotnet/core/get-startedhttps://learn.microsoft.com/dotnet/framework/install
- 異なるドキュメントセット:
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 からブックマークのアンカー テキストをコピーします。
注意
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)
注意
アンカー テキストは必ず小文字で、スペースは使用できません。
XRef (相互参照) リンク
XRef リンクはビルド時に検証されるため、API へのリンクには、このリンクを使用することをお勧めします。 現在の docset または他の docset 内の自動生成された API リファレンス ページにリンクするには、種類またはメンバーの一意な ID (UID) を含む XRef リンクを使用します。
ヒント
VS Code 用 Learn Markdown 拡張機能 (Learn Authoring Pack の一部) を使用して、.NET API ブラウザーに表示される .NET XRref リンクを挿入できます。
リンク先の API が Microsoft Learn で公開されているかどうかを確認するには、 .NET API ブラウザー または Windows UWP 検索ボックスに完全な名前のすべてまたは一部を入力します。 結果が表示されない場合、型はまだ 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 として表示されます。これは、望ましくない可能性があります。
注意
UID は、大文字と小文字が区別されます。 たとえば、<xref:System.Object> は正しく解決されますが、<xref:system.object> は正しく解決されません。
XRef ビルド警告とインクリメンタル ビルド
インクリメンタル ビルドでは、変更されたファイル、または変更の影響を受けたファイルのみがビルドされます。 無効な XRef リンクに関するビルド警告が表示されても、そのリンクが実際は有効な場合、ビルドがインクリメンタル ビルドである可能性があります。 警告の原因となったファイルが変更されていないため、そのファイルはビルドされず、過去の警告が再度表示されました。 ファイルが変更されるか、完全なビルドをトリガーすると (ops.microsoft.com で完全なビルドを開始できる場合)、警告は表示されなくなります。 DocFX は Xref サービス内のデータ更新を検出できないため、これはインクリメンタル ビルドの欠点です。
UID を決定する
通常、UID は、完全修飾されたクラスまたはメンバーの名前です。 UID を決定するには、少なくとも次の 2 つの方法があります。
種類またはメンバーの Microsoft Learn ページを右クリックし、[ソースの表示] を選択し、ms.assetid のコンテンツ値をコピーします。
型の名前の一部または全部を URL に追加して、オートコンプリート サイトを利用します。 たとえば、ブラウザーのアドレス バーに
https://xref.docs.microsoft.com/autocomplete?text=Writelineと入力すると、名前に Writeline を含むすべての型とメソッドが、その UID とともに表示されます。
UID を確認する
UID が正しいかどうかをテストするには、次の URL の System.Stringを自分の UID に置き換えて、それをブラウザーのアドレス バーに貼り付けます。
https://xref.docs.microsoft.com/query?uid=System.String
ヒント
URL 内の UID は、大文字と小文字が区別されます。メソッド オーバーロード URL を確認する場合、パラメーター型の間にスペースを入れないようにしてください。
次のような内容が表示された場合、正しい UID です。
[{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,...xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"},{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,netframework-4.6,netframework-4.6.1,...,xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"}]
ページに [] だけが表示される場合、UID は正しくありません。
URL のパーセント エンコード
UID 内の特殊文字は、次のように HTML エンコードする必要があります。
| 文字 | HTML エンコード |
|---|---|
` |
%60 |
# |
%23 |
* |
%2A |
パーセント エンコードの完全な一覧を参照してください。
エンコード例:
System.Threading.Tasks.Task`1は、System.Threading.Tasks.Task%601としてエンコードされます (ジェネリック型に関するセクションを参照してください)System.Exception.#ctorは、System.Exception.%23ctorとしてエンコードされますSystem.Object.Equals*は、System.Object.Equals%2Aとしてエンコードされます
ジェネリック型
ジェネリック型は、System.Collections.Generic.List<T> などの型です。 .NET API ブラウザーでこの型を参照し、その URL を調べると、<T> は、URL で -1 として記述されていることがわかります。これは、実際には、 `1 を表します。
https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1
List<T> などのジェネリック型にリンクするには、次の例に示すように、` バッククォート文字を %60 としてエンコードします。
<xref:System.Collections.Generic.List%601>
メソッド
メソッドにリンクするには、メソッド名の後にアスタリスク (*) を追加してメソッドの全般ページにリンクするか、特定のオーバーロードにリンクします。 たとえば、特定のパラメーター型を指定しないで <xref:System.Object.Equals%2A?displayProperty=nameWithType> メソッドにリンクする場合に全般ページを使用します。 アスタリスク文字は、%2A としてエンコードされます。 次に例を示します。
Object.Equals への <xref:System.Object.Equals%2a?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 ページで、使用条件フッターの「第三者サイトへのリンク」に法的な情報を明記しています。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示