共用方式為

在文件中使用連結

  • 發行項

本文說明如何使用裝載於 Microsoft Learn 之頁面的超連結。 使用一些不同的慣例，可以輕易地將連結新增至 Markdown。 連結可將使用者指向相同頁面、其他相鄰頁面，或外部網站與 URL 中的內容。

Microsoft Learn 後端使用 Open Publishing Services （OPS），其支援透過 Markdig 剖析引擎剖析的 CommonMark 相容 Markdown。 此 Markdown 類別大多與 GitHub Flavored Markdown （GFM） 相容，因為大部分的檔都儲存在 GitHub 中，而且可以在那裡編輯。 額外的功能可透過 Markdown 延伸模組新增。

重要

每當目標支援連結時，所有連結都必須是安全的https http

連結文字

您包含在連結文字中的字詞應該淺顯易懂。 換句話說，它們應該是簡單的英文單字，或您要連結之網頁的標題。

重要

請勿使用 「按兩下這裡」做為連結文字。 這對搜尋引擎最佳化而言並不是一個好的選擇，且沒有適當地描述目標。

正確：

  • 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).

文章之間的連結

發佈系統支援兩種類型的超連結： URL 和 檔案連結。

URL 連結可以是相對於 根目錄的 https://zcusa.951200.xyzURL 路徑，或是包含完整 URL 語法的絕對 URL 路徑（例如 ， https://github.com/MicrosoftDocs/PowerShell-Docs。

  • 連結到目前 docset 的外部內容，或在 docset 內自動產生的參照與概念性文章之間連結時，請使用 URL 連結。
  • 建立相對連結的最簡單方式，就是從瀏覽器複製 URL，然後將 https://zcusa.951200.xyz/en-us 從貼到 Markdown 的值中移除。
  • 請勿將地區設定包含在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)）

注意

上述範例均未在連結中使用 ~/。 若要連結到從存放庫根開始的絕對路徑，請使用 / 來啟動連結。 瀏覽 GitHub 上的原始碼存放庫時，置入 ~/ 會產生無效的連結。 在路徑的開頭使用 / 即可正確解決。

Microsoft Learn 上發佈的內容具有下列 URL 結構：

https://zcusa.951200.xyz/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

範例：

https://zcusa.951200.xyz/azure/load-balancer/load-balancer-overview

https://zcusa.951200.xyz/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://zcusa.951200.xyz/dotnet/core/get-started
    • https://zcusa.951200.xyz/dotnet/framework/install
  • 不同的檔案集：
    • https://zcusa.951200.xyz/dotnet/core/get-started
    • https://zcusa.951200.xyz/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 連結是連結至 API 的建議方式，因為它們可讓您輕鬆地自定義連結文字。 此外，它們會在建置階段進行驗證，而且如果 API 參考的 URL 要變更，連結仍可運作。 若要連結到目前 docset 或其他 docset 中自動產生的 API 參照頁面，請搭配類型或成員的唯一識別碼 (UID) 來使用 XRef 連結。

提示

適用於 VS Code 的 API 參考連結協助程式延伸模組可讓您將 .NET API Xref 連結插入 Markdown 和 XML 檔案中，變得非常簡單。

在 .NET API 瀏覽器或 Windows UWP 搜尋方塊中輸入所有或部分完整名稱，以檢查您要連結的 API 是否已在 Microsoft Learn 上發佈。 如果您未看到任何結果顯示，則類型尚未顯示在 Microsoft Learn 上。

您可以使用下列其中一個語法：

  • 自動連結：

    <xref:UID>
<xref:UID?displayProperty=nameWithType>

    根據預設，連結文字只會顯示成員或型別名稱。 選用的 displayProperty=nameWithType 查詢參數會產生完整連結文字；亦即，namespace.type 表示類型，而 type.member 表示類型成員 (包括列舉類型成員)。

  • Markdown 式連結：

    [link text](xref:UID)

    當想要自訂顯示的連結文字時，請針對 XRef 使用 Markdown 式連結。

