แชร์ผ่าน

ใช้ลิงก์ในเอกสาร

  • บทความ

บทความนี้อธิบายวิธีการใช้ไฮเปอร์ลิงก์จากหน้าที่โฮสต์ที่ Microsoft Learn เพิ่มลิงก์ได้ง่ายใน markdown โดยมีหลักต่างกันเล็กน้อย ลิงก์จะแสดงเนื้อหาให้ผู้ใช้เห็นในหน้าเดียวกัน ในหน้าอื่นๆ ที่อยู่ติดกันหรือบนไซต์และ URL ภายนอก

Backend ของ Microsoft Learn ใช้ Open Publishing Services (OPS) ซึ่งสนับสนุน Markdown ตามมาตรฐาน CommonMark ที่แยกวิเคราะห์ผ่านเครื่องมือวิเคราะห์คํา Markdig โดยส่วนใหญ่ Markdown Flavors นี้จะเข้ากันได้กับ GitHub Flavored Markdown (GFM) เนื่องจากเอกสารส่วนใหญ่จะจัดเก็บไว้ใน GitHub และสามารถแก้ไขได้ สามารถเพิ่มการทำงานเพิ่มเติมได้ผ่านทางส่วนขยาย Markdown

สำคัญ

ลิงก์ทั้งหมดต้องปลอดภัย (https vs 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 สามารถเป็นเส้นทาง URL ที่สัมพันธ์กับรากของ https://learn.microsoft.comหรือ URL แบบสัมบูรณ์ที่มีไวยากรณ์ URL แบบเต็ม (ตัวอย่างเช่น https://github.com/MicrosoftDocs/PowerShell-Docs)

  • ใช้ลิงก์ URL เมื่อเชื่อมโยงไปยังเนื้อหาภายนอก docset ในปัจจุบัน หรือระหว่างบทความการอ้างอิงโดยอัตโนมัติและแนวคิดภายใน docset
  • วิธีที่ง่ายที่สุดในการสร้างลิงก์ที่เกี่ยวข้องคือการคัดลอก URL จากเบราว์เซอร์ของคุณ จากนั้นลบ https://learn.microsoft.com/en-us จากค่าที่คุณวางลงในมาร์กดาวน์
  • อย่ารวมตําแหน่งที่ตั้งใน URL สําหรับคุณสมบัติของ Microsoft (ตัวอย่างเช่น ลบออกจาก /en-us URL)

ลิงก์ไฟล์ใช้เพื่อเชื่อมโยงจากบทความหนึ่งไปยังอีกบทความหนึ่งภายใน docset

  • เส้นทางของไฟล์ทั้งหมดใช้อักขระเครื่องหมายทับไปข้างหน้า (/) แทนที่อักขระเครื่องหมายทับหลัง

  • การเชื่อมโยงบทความไปยังบทความอื่นในไดเรกทอรีเดียวกัน:

    [link text](article-name.md)

  • การเชื่อมโยงบทความไปยังบทความในไดเรกทอรีหลักของไดเรกทอรีปัจจุบัน:

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

  • การเชื่อมโยงบทความไปยังบทความในไดเรกทอรีย่อยของไดเรกทอรีปัจจุบัน:

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

  • การเชื่อมโยงบทความไปยังบทความในไดเรกทอรีย่อยของไดเรกทอรีหลักของไดเรกทอรีปัจจุบัน:

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

  • บทความบางอย่างประกอบด้วยทั้ง .yml และ ไฟล์ ที่.ymlไฟล์ประกอบด้วยเมตาดาต้าและ .md .md ประกอบด้วยเนื้อหา ในกรณีดังกล่าว ลิงก์ไปยัง .yml ไฟล์:

    [link text](../directory/article-name.yml) (ไม่ [link text](../directory/article-name-content.md))

หมายเหตุ

ไม่มีตัวอย่างก่อนหน้านี้ใช้ ~/ เป็นส่วนหนึ่งของการเชื่อมโยง เมื่อต้องการเชื่อมโยงไปยังเส้นทางแบบสัมบูรณ์ที่เริ่มต้นที่รากของที่เก็บข้อมูล ให้เริ่มต้นการเชื่อมโยงด้วย / การใส่ ~/ สร้างลิงก์ที่ไม่ถูกต้องเมื่อนำทางไปยังที่เก็บแหล่งข้อมูลบน GitHub การเริ่มต้นเส้นทางด้วย / แก้ไขอย่างถูกต้อง

เนื้อหาที่เผยแพร่บน 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 เดียวกันมีส่วนของ URL <product-service> เดียวกัน ตัวอย่างเช่น:

  • docset เดียวกัน:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Docset ที่แตกต่างกัน:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

สำหรับการเชื่อมโยงบุ๊กมาร์กไปยังหัวเรื่องในไฟล์ ปัจจุบัน ให้ใช้สัญลักษณ์แฮชแล้วตามด้วยคำตัวพิมพ์เล็กของส่วนหัว ลบเครื่องหมายวรรคตอนออกจากส่วนหัว และแทนที่ช่องว่างด้วยเส้นประ

[Managed Disks](#managed-disks)

เมื่อต้องลิงก์ไปยังส่วนหัวบุ๊กมาร์กในบทความอื่น ใช้ลิงก์แบบสัมพัทธ์ของไฟล์ หรือลิงก์แบบสัมพัทธ์ของไซต์รวมถึงสัญลักษณ์แฮช ตามด้วยคำของส่วนหัว ลบเครื่องหมายวรรคตอนออกจากส่วนหัว และแทนที่ช่องว่างด้วยเส้นประ

[Managed Disks](../../linux/overview.md#managed-disks)

คุณยังสามารถคัดลอกลิงก์บุ๊กมาร์กจาก URL ได้ เมื่อต้องการค้นหา URL ให้วางเมาส์ของคุณเหนือบรรทัดหัวเรื่องบน Microsoft Learn คุณควรเห็นไอคอนลิงก์ปรากฏขึ้น:

ไอคอนลิงก์ในส่วนหัวของบทความ

คลิกที่ไอคอนลิงก์จากนั้นคัดลอกข้อความจุดยึดบุ๊กมาร์กจาก URL (นั่นคือ ส่วนหนึ่งหลังจากแฮช)

หมายเหตุ

ส่วนขยาย Learn Markdown ยังมีเครื่องมือเพื่อช่วยในการสร้างลิงก์

การเพิ่มลิงก์จุดยึดแบบชัดเจนโดยใช้แท็ก HTML <a> นั้นไม่จำเป็นหรือแนะนำ ยกเว้นในฮับและเพจเริ่มต้น แต่ให้ใช้บุ๊กมาร์กที่สร้างโดยอัตโนมัติตามที่อธิบายไว้ใน ลิงก์บุ๊กมาร์ก สำหรับฮับและเพจเริ่มต้น ให้ประกาศจุดยึดดังนี้:

## <a id="anchortext" />Header text

or

## <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 เนื่องจากทําให้ง่ายต่อการกําหนดค่าข้อความลิงก์ นอกจากนี้ จะมีการตรวจสอบความถูกต้องในเวลาที่สร้าง และถ้า URL ไปยังการอ้างอิง API มีการเปลี่ยนแปลง ลิงก์จะยังคงใช้งานได้ หากต้องการลิงก์ไปยังหน้าอ้างอิง API ที่สร้างขึ้นอัตโนมัติใน docset ปัจจุบันหรือ docsets อื่น ให้ใช้ลิงก์ XRef ที่มี ID เฉพาะ (UID) ของประเภทหรือสมาชิก

เคล็ดลับ

ส่วนขยายตัวช่วยเหลือลิงก์อ้างอิง API สําหรับ VS Code ทําให้การแทรกลิงก์ .NET API Xref ลงใน Markdown และไฟล์ XML ทําได้ง่ายมาก

ตรวจสอบว่า 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) แสดงเป็น คลาสสตริง

พารามิเตอร์คิวรี 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>เขียนเป็น-1 ใน URL ซึ่งหมายถึง ' 1:

https://learn.microsoft.com/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)

เคล็ดลับ

ส่วนขยาย Learn Authoring Pack สําหรับ Visual Studio Code ช่วยให้คุณสามารถใส่ลิงก์แบบย่อและบุ๊กมาร์กได้อย่างถูกต้องไร้ซึ่งความน่าลองของการค้นหาเส้นทาง

ตัวเลือกคือองค์ประกอบการนำทางที่ปรากฏในบทความเอกสารเป็นรายการแบบเลื่อนลง เมื่อผู้อ่านเลือกค่าในเมนูแบบเลื่อนลง เบราว์เซอร์จะเปิดบทความที่เลือก โดยปกติรายการตัวเลือกจะมีลิงก์ไปยังบทความที่เกี่ยวข้องมากที่สุด ตัวอย่างเช่น เรื่องหัวข้อเดียวกันในภาษาการโปรแกรมหลายภาษาหรือชุดบทความที่เกี่ยวข้องอย่างใกล้ชิด

หากคุณมีตัวเลือกที่ฝังอยู่ในเอกสารรวม ใช้โครงสร้างลิงก์ต่อไปนี้:

> [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 อย่างไร นั่นเป็นหน้าท่ของ Google ที่จะบอก ถ้าจำเป็น เราสามารถอธิบายวิธีใช้เครื่องมือสำหรับนักพัฒนา Android กับ Azure แต่ Google ควรบอกเล่าถึงวิธีการใช้เครื่องมือของพวกเขา
  • PM signoff: คำขอให้ Microsoft ลงนามเพื่อออกจากเนื้อหาของบุคคลที่สาม เมื่อลิงก์ไปหน้าดังกล่าว เราจะพูดถึงบางสิ่งบางอย่างเกี่ยวกับความไว้วางใจของเราในเรื่องนี้และภาระหน้าที่ของเราหากมีผู้ปฏิบัติตามคำแนะนำ
  • รีวิวที่สดใหม่: ตรวจสอบว่าข้อมูลของบุคคลที่สามยังคงเป็นปัจจุบัน ถูกต้อง และมีความเกี่ยวข้อง ตลอดจนไม่มีการเปลี่ยนแปลงลิงก์
  • นอกสถานที่: ทำให้ผู้ใช้ทราบว่ากำลังไปที่ไซต์อื่น หากบริบทไม่ชัดเจน เพิ่มวลีเพื่อแสดงความหมาย ตัวอย่างเช่น: "ข้อกําหนดเบื้องต้นรวมถึงเครื่องมือสําหรับนักพัฒนา Android ซึ่งคุณสามารถดาวน์โหลดได้บนเว็บไซต์ Android Studio"
  • ขั้นตอนถัดไป: คุณสามารถเพิ่มลิงก์ไปยังบล็อก MVP ในส่วน "ขั้นตอนถัดไป" อีกครั้ง ตรวจสอบให้แน่ใจว่าผู้ใช้เข้าใจว่าพวกเขากำลังจะออกจากไซต์
  • ข้อมูลด้านกฎหมาย: เราได้รับการคุ้มครองตามกฎหมายภายใต้ ลิงก์ไปยังไซต์ ของบุคคลที่สามใน ข้อกําหนดในการใช้ ที่อยู่ในส่วนท้ายของหน้า microsoft.com ทุกหน้า