Blokir kode Markdown - panduan cepat dan contoh cara penggunaan
Bloks Kode Markdown sangat sederhana
Di sini saya mereview Opsi kodeblock dalam Markdown.
Kodeblock Markdown
Kodeblock Markdown adalah cara untuk menampilkan kode atau teks yang telah diformat dalam dokumen Markdown, dengan mempertahankan format dan secara opsional mengaktifkan penyorotan sintaks. Ada dua jenis utama penataan kode dalam Markdown: kode inline dan kodeblock.
Jenis Kodeblock Markdown
Jenis | Contoh Sintaks | Kasus Penggunaan | Penyorotan Sintaks | Catatan |
---|---|---|---|---|
Kode inline | `code` |
Snippet pendek dalam teks | Tidak | Untuk kata tunggal atau perintah |
Blok indentasi | (4 spasi atau 1 tab) | Kode multi-baris (gaya lama) | Tidak | Tidak disarankan untuk penggunaan modern |
Blok terbatas | code |
Perbedaan Utama
- Kode inline menggunakan tanda kutip tunggal (`) dan digunakan untuk snippet pendek dalam kalimat.
- Blok kode indentasi menggunakan 4 spasi atau tab di awal setiap baris. Mereka tidak mendukung penyorotan sintaks dan kurang umum dalam Markdown modern.
- Blok kode terbatas menggunakan tiga tanda kutip ganda (```) atau tanda tilde (~~~) sebelum dan sesudah kode. Ini adalah metode yang disarankan, terutama di platform seperti GitHub, karena:
- Mereka lebih mudah dibaca dan ditulis.
- Anda dapat menentukan bahasa pemrograman segera setelah tanda kutip pembuka untuk penyorotan sintaks.
- Mereka mempertahankan format dan mendukung kode multi-baris.
Contoh blok kode terbatas dengan penyorotan sintaks:
Ketika kita memiliki teks berikut yang diformat dalam Markdown:
```python
def hello():
print("Hello, world!")
```
Maka teks yang dirender akan terlihat seperti ini:
def hello():
print("Hello, world!")
Praktik Terbaik dalam Menggunakan Kodeblock Markdown
- Gunakan blok kode terbatas (tiga tanda kutip ganda) untuk kode multi-baris agar memastikan kejelasan dan kompatibilitas di berbagai platform.
- Tentukan bahasa setelah tanda kutip pembuka untuk penyorotan sintaks (misalnya, ``````python).
- Gunakan kode inline untuk snippet pendek atau perintah dalam teks.
- Hindari blok kode indentasi kecuali diperlukan untuk kompatibilitas lama, karena mereka tidak mendukung penyorotan sintaks dan dapat kurang terbaca.
- Letakkan baris kosong sebelum dan setelah blok kode terbatas untuk meningkatkan keterbacaan dalam Markdown mentah.
Fitur Khusus
- Beberapa platform mendukung identifikasi bahasa tambahan seperti
diff
untuk menampilkan perubahan kode, yang dapat menyorot baris yang ditambahkan atau dihapus dalam tinjauan kode. - Untuk menampilkan tanda kutip dalam blok kode, bungkus blok tersebut dengan jumlah tanda kutip yang lebih besar (misalnya, empat tanda kutip untuk menampilkan tiga tanda kutip).
OutTake
Fitur | Kode Inline | Blok Indentasi | Blok Terbatas |
---|---|---|---|
Dukungan multi-baris | Tidak | Ya | Ya |
Penyorotan sintaks | Tidak | Tidak | Ya |
Disarankan untuk kode | Tidak | Tidak | Ya |
Kemudahan penggunaan | Mudah | Sedang | Mudah |
Gunakan blok kode terbatas dengan identifikasi bahasa untuk keterbacaan terbaik dan penyorotan sintaks. Simpan kode inline untuk snippet pendek, dan hindari blok indentasi kecuali diperlukan untuk kompatibilitas.
Penyorotan Sintaks Diff
Untuk menggunakan penyorotan sintaks diff dalam kodeblock Markdown secara efektif, ikuti langkah-langkah berikut:
- Gunakan blok kode terbatas dengan tiga tanda kutip ganda (```) untuk memulai dan mengakhiri blok Anda.
- Tentukan
diff
sebagai identifikasi bahasa segera setelah tanda kutip pembuka. Ini mengaktifkan penyorotan sintaks untuk perbedaan, mirip dengan yang Anda lihat dalam pesan commit Git atau permintaan penarikan (pull request).
Contoh:
- baris lama yang akan dihapus
+ baris baru yang akan ditambahkan
baris yang tidak berubah
- Baris yang dimulai dengan
-
akan ditonjolkan sebagai penghapusan (biasanya berwarna merah). - Baris yang dimulai dengan
+
akan ditonjolkan sebagai penambahan (biasanya berwarna hijau). - Baris tanpa awalan tidak akan ditonjolkan secara khusus.
Praktik terbaik:
- Gunakan format ini untuk menyampaikan perubahan kode, perbaikan, atau saran dalam dokumentasi, tinjauan kode, atau blog teknis.
- Letakkan baris kosong sebelum dan setelah blok kode Anda untuk meningkatkan keterbacaan dalam Markdown mentah.
- Catatan bahwa penyorotan diff hanya menonjolkan seluruh baris berdasarkan karakter awal; ia tidak menonjolkan perubahan inline dalam satu baris.
Tips:
Metode ini secara luas didukung di platform seperti GitHub, GitLab, dan banyak renderer Markdown, membuatnya menjadi pilihan yang andal untuk berbagi perubahan kode secara visual.
Bahasa yang Didukung
Kodeblock Markdown mendukung berbagai macam bahasa untuk penyorotan sintaks, tetapi himpunan bahasa yang didukung secara tepat bergantung pada renderer atau platform yang Anda gunakan. Markdown itu sendiri tidak mendefinisikan bahasa mana yang didukung; ia hanya meneruskan identifikasi bahasa ke mesin rendering, yang kemudian menerapkan penyorotan sintaks yang sesuai. Batasan kode Markdown itu sendiri tidak mendefinisikan himpunan bahasa pemrograman yang didukung secara resmi. Sebaliknya, daftar bahasa yang didukung bergantung pada renderer Markdown atau platform yang Anda gunakan (seperti GitHub, GitLab, VS Code, Typora, Quarto, dll.).
Bahasa yang umum didukung di platform utama (seperti GitHub, VS Code, Bitbucket, Docusaurus, dan ReadMe) meliputi:
- Web & Skrip: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
- Pemrograman: python (py), java, c, c++, c#, php, ruby, go, rust, scala, swift, kotlin, objective-c
- Data & Query: sql, r, matlab
- Markup & Konfigurasi: markdown, ini, toml, dockerfile, makefile
- Khusus: diff, mermaid, geojson, topojson, stl (untuk diagram dan visualisasi data di GitHub)
- Lainnya: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, dan banyak lagi
Cara menentukan bahasa: Gunakan nama bahasa segera setelah tanda kutip ganda pembuka:
```python
def hello():
print("Hello, world!")
```
Bahasa berikut didukung secara luas di KEBANYAKAN renderer Markdown:
Bahasa | Identifikasi Umum |
---|---|
Python | python, py |
JavaScript | javascript, js |
TypeScript | typescript, ts |
Java | java |
C | c |
C++ | cpp, c++ |
C# | csharp, cs, c# |
Go | go |
Ruby | ruby, rb |
PHP | php |
Rust | rust |
Swift | swift |
Kotlin | kotlin |
HTML | html |
CSS | css |
Shell/Bash | shell, bash, sh, zsh |
SQL | sql |
JSON | json |
YAML | yaml, yml |
Markdown | markdown, md |
Perl | perl |
Lua | lua |
R | r |
Matlab | matlab |
Makefile | makefile |
Catatan: Identifikasi bahasa sebenarnya dapat bervariasi (misalnya, js
vs. javascript
). Sebagian besar renderer tidak peka terhadap huruf besar-kecil untuk nama bahasa.
Cara menemukan daftar lengkap bahasa yang didukung:
- GitHub: Menggunakan Linguist untuk penyorotan, mendukung ratusan bahasa.
- VS Code & banyak renderer web: Menggunakan highlight.js atau Pygments—lihat dokumentasi mereka untuk daftar lengkap.
- Bitbucket: Merujuk ke CodeMirror modes dan Pygments lexers.
Poin penting:
- Sebagian besar platform mendukung semua bahasa pemrograman, skrip, dan markup utama.
- Beberapa platform juga mendukung format diagram dan data (seperti mermaid, geojson).
- Identifikasi bahasa biasanya tidak peka terhadap huruf besar-kecil tetapi sebaiknya dalam huruf kecil untuk kompatibilitas terbaik.
- Jika Anda menggunakan identifikasi bahasa yang tidak didukung, blok kode akan ditampilkan sebagai teks biasa.
Menentukan nama file dalam kodeblock Markdown
Untuk menentukan nama file dalam kodeblock Markdown, Anda memiliki beberapa opsi, tetapi metode yang digunakan bergantung pada platform dan renderer:
1. Nama file dalam label kodeblock (sintaks meta)
Beberapa mesin Markdown (seperti beberapa generator situs statis, alat dokumentasi, dan platform blogging) mendukung sintaks meta di mana Anda menambahkan nama file setelah bahasa, dipisahkan oleh titik dua:
```js:app.js
console.log("Hello, world!");
```
Ini akan menampilkan nama file (misalnya, app.js
) di atas atau di sebelah blok kode, tergantung pada renderer.
Dan renderer Hugo di situs ini tidak mendukung fitur ini:
console.log("Hello, world!");
Catatan: Fitur ini tidak didukung di semua platform (misalnya, Markdown berflavor GitHub saat ini tidak mendukung fitur ini).
2. Judul atau kode inline di atas
Untuk kompatibilitas universal (termasuk GitHub, Stack Overflow, dan sebagian besar renderer Markdown), letakkan nama file di atas blok kode, menggunakan judul atau kode inline tebal:
**`app.js`**
```
console.log("Hello, world!");
```
Atau:
#### `app.js`
```
console.log("Hello, world!");
```
Ini secara visual menghubungkan nama file dengan blok kode dan bekerja di mana saja.
3. Nama file sebagai komentar dalam kode
Alternatifnya, Anda dapat menyertakan nama file sebagai komentar di dalam blok kode itu sendiri:
```
// app.js
console.log("Hello, world!");
```
Ini sangat berguna jika Anda ingin nama file terlihat ketika menyalin kode.
Ringkasan dan Praktik Terbaik
Metode | Didukung di GitHub | Didukung di Docs/Blogs | Universal |
---|---|---|---|
Sintaks meta (misalnya, :app.js ) |
Tidak | Terkadang | Tidak |
Judul/kode inline di atas | Ya | Ya | Ya |
Komentar dalam kode | Ya | Ya | Ya |
Gunakan judul atau kode inline tebal di atas blok kode untuk kompatibilitas maksimal, dan pertimbangkan menambahkan komentar dalam kode untuk kejelasan ketika berbagi di berbagai platform.