Bagikan melalui

Templat Metadata dan Markdown untuk dokumen .NET

Templat dotnet/docs ini berisi contoh sintaks Markdown dan panduan tentang mengatur metadata.

Saat membuat file Markdown, salin templat yang disertakan ke file baru, isi metadata seperti yang ditentukan di bawah ini, dan atur judul H1 di atas ke judul artikel.

Metainformasi

Blok metadata yang diperlukan berada di blok metadata sampel berikut:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
  • Anda harus memiliki spasi antara titik dua (:) dan nilai untuk elemen metadata.
  • Titik dua dalam nilai (misalnya, judul) mengganggu penguraian metadata. Dalam hal ini, kelilingi judul dengan tanda kutip ganda (misalnya, title: "Writing .NET Core console apps: An advanced step-by-step guide").
  • judul: Muncul di hasil mesin pencari. Judul tidak boleh identik dengan judul di judul H1 Anda, dan harus berisi 60 karakter atau kurang.
  • deskripsi: Meringkas konten artikel. Biasanya ditampilkan di halaman hasil pencarian, tetapi tidak digunakan untuk peringkat pencarian. Panjangnya harus 115-145 karakter termasuk spasi.
  • penulis: Bidang penulis harus berisi nama pengguna GitHub penulis.
  • ms.date: Tanggal pembaruan signifikan terakhir. Perbarui ini pada artikel yang sudah ada jika Anda meninjau dan memperbarui seluruh artikel. Perbaikan kecil, seperti kesalahan ketik atau sejenisnya tidak menjamin pembaruan.

Metadata lain dilampirkan ke setiap artikel, tetapi kami biasanya menerapkan sebagian besar nilai metadata di tingkat folder, yang ditentukan dalam docfx.json.

Markdown Dasar, GFM, dan karakter-karakter khusus

Anda dapat mempelajari dasar-dasar Markdown, GitHub Flavored Markdown (GFM), dan ekstensi khusus OPS di artikel referensi Markdown .

Markdown menggunakan karakter khusus seperti *, ', dan # untuk pemformatan. Jika Anda ingin menyertakan salah satu karakter ini dalam konten, Anda harus melakukan salah satu dari dua hal:

  • Letakkan garis miring terbelakang sebelum karakter khusus untuk "meloloskannya" (misalnya, \* untuk *).
  • Gunakan kode entitas HTML untuk karakter (misalnya, * untuk *).

Nama file

Nama file menggunakan aturan berikut:

  • Hanya berisi huruf kecil, angka, dan tanda hubung.
  • Tidak ada spasi atau karakter tanda baca. Gunakan tanda hubung untuk memisahkan kata dan angka dalam nama file.
  • Gunakan kata kerja tindakan yang spesifik, seperti mengembangkan, membeli, membangun, memecahkan masalah. Tidak ada kata-kata -ing.
  • Tidak ada kata-kata kecil - jangan sertakan a, dan, di, atau, dll.
  • Harus dalam format Markdown dan menggunakan ekstensi file .md.
  • Pertahankan nama file yang cukup singkat. Mereka adalah bagian dari URL untuk artikel Anda.

Headings

Gunakan kapitalisasi gaya kalimat. Selalu kapitalkan kata pertama judul.

Penataan teks

Italics
Gunakan untuk file, folder, path (untuk item yang panjang, diletakkan pada barisnya sendiri), istilah baru.

Tebal
Gunakan untuk elemen UI.

Code
Gunakan untuk kode sebaris, kata kunci bahasa, nama paket NuGet, perintah di baris perintah, tabel dan kolom database, serta URL yang tidak dapat diklik.

Lihat artikel umum tentang Tautan untuk informasi tentang jangkar, tautan internal, tautan ke dokumen lain, termasuk kode, dan tautan eksternal.

Tim dokumen .NET menggunakan konvensi berikut:

  • Dalam sebagian besar kasus, kami menggunakan tautan relatif dan tidak menganjurkan penggunaan ~/ dalam tautan karena tautan relatif berfungsi di sumber di GitHub. Namun, setiap kali kita menautkan ke file dalam repositori dependen, kita menggunakan ~/ karakter untuk menyediakan jalur. Karena file dalam repositori dependen berada di lokasi yang berbeda di GitHub, tautan tidak akan diselesaikan dengan benar dengan tautan relatif terlepas dari bagaimana mereka ditulis.
  • Spesifikasi bahasa C# dan spesifikasi bahasa Visual Basic disertakan dalam dokumen .NET dengan menyertakan sumber dari repositori bahasa. Sumber markdown dikelola di repositori csharplang dan vblang .

Tautan ke spesifikasi harus menunjuk ke direktori sumber tempat spesifikasi tersebut disertakan. Untuk C#, ini ~/_csharplang/spec dan untuk VB, ini ~/_vblang/spec, seperti dalam contoh berikut:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Sistem build memiliki beberapa ekstensi yang memungkinkan kami untuk menautkan ke API .NET tanpa harus menggunakan tautan eksternal. Anda menggunakan salah satu sintaks berikut:

  1. Tautan otomatis: <xref:UID> atau <xref:UID?displayProperty=nameWithType>

    Parameter displayProperty kueri menghasilkan teks tautan yang sepenuhnya memenuhi syarat. Secara default, teks tautan hanya memperlihatkan nama anggota atau jenis.

  2. Tautan markdown: [link text](xref:UID)

    Gunakan saat Anda ingin mengkustomisasi teks tautan yang ditampilkan.

