Bagikan melalui

Panduan pemformatan teks

  • Artikel

Penggunaan gaya berani, miring, dan kode yang konsisten dan sesuai untuk elemen teks meningkatkan keterbacaan dan membantu menghindari kesalahpahaman.

Tebal

Gunakan tebal untuk elemen UI, seperti pilihan menu, nama kotak dialog, dan nama bidang input.

Contoh

  • Ini: Dalam Penjelajah Solusi, klik kanan simpul proyek, lalu pilih Tambahkan > Item Baru.
  • Bukan ini: Dalam Penjelajah Solusi, klik kanan simpul proyek, lalu pilih Tambahkan > Item Baru.
  • Bukan ini: Dalam Penjelajah Solusi, klik kanan simpul proyek, lalu pilih Tambahkan > Item Baru.

Miring

Gunakan miring untuk:

  • Memperkenalkan istilah baru bersama dengan definisi atau penjelasan.
  • Nama file, nama folder, jalur.
  • Input pengguna.

Contoh

  • Ini: Di App Service, aplikasi berjalan dalam paket App Service. Paket App Service menentukan satu set sumber daya komputasi untuk menjalankan aplikasi web.
  • Bukan ini: Di App Service, aplikasi berjalan dalam "paket App Service." Paket App Service menentukan sekumpulan sumber daya komputasi untuk menjalankan aplikasi web.
  • Ini: Ganti kode di HttpTriggerCSharp.cs dengan kode berikut.
  • Bukan ini: Ganti kode dengan HttpTriggerCSharp.cs kode berikut.
  • Ini: Masukkan ContosoUniversity untuk Nama, lalu pilih Tambahkan.
  • Bukan ini: Masukkan "ContosoUniversity" untuk Nama, lalu pilih Tambahkan.

Gaya Kode

Gunakan gaya kode untuk:

  • Elemen kode, seperti nama metode, nama properti, dan kata kunci bahasa.
  • Perintah SQL
  • Nama paket NuGet
  • Perintah baris perintah*
  • Nama tabel dan kolom database
  • Nama sumber daya yang tidak boleh dilokalkan (seperti nama komputer virtual)
  • URL yang tidak ingin Anda klik

Mengapa? Panduan gaya yang lebih lama menentukan tebal untuk banyak elemen teks ini. Namun, sebagian besar artikel dilokalkan, dan gaya kode memberi tahu penerjemah untuk membiarkan bagian teks tersebut tidak diterjemahkan.

Gaya kode dapat sebaris (dikelilingi oleh ') atau blok kode pagar (dikelilingi oleh ''') yang mencakup beberapa baris. Letakkan cuplikan kode dan jalur yang lebih panjang di blok kode pagar.

* Dalam perintah baris perintah, gunakan garis miring di jalur file jika didukung di semua platform. Gunakan garis miring terbelakang untuk mengilustrasikan perintah yang berjalan di Windows, ketika hanya garis miring terbelakang yang didukung. Misalnya, garis miring ke depan berfungsi pada .NET CLI di semua platform, sehingga Anda akan menggunakan dotnet build foldername/filename.csproj daripada dotnet build foldername\filename.csproj.

Contoh menggunakan gaya sebaris

  • Ini: Secara default, Kerangka Kerja Entitas menginterpretasikan properti yang dinamai Id atau ClassnameID sebagai kunci utama.
  • Bukan ini: Secara default, Kerangka Kerja Entitas menginterpretasikan properti yang bernama Id atau ClassnameID sebagai kunci utama.
  • Ini: Paket ini Microsoft.EntityFrameworkCore menyediakan dukungan runtime untuk EF Core.
  • Bukan ini: Paket Microsoft.EntityFrameworkCore menyediakan dukungan runtime untuk EF Core.

Contoh blok kode yang dipagari

  • Ini: Tidak ada perintah yang dikirim ke database berdasarkan pernyataan yang hanya mengubah IQueryable, seperti kode berikut:

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • Bukan ini: Tidak ada perintah yang dikirim ke database berdasarkan pernyataan yang hanya mengubah IQueryable, seperti siswa var = konteks. Students.Where(s => s.LastName == "Davolio").

  • Ini: Misalnya, untuk menjalankan Get-ServiceLog.ps1 skrip di C:\Scripts direktori, ketik:

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • Bukan ini: Misalnya, untuk menjalankan skrip Get-ServiceLog.ps1 di direktori C:\Scripts , ketik: "C:\Scripts\Get-ServiceLog.ps1."

  • Semua blok kode yang dipagari harus memiliki tag bahasa yang disetujui. Untuk daftar tag bahasa dukungan, lihat Cara menyertakan kode dalam dokumen.

Tempat penampung

Jika Anda ingin pengguna mengganti bagian dari string input dengan nilainya sendiri, gunakan teks tempat penampung yang ditandai dengan tanda kurung sudut (kurang dari < dan lebih besar dari > karakter).