範例：

  • <xref：System.String> 顯示為 String

  • <xref：System.String？displayProperty=nameWithType> 會顯示為 System.String

  • [String 類別]（xref：System.String） 會顯示為 String 類別。

在類別中，displayProperty=fullName 查詢參數的運作方式與 displayProperty=nameWithType 相同。 亦即，連結文字會變成 namespace.classname。 不過，對於成員，鏈接文字會顯示為 namespace.classname.membername，這可能是不想要的。

注意

UID 會區分大小寫。 例如， <xref:System.Object> 會正確解析，但 <xref:system.object> 不會解析。

判斷 UID

UID 通常是完整類別或成員名稱。 若要判斷 UID，請以滑鼠右鍵按兩下類型或成員的 [Microsoft Learn] 頁面，選取 [檢視來源]，然後複製 ms.assetid 的內容值。

網頁原始檔中的 ms.assetid

URL 的百分號編碼

UID 中的特殊字元必須以 百分比編碼 ，如下所示：

字元 HTML 編碼
* *

編碼範例：

  • System.Exception.#ctor 會編碼為 System.Exception.%23ctor

泛型類型

泛型型別是指 System.Collections.Generic.List<T> 之類的類型。 如果在 .NET API 瀏覽器中瀏覽至此類型並查看其 URL，則會看到 <T> 在 URL 中寫成 -1，這實際上代表 `1：

https://zcusa.951200.xyz/dotnet/api/system.collections.generic.list-1

方法

若要連結到方法，可在方法名稱後面加上星號 (*) 來連結到一般方法，或連結到特定多載。 例如，當想要連結到不含特定參數類型的 <xref:System.Object.Equals*?displayProperty=nameWithType> 方法時，請使用一般頁面。 例如：

<xref:System.Object.Equals*?displayProperty=nameWithType> 會連結到 Object.Equals

若要連結到特定多載，請在方法名稱後面加上括弧，並包含每個參數的完整類型名稱。 請勿在類型名稱之間加入空白字元，否則連結將無法使用。 例如：

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> 會連結到 Object.Equals(Object, Object)

因為包含檔案位於另一個目錄中，所以您必須使用較長的相對路徑。 若要從包含檔案連結到文章，請使用此格式：

[link text](../articles/folder/article-name.md)

提示

適用於 Visual Studio Code 的 Learn Authoring Pack 延伸模組可協助您正確插入相對連結和書籤，而不需要找出路徑的 Tedium。

選取器是在文件文章中顯示為下拉式清單的導覽元件。 當讀者在下拉式清單中選取一個值時，瀏覽器會開啟選取的文章。 一般而言，選取器清單會包含密切相關的文章連結，例如多種程式設計語言的相同主題，或密切相關的系列文章。

如果您擁有內嵌在包含檔案中的選取器，則可以使用下列連結結構：

> [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/)

最佳使用者體驗會減少將使用者傳送到其他網站的情況。 因此，請根據以下資訊來提供有時所需要的協力廠商網站連結：

  • 責任：當您想要共用的資訊是協力廠商資訊時，連結到協力廠商內容。 例如，告知大家如何使用 Android 開發人員工具，並不是 Microsoft 的立場，那是 Google 的資訊。 如果有需要，我們可以解釋如何搭配 Azure 使用 Android 開發人員工具，但 Google 應該說明如何使用其工具。
  • PM 簽核：要求 Microsoft 簽核協力廠商內容。 透過與之連結，表示我們對其信任以及我們在人們遵循指示時的義務。
  • 重新整理評論：請確定第三方資訊仍然是最新的、正確且相關的資訊，且連結尚未變更。
  • 異地：讓使用者了解他們會前往另一個網站。 如果上下文不清楚，請加入一個限定詞組。 例如：「必要條件包括 Android 開發人員工具，您可以在 Android Studio 網站上下載。
  • 後續步驟：最好在[後續步驟] 區段中新增 MVP 部落格的連結。 同樣地，請確認使用者了解他們將會離開網站。
  • 法律：我們會在每一個 microsoft.com 頁面上使用規定頁尾中的第三方網站連結下合法涵蓋。