Examples:

  • <xref:System.String> dirender sebagai String
  • <xref:System.String?displayProperty=nameWithType> dirender sebagai System.String
  • [String class](xref:System.String) dirender sebagai kelas String

Untuk informasi selengkapnya tentang menggunakan notasi ini, lihat Menggunakan referensi silang.

Beberapa UID berisi karakter khusus ', # atau *, nilai UID harus dikodekan HTML sebagai %60, %23 dan %2A masing-masing. Terkadang Anda akan melihat tanda kurung dikodekan tetapi itu bukan persyaratan.

Examples:

  • System.Threading.Tasks.Task'1 menjadi System.Threading.Tasks.Task%601
  • System.Exception.#ctor menjadi System.Exception.%23ctor
  • System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) menjadi System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Jika Anda menambahkan * (atau %2A) setelah UID, tautan kemudian mewakili halaman kelebihan beban dan bukan API tertentu. Misalnya, Anda dapat menggunakannya saat ingin menautkan ke halaman Daftar<T>.BinarySearch Method dengan cara umum alih-alih overload tertentu seperti Daftar<T>.BinarySearch(T, IComparer<T>). Anda juga dapat menggunakan * untuk menautkan ke halaman anggota saat anggota tidak kelebihan beban; ini akan menghemat Anda dari harus menyertakan daftar parameter di UID.

Untuk menautkan ke kelebihan beban metode tertentu, Anda harus menyertakan nama jenis yang sepenuhnya memenuhi syarat dari setiap parameter metode. Misalnya, <xref:System.DateTime.ToString> menautkan ke metode DateTime.ToString tanpa parameter, sementara <tautan xref:System.DateTime.ToString(System.String,System.IFormatProvider)> ke metode DateTime.ToString(String,IFormatProvider ).

Untuk menautkan ke jenis generik, seperti System.Collections.Generic.List<T>, Anda menggunakan karakter ' (%60) diikuti dengan jumlah parameter jenis generik. Misalnya, <xref:System.Nullable%601> merujuk ke tipe System.Nullable<T>, sedangkan <xref:System.Func%602> merujuk ke delegasi System.Func<T,TResult>.

Kode

Cara terbaik untuk menyertakan kode adalah dengan menyertakan cuplikan dari sampel yang berfungsi. Buat sampel Anda dengan mengikuti instruksi dalam artikel berkontribusi pada .NET . Termasuk cuplikan dari program lengkap memastikan bahwa semua kode berjalan melalui sistem Integrasi Berkelanjutan (CI) kami. Namun, jika Anda perlu menunjukkan sesuatu yang menyebabkan kesalahan waktu kompilasi atau runtime, Anda dapat menggunakan blok kode sebaris.

Untuk informasi tentang sintaks Markdown untuk memperlihatkan kode dalam dokumen, lihat Cara menyertakan kode dalam dokumen.

Gambar

Gambar statis atau GIF animasi

![this is the alt text](../images/Logo_DotNet.png)

Gambar yang dihubungkan

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videos

Anda dapat menyematkan video YouTube dalam file Markdown. Untuk mendapatkan URL video yang benar, klik kanan video, pilih Salin Kode Semat, dan salin URL dari <iframe> elemen .

> [!VIDEO <youtube_video_link>]

Contohnya:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

ekstensi dari learn.microsoft

learn.microsoft menyediakan beberapa ekstensi tambahan untuk GitHub Flavored Markdown.

Daftar yang sudah diperiksa

Gaya kustom tersedia untuk daftar. Anda dapat merender daftar dengan tanda centang hijau.

> [!div class="checklist"]
>
> - How to create a .NET Core app
> - How to add a reference to the Microsoft.XmlSerializer.Generator package
> - How to edit your MyApp.csproj to add dependencies
> - How to add a class and an XmlSerializer
> - How to build and run the application

Ini dirender sebagai:

  • Cara membuat aplikasi .NET Core
  • Cara menambahkan referensi ke paket Microsoft.XmlSerializer.Generator
  • Cara mengedit MyApp.csproj Anda untuk menambahkan dependensi
  • Cara menambahkan kelas dan XmlSerializer
  • Cara membangun dan menjalankan aplikasi

Anda dapat melihat contoh daftar yang diperiksa dalam tindakan di dokumen .NET Core.

Buttons

Tautan tombol:

> [!div class="button"]
> [button links](dotnet-contribute.md)

Ini dirender sebagai:

tautan pada tombol

Anda dapat melihat contoh tombol yang beraksi di dokumen Visual Studio.

Langkah demi langkah

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

Anda dapat melihat contoh langkah demi langkah dalam tindakan di Panduan C#.

  • Last updated on