Bagikan melalui

Templat Metadata dan Markdown untuk dokumen .NET

  • Artikel

Templat dotnet/docs ini berisi contoh sintaks Markdown dan panduan tentang pengaturan 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.

Metadata

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 di antara titik dua (:) dan nilai untuk elemen metadata.
  • Titik dua dalam nilai (misalnya, judul) memutus pengurai 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 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 "melarikan diri" itu (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 -ing kata- kata.
  • Tidak ada kata-kata kecil - jangan sertakan, dan, di, atau, dll.
  • Harus berada di Markdown dan menggunakan ekstensi file .md.
  • Pertahankan nama file yang cukup pendek. Mereka adalah bagian dari URL untuk artikel Anda.

Heading

Gunakan kapitalisasi gaya kalimat. Selalu kapitalisasi kata pertama dari judul.

Gaya teks

Miring
Gunakan untuk file, folder, jalur (untuk item panjang, dibagi ke baris mereka sendiri), istilah baru.

Tebal
Gunakan untuk elemen UI.

Code
Gunakan untuk kode sebaris, kata kunci bahasa, nama paket NuGet, perintah baris perintah, nama tabel dan kolom database, dan URL yang tidak ingin Anda klik.

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

Tim dokumen .NET menggunakan konvensi berikut:

  • Dalam kebanyakan kasus, kami menggunakan tautan relatif dan mencegah penggunaan ~/ dalam tautan karena tautan relatif diselesaikan dalam 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 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.

Contoh:

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

Contoh:

  • 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

Anda dapat menemukan UID jenis, daftar kelebihan beban anggota, atau anggota tertentu yang kelebihan beban dari https://xref.learn.microsoft.com/autocomplete. String ?text=*\<type-member-name>* kueri mengidentifikasi jenis atau anggota yang ingin Anda lihat UID-nya. Misalnya, https://xref.learn.microsoft.com/autocomplete?text=string.format mengambil kelebihan beban String.Format . Alat ini mencari parameter kueri yang disediakan text di bagian mana pun dari UID. Misalnya, Anda dapat mencari nama anggota (ToString), nama anggota parsial (ToStri), jenis dan nama anggota (Double.ToString), dll.

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 Daftar<T>. Halaman Metode BinarySearch dengan cara umum alih-alih kelebihan beban tertentu seperti Daftar<T>. BinarySearch(T, IComparer<T>). Anda juga dapat menggunakan * untuk menautkan ke halaman anggota saat anggota tidak kelebihan beban; ini menyelamatkan Anda dari keharu-hari menyertakan daftar parameter dalam UID.

Untuk menautkan ke metode tertentu yang kelebihan beban, 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 <metode xref:System.DateTime.ToString(System.String,System.IFormatProvider)> ditautkan 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> tautan ke jenis System.Nullable<T> , sementara <xref:System.Func%602> tautan 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 tertaut

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

Video

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

> [!VIDEO <youtube_video_link>]

Contohnya:

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

ekstensi learn.microsoft

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

Daftar yang dicentang

Gaya kustom tersedia untuk daftar. Anda bisa 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 dicentang dalam tindakan di dokumen .NET Core.

Tombol

Tautan tombol:

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

Ini dirender sebagai:

tautan tombol

Anda dapat melihat contoh tombol dalam tindakan 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#.