Bagikan melalui

Menggunakan tautan dalam dokumentasi

  • Artikel

Artikel ini menjelaskan cara menggunakan hyperlink dari halaman yang dihosting di Microsoft Learn. Tautan mudah ditambahkan ke markdown dengan beberapa konvensi yang bervariasi. Tautan mengarahkan pengguna ke konten di halaman yang sama, di halaman tetangga lain, atau di situs dan URL eksternal.

Backend Microsoft Learn menggunakan Open Publishing Services (OPS), yang mendukung markdown yang mematuhi CommonMark yang diurai melalui mesin penguraian Markdig . Rasa markdown ini sebagian besar kompatibel dengan GitHub Flavored Markdown (GFM), karena sebagian besar dokumen disimpan di GitHub dan dapat diedit di sana. Fungsionalitas tambahan ditambahkan melalui ekstensi Markdown.

Penting

Semua tautan harus aman (https vs http) setiap kali target mendukungnya (yang mayoritasnya harus).

Teks tautan

Kata-kata yang Anda sertakan dalam teks tautan harus bersahabat. Dengan kata lain, kata-kata tersebut harus berupa kata-kata bahasa Inggris normal atau judul halaman yang Anda tautkan.

Penting

Jangan gunakan "klik di sini" sebagai teks tautan. Ini buruk untuk pengoptimalan mesin pencari dan tidak mendeskripsikan target secara memadai.

Benar:

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

Salah:

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

Tautan dari satu artikel ke artikel lainnya

Ada dua jenis hyperlink yang didukung oleh sistem penerbitan: URL dan tautan file.

Tautan URL dapat menjadi jalur URL yang relatif terhadap akar https://learn.microsoft.com, atau URL absolut yang menyertakan sintaks URL lengkap (misalnya, https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Gunakan tautan URL saat menautkan ke konten di luar docset saat ini atau antara referensi yang dibuat secara otomatis dan artikel konseptual dalam docset.
  • Cara paling sederhana untuk membuat tautan relatif adalah dengan menyalin URL dari browser Anda, lalu menghapus https://learn.microsoft.com/en-us dari nilai yang Anda tempelkan ke markdown.
  • Jangan sertakan lokal dalam URL untuk properti Microsoft (misalnya, hapus /en-us dari URL).

Tautan file digunakan untuk menautkan dari satu artikel ke artikel lain dalam docset.

  • Semua jalur file menggunakan karakter forward-slash (/) alih-alih karakter back-slash.

  • Artikel menautkan ke artikel lain di direktori yang sama:

    [link text](article-name.md)

  • Artikel menautkan ke artikel di direktori induk direktori saat ini:

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

  • Artikel menautkan ke artikel di subdirektori direktori saat ini:

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

  • Artikel menautkan ke artikel di subdirektori direktori induk direktori saat ini:

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

  • Beberapa artikel terdiri dari .yml file dan .md , di mana .yml file berisi metadata dan .md berisi konten. Dalam hal ini, tautkan ke .yml file:

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

Catatan

Tidak ada contoh sebelumnya yang menggunakan ~/ sebagai bagian dari tautan. Untuk menautkan ke jalur absolut yang dimulai di akar repositori, mulai tautan dengan /. ~/ Termasuk menghasilkan tautan yang tidak valid saat menavigasi repositori sumber di GitHub. Memulai jalur dengan / menyelesaikan dengan benar.

Konten yang diterbitkan di Microsoft Learn memiliki struktur URL berikut:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Contoh:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> - mengidentifikasi bahasa artikel (misalnya: en-us atau de-de)
  • <product-service> - nama produk atau layanan (misalnya: powershell, dotnet, atau azure)
  • [<feature-service>] - (opsional) nama fitur atau sublayanan produk (misalnya: csharp atau load-balancer)
  • [<subfolder>] - (opsional) nama subfolder dalam fitur
  • <topic> - nama file artikel untuk topik (misalnya: gambaran umum atau gambaran umum load-balancer)
  • [?view=\<view-name>] - (opsional) nama tampilan yang digunakan oleh pemilih versi untuk konten yang memiliki beberapa versi yang tersedia (misalnya: azps-3.5.0)

Tip

Dalam kebanyakan kasus, artikel dalam docset yang sama memiliki fragmen URL yang sama <product-service> . Contohnya:

  • Docset yang sama:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Docset yang berbeda:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Untuk tautan marka buku ke judul dalam file saat ini , gunakan simbol hash diikuti dengan kata-kata huruf kecil judul. Hapus tanda baca dari judul dan ganti spasi dengan tanda hubung:

[Managed Disks](#managed-disks)

Untuk menautkan ke judul bookmark di artikel lain, gunakan tautan relatif file atau relatif situs ditambah simbol hash, diikuti dengan kata-kata judul. Hapus tanda baca dari judul dan ganti spasi dengan tanda hubung:

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

Anda juga dapat menyalin tautan bookmark dari URL. Untuk menemukan URL, arahkan mouse Anda ke garis judul di Microsoft Learn. Anda akan melihat ikon tautan muncul:

Ikon tautan dalam judul artikel

Klik ikon tautan lalu salin teks jangkar bookmark dari URL (yaitu, bagian setelah hash).

Catatan

Ekstensi Learn Markdown juga memiliki alat untuk membantu membuat tautan.

Menambahkan tautan jangkar eksplisit menggunakan <a> tag HTML tidak diperlukan atau direkomendasikan, kecuali di hub dan halaman arahan. Sebagai gantinya, gunakan marka buku yang dibuat secara otomatis seperti yang dijelaskan dalam tautan marka buku. Untuk halaman hub dan landing, deklarasikan jangkar sebagai berikut:

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

atau

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

Dan yang berikut ini untuk ditautkan ke jangkar:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Catatan

Teks jangkar harus selalu huruf kecil dan tidak berisi spasi.

Tautan XRef adalah cara yang disarankan untuk menautkan ke API, karena divalidasi pada waktu build. Untuk menautkan ke halaman referensi API yang dibuat secara otomatis di docset saat ini atau docset lainnya, gunakan tautan XRef dengan ID unik (UID) jenis atau anggota.

Tip

Anda dapat menggunakan ekstensi Learn Markdown untuk Visual Studio Code (bagian dari Learn Authoring Pack) untuk menyisipkan tautan .NET XRref yang muncul di Browser .NET API.

Periksa apakah API yang ingin Anda tautkan diterbitkan di Microsoft Learn dengan mengetikkan semua atau beberapa nama lengkapnya di browser .NET API atau kotak pencarian Windows UWP . Jika Anda tidak melihat hasil apa pun yang ditampilkan, jenisnya belum ada di Microsoft Learn.

Anda dapat menggunakan salah satu sintaks berikut:

  • Tautan otomatis:

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

    Secara default, teks tautan hanya memperlihatkan nama anggota atau jenis. Parameter kueri opsional displayProperty=nameWithType menghasilkan teks tautan yang sepenuhnya memenuhi syarat, yaitu namespace.type untuk jenis, dan type.member untuk anggota jenis, termasuk anggota jenis enumerasi.

  • Tautan gaya markdown:

    [link text](xref:UID)

    Gunakan tautan gaya Markdown untuk XRef saat Anda ingin mengkustomisasi teks tautan yang ditampilkan.

Contoh:

  • <xref:System.String> ditampilkan sebagai String

  • <xref:System.String?displayProperty=nameWithType> ditampilkan sebagai System.String

  • [Kelas string](xref:System.String) ditampilkan sebagai kelas String.

Parameter displayProperty=fullName kueri bekerja dengan cara yang sama seperti displayProperty=nameWithType untuk kelas. Artinya, teks tautan menjadi namespace.classname. Namun, untuk anggota, teks tautan ditampilkan sebagai namespace.classname.membername, yang mungkin tidak diinginkan.

Catatan

UID peka huruf besar/kecil. Misalnya, <xref:System.Object> menyelesaikan dengan benar tetapi <xref:system.object> tidak.

XRef membangun peringatan dan build inkremental

Build inkremental hanya membangun file yang telah berubah atau terpengaruh oleh perubahan. Jika Anda melihat peringatan build tentang tautan XREF yang tidak valid, tetapi tautan sebenarnya valid, ini bisa jadi karena build bertahap. File yang menyebabkan peringatan tidak berubah, sehingga tidak dibangun dan peringatan sebelumnya diputar ulang. Peringatan akan hilang ketika file berubah atau jika Anda memicu build penuh (Anda dapat memulai build penuh di ops.microsoft.com). Ini adalah kelemahan untuk build inkremental, karena DocFX tidak dapat mendeteksi pembaruan data di dalam layanan XREF.

Menentukan UID

UID biasanya merupakan nama kelas atau anggota yang sepenuhnya memenuhi syarat. Setidaknya ada dua cara untuk menentukan UID:

  • Klik kanan pada halaman Microsoft Learn untuk jenis atau anggota, pilih Tampilkan sumber, lalu salin nilai konten untuk ms.assetid:

    ms.assetid di sumber untuk halaman web

  • Gunakan situs lengkapi otomatis dengan menambahkan beberapa atau semua nama jenis ke URL. Misalnya, memasukkan https://xref.docs.microsoft.com/autocomplete?text=Writeline di bilah alamat browser Anda menampilkan semua jenis dan metode yang berisi Writeline dalam namanya, bersama dengan UID mereka.

Memverifikasi UID

Untuk menguji apakah Anda memiliki UID yang benar, ganti System.String di URL berikut dengan UID Anda, lalu tempelkan ke bilah alamat browser:

https://xref.docs.microsoft.com/query?uid=System.String

Tip

UID di URL peka huruf besar/kecil, dan jika Anda memeriksa UID kelebihan beban metode, jangan sertakan spasi di antara jenis parameter.

Jika Anda melihat sesuatu seperti berikut ini, Anda memiliki UID yang benar:

[{"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"}]

Jika Anda hanya melihat [] ditampilkan di halaman, Anda memiliki UID yang salah.

Pengodean persen URL

Karakter khusus dalam UID harus dikodekan HTML sebagai berikut:

Karakter Pengodean HTML
` %60
# %23
* %2A

Lihat daftar lengkap persen-kode.

Contoh pengodean:

  • System.Threading.Tasks.Task`1 mengodekan sebagai System.Threading.Tasks.Task%601 (lihat bagian pada jenis generik)

  • System.Exception.#ctor mengodekan sebagai System.Exception.%23ctor

  • System.Object.Equals* mengodekan sebagai System.Object.Equals%2A

Tipe Generik

Jenis generik adalah jenis-jenis seperti System.Collections.Generic.List<T>. Jika Anda menelusuri jenis ini di browser .NET API dan melihat URL-nya, Anda akan melihat bahwa <T> ditulis seperti -1 dalam URL, yang sebenarnya mewakili '1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Untuk menautkan ke tipe generik seperti Daftar<T>, kodekan ` karakter backtick sebagai %60, seperti yang diperlihatkan dalam contoh berikut:

<xref:System.Collections.Generic.List%601>

Metode

Untuk menautkan ke metode, Anda dapat menautkan ke halaman metode umum dengan menambahkan tanda bintang (*) setelah nama metode, atau ke kelebihan beban tertentu. Misalnya, gunakan halaman umum saat Anda ingin menautkan <xref:System.Object.Equals%2A?displayProperty=nameWithType> ke metode tanpa jenis parameter tertentu. Karakter tanda bintang dikodekan sebagai %2A. Contohnya:

<xref:System.Object.Equals%2a?displayProperty=nameWithType> tautan ke Object.Equals

Untuk menautkan ke kelebihan beban tertentu, tambahkan tanda kurung setelah nama metode dan sertakan nama jenis lengkap setiap parameter. Jangan letakkan karakter spasi di antara nama jenis atau tautan tidak akan berfungsi. Contohnya:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> tautan ke Object.Equals(Object, Object)

Karena file yang disertakan terletak di direktori lain, Anda harus menggunakan jalur relatif yang lebih panjang. Untuk menautkan ke artikel dari file sertakan, gunakan format ini:

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

Tip

Ekstensi Learn Authoring Pack untuk Visual Studio Code membantu Anda menyisipkan tautan dan marka buku relatif dengan benar tanpa tedium mencari tahu jalur.

Pemilih adalah komponen navigasi yang muncul di artikel dokumen sebagai daftar drop-down. Saat pembaca memilih nilai di menu drop-down, browser akan membuka artikel yang dipilih. Biasanya daftar pemilih berisi tautan ke artikel yang terkait erat, misalnya materi pelajaran yang sama dalam beberapa bahasa pemrograman atau serangkaian artikel yang terkait erat.

Jika Anda memiliki pemilih yang disematkan dalam sertakan, gunakan struktur tautan berikut:

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

Anda dapat menggunakan tautan gaya referensi untuk membuat konten sumber Anda lebih mudah dibaca. Tautan gaya referensi mengganti sintaks tautan sebaris dengan sintaks yang disederhanakan yang memungkinkan Anda memindahkan URL panjang ke akhir artikel. Berikut contoh Daring Fireball :

Teks sebaris:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Referensi tautan di akhir artikel:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Pastikan Anda menyertakan ruang setelah titik dua, sebelum tautan. Saat Anda menautkan ke artikel teknis lainnya, jika Anda lupa menyertakan ruang, tautan akan rusak di artikel yang diterbitkan.

Untuk menautkan ke halaman di properti Microsoft lain (seperti halaman harga, halaman SLA, atau apa pun yang bukan artikel dokumentasi), gunakan URL absolut, tetapi hilangkan lokal. Tujuannya di sini adalah bahwa tautan berfungsi di GitHub dan di situs yang dirender:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Pengalaman pengguna terbaik meminimalkan pengiriman pengguna ke situs lain. Jadi mendasarkan tautan apa pun ke situs pihak ketiga, yang kadang-kadang kita butuhkan, pada info ini:

  • Akuntabilitas: Tautkan ke konten pihak ketiga saat itu adalah informasi pihak ketiga yang akan dibagikan. Misalnya, ini bukan tempat Microsoft untuk memberi tahu orang-orang cara menggunakan alat pengembang Android--yaitu cerita Google untuk diceritakan. Jika perlu, kita dapat menjelaskan cara menggunakan alat pengembang Android dengan Azure, tetapi Google harus menceritakan kisah tentang cara menggunakan alat mereka.
  • Signoff PM: Minta Agar Microsoft menandatangani konten pihak ketiga. Dengan menghubungkannya, kami mengatakan sesuatu tentang kepercayaan kami padanya dan kewajiban kami jika orang-orang mengikuti instruksi.
  • Tinjauan kesegaran: Pastikan info pihak ketiga masih terkini, benar, dan relevan, dan tautan belum berubah.
  • Di luar lokasi: Membuat pengguna menyadari bahwa mereka akan pergi ke situs lain. Jika konteks tidak memperjelasnya, tambahkan frasa yang memenuhi syarat. Misalnya: "Prasyarat mencakup Android Developer Tools, yang dapat Anda unduh di situs Android Studio."
  • Langkah berikutnya: Tidak masalah untuk menambahkan tautan ke, misalnya, blog MVP di bagian "Langkah berikutnya". Sekali lagi, pastikan pengguna memahami bahwa mereka akan meninggalkan situs.
  • Legal: Kami tercakup secara hukum di bawah Tautan ke Situs Pihak Ketiga dalam footer Ketentuan Penggunaan di setiap halaman microsoft.com.