Opsi 1: Gunakan gaya kode untuk mengelilingi kata tempat penampung atau frasa yang mencakup. Misalnya, Anda dapat menggunakan backtick tunggal ' untuk pemformatan kode sebaris untuk satu frasa, atau triple-ticks ''' untuk pemformatan berpagar kode.

`az group delete -n <ResourceGroupName>`

Dirender sebagai:

az group delete -n <ResourceGroupName>

or

Opsi 2: Gunakan karakter \ garis miring terbalik untuk menghindari karakter tanda kurung sudut di Markdown, seperti \< dan \>. Meskipun hanya escape pertama di braket \< sudut kiri yang diperlukan, melarikan diri dari braket \> penutup juga berfungsi untuk konsistensi. HTML yang dirender tidak menampilkan karakter escape kepada pembaca:

az group delete -n \<ResourceGroupName\>

Dirender sebagai:

az group delete -n <ResourceGroupName>

Beri tahu pembaca tentang tempat penampung: Dalam teks yang mendahului contoh tempat penampung tersebut, jelaskan kepada pembaca bahwa teks dalam tanda kurung harus dihapus dan diganti dengan nilai nyata. Kami merekomendasikan penggunaan miring untuk input pengguna. Anda dapat memformat miring dalam kode sebaris kurung sudut:

Dalam contoh berikut, ganti teks <ResourceGroupName> tempat penampung dengan nama grup sumber daya Anda sendiri.

Perhatian

Situs Microsoft Learn tidak merender <teks tempat penampung> yang menggunakan tanda kurung sudut dalam kasus di mana tanda kurung tidak lolos dengan benar atau teks tidak diformat kode. Proses build Microsoft Learn menginterpretasikan <frasa tempat penampung> sebagai tag HTML yang bisa berbahaya bagi browser pembaca, dan menandainya sebagai tag-html yang tidak diizinkan. Anda akan melihat saran dalam laporan build, dan kata tempat penampung tidak dirender dalam output halaman Microsoft Learn saat itu terjadi.

Untuk menghindari kehilangan konten pada tempat penampung, gunakan code karakter pemformatan atau escape (\< \>) seperti yang dijelaskan sebelumnya.

Kami mencegah penggunaan kurung kurawal { } sebagai tempat penampung sintis. Pembaca dapat membingungkan tempat penampung kurung kurawal dengan notasi yang sama yang digunakan dalam:

  • Teks yang dapat diganti
  • String format
  • Interpolasi string
  • Templat teks
  • Konstruksi pemrograman serupa

Casing dan spasi: Anda dapat memisahkan nama tempat penampung dengan tanda hubung ("kasus kebab") atau dengan garis bawah, atau Anda dapat melakukannya dengan menggunakan kasus Pascal. Kasus Kebab mungkin menghasilkan kesalahan sintaksis, dan garis bawah dapat bertentangan dengan garis bawah. Semua huruf besar dapat berkonflik dengan konstanta bernama dalam banyak bahasa, meskipun mungkin juga menarik perhatian pada nama tempat penampung.

<Resource-Group-Name> atau <ResourceGroupName>

Judul dan teks tautan

Jangan terapkan gaya sebaris seperti miring atau tebal ke judul atau teks hyperlink.

Mengapa?

Orang mengandalkan teks hyperlink standar untuk mengidentifikasi elemen teks sebagai tautan yang dapat diklik. Menata tautan sebagai miring, misalnya, dapat mengaburkan fakta bahwa teks adalah tautan. Judul memiliki gaya mereka sendiri dan mencampur gaya lain di dalamnya terlihat buruk.

Contoh judul dan teks tautan

Tombol dan pintasan keyboard

Saat merujuk ke kunci atau kombinasi kunci, ikuti konvensi berikut:

  • Kapitalkan huruf pertama nama kunci.
  • Kelilingi nama kunci dengan <kbd> tag HTML.</kbd>
  • Gunakan "+" untuk menggabungkan kunci yang dipilih pengguna secara bersamaan.

Contoh tombol dan pintasan keyboard

  • Ini: Pilih Alt+Ctrl+S.
  • Bukan ini: Tekan ALT+CTRL+S.
  • Bukan ini: Tekan ALT+CTRL+S.

Pengecualian

Panduan gaya bukan aturan yang kaku. Dalam konteks di mana mereka membahayakan keterbacaan, lakukan sesuatu yang berbeda. Misalnya, tabel HTML dengan sebagian besar elemen kode mungkin terlihat terlalu sibuk dengan gaya kode di mana-mana. Anda dapat memilih gaya tebal dalam konteks tersebut.

Jika Anda memilih gaya teks alternatif di mana kode biasanya dipanggil, pastikan teks tidak apa-apa untuk diterjemahkan dalam versi artikel yang dilokalkan. Kode adalah satu-satunya gaya yang secara otomatis mencegah terjemahan. Untuk skenario di mana Anda ingin mencegah pelokalan tanpa menggunakan gaya kode, lihat String yang tidak dilokalkan.