Markdown bersifat permisif.Dokumen dengan kesalahan struktural masih dapat dirender, sehingga kesalahan tersebut mudah terlewatkan hingga tabel rusak, judul hilang dari navigasi, atau gambar menjadi tidak berarti bagi pengguna pembaca layar.
Markdown linting adalah proses pemeriksaan teks sumber untuk masalah struktural, aksesibilitas, dan konsistensi sebelum dipublikasikan.Mulailah dengan Linter Markdown untuk menangkap tingkat judul yang dilewati, teks alternatif gambar yang hilang, URL kosong, pagar kode yang tidak berlabel atau tidak tertutup, dan spasi tambahan.Kemudian gunakan daftar periksa manual dalam panduan ini untuk tinjauan editorial yang lebih luas.
Linting bukan tentang memaksakan preferensi sewenang-wenang.Aturan yang berguna harus mencegah masalah pembacaan, rendering, pemeliharaan, atau aksesibilitas yang sebenarnya.
Daftar Periksa Pra-Publikasi Cepat
| Periksa | Mengapa itu penting | Otomatis atau manual? |
|---|---|---|
| Hirarki judul | Mempertahankan struktur dokumen | Linter |
| Teks alternatif gambar | Membuat gambar dapat dimengerti tanpa penglihatan | Linter |
| Tautan deskriptif | Meningkatkan aksesibilitas dan pemindaian | Linter + tinjauan manual |
| Pagar kode tertutup | Mencegah sisa halaman menjadi kode | Linter |
| Label bahasa kode | Mengaktifkan penyorotan sintaksis yang berguna | Linter |
| Spasi tambahan | Menghindari perilaku khusus dialek yang tidak terlihat | Linter |
| Satu judul halaman jelas | Menjaga tujuan halaman tetap jelas | Tinjauan manual |
| Daftar yang konsisten | Mencegah kerusakan sarang | Tinjauan manual |
| Tabel yang valid | Menjaga struktur kolom tetap utuh | Tinjauan manual |
| Judul unik | Mencegah kebingungan jangkar duplikat | Tinjauan manual |
| Penggunaan portabel HTML | Menghindari kegagalan khusus perender | Tinjauan manual |
| Paragraf yang dapat dibaca | Meningkatkan pemahaman | Tinjauan manual |
Tempelkan dokumen representatif ke dalam linter, jalankan pemeriksaan, perbaiki baris yang dilaporkan, lalu pratinjau halaman lengkap dalam sistem penerbitan sebenarnya.
1. Tingkat Judul yang Dilewati
Masalah
# Deployment Guide
### Configure credentials
Dokumen melompat dari H1 ke H3.Ini mungkin terlihat dapat diterima ketika ukuran font adalah satu-satunya sinyal yang terlihat, namun garis besar strukturnya tidak ada levelnya.
Perbaiki
# Deployment Guide
## Configure credentials
Gunakan judul untuk mendeskripsikan hierarki, bukan untuk memilih ukuran visual.Jika “Konfigurasi kredensial” benar-benar termasuk dalam bagian yang hilang, tambahkan bagian tersebut:
# Deployment Guide
## Preparation
### Configure credentials
Pengelolaan Linter Markdown melaporkan judul yang melonjak lebih dari satu tingkat.
2. Judul H1 Banyak atau Hilang
Sebuah halaman biasanya memiliki satu judul yang jelas.Beberapa sistem dokumentasi menghasilkan H1 dari materi depan, sementara yang lain mengharapkannya di badan Markdown.Ketahui konvensi mana yang digunakan situs Anda.
Sumber yang ambigu
# Installation
# Configuration
Sumber jelas
# Product setup
## Installation
## Configuration
Jika templat situs Anda dirender title: Product setup sebagai halaman H1, isi dapat dimulai dengan H2.Aturannya bukanlah “setiap file Markdown harus berisi tepat satu #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. Judul Hanya Digunakan untuk Penekanan
Sumber ini membuat entri garis besar yang tidak perlu:
#### Important!
Jika teks tidak memperkenalkan suatu bagian, gunakan prosa atau keterangan yang sesuai:
**Important:** Back up the database before continuing.
Judul harus membantu pembaca menavigasi.Judul dekoratif membuat daftar isi berisik dan mengurangi kegunaan navigasi bantu.
4. Gambar Tanpa Teks Alternatif
Masalah

Gambar tidak memiliki alternatif teks.Pembaca yang tidak dapat melihatnya tidak menerima penjelasan, dan seseorang yang menelusuri gambar yang rusak atau cacat tidak dapat menentukan tujuannya.
Perbaiki

Jelaskan informasi yang disumbangkan oleh gambar, bukan tampilannya saja.Hindari frasa seperti “gambar” kecuali medianya penting.
Gambar dekoratif adalah kasus khusus.Teks alternatif kosong mungkin benar di HTML bila gambar tidak menyampaikan informasi, namun penyaji Markdown dan alur kerja konten berbeda.Jika suatu gambar murni dekoratif, pertama-tama tanyakan apakah gambar tersebut termasuk dalam dokumentasi teknis.
Linter menandai gambar Markdown dengan teks alternatif kosong.Itu Pemformat gambar dapat menghasilkan markup gambar dengan alternatif eksplisit dan keterangan opsional.
5. Tautan Lemah atau Telanjang
Masalah
Visit https://example.com/docs/setup for more information.
URL kosong sulit dipindai dan tidak menyenangkan saat dibaca dengan keras.Teks tautan umum tidak jauh lebih baik:
[Click here](https://example.com/docs/setup).
Perbaiki
Read the [service setup guide](https://example.com/docs/setup).
Tautan deskriptif memberi tahu pembaca apa yang akan mereka buka.Mereka juga tetap bermakna ketika diekstraksi ke dalam daftar tautan.
Linter mengidentifikasi banyak yang kosong http:// and https:// URL, namun tinjauan editorial masih diperlukan untuk menilai apakah teks tautan bermanfaat.
6. Pagar Kode Tidak Tertutup
Masalah
```javascript
const status = 'ready';
## Next section
Tanpa pagar penutup, penyaji dapat memperlakukan sisa halaman sebagai kode.
Perbaiki
```javascript
const status = 'ready';
```
## Next section
Pagar yang tidak tertutup dapat merusak sebagian besar dokumen yang sah.Linter melaporkan garis di mana pagar yang tak tertandingi dimulai.
7. Pagar Kode Tanpa Pengidentifikasi Bahasa
Kurang bermanfaat
```
npm run build
```
Lebih baik
```bash
npm run build
```
Pengenal bahasa mengaktifkan penyorotan sintaksis dan mengomunikasikan jenis konten yang dilihat pembaca.Gunakan pengidentifikasi umum seperti javascript, typescript, json, html, css, bash, powershell, yaml, atau markdown.
Jangan menambahkan bahasa yang tidak akurat hanya untuk mendapatkan warna.Untuk keluaran tidak terstruktur, gunakan text ketika tujuan mengenalinya.
8. Indentasi Daftar Tidak Konsisten
Masalah
- Install dependencies
- Production packages
* Development packages
- Optional tools
Campuran tab, spasi, dan penanda sulit ditinjau dan mungkin ditampilkan pada level yang berbeda.
Perbaiki
- Install dependencies
- Production packages
- Development packages
- Optional tools
Pilih lebar lekukan yang konsisten untuk proyek.Jumlah spasi yang tepat dapat bergantung pada dialek Markdown dan isi daftar, namun konsistensi sangat penting.
Gunakan Pemformat daftar bersarang untuk menormalkan poin campuran, penomoran, tab, dan lekukan sebelum tinjauan akhir.
9. Urutan Angka yang Diketik Secara Manual
Daftar bernomor panjang mahal untuk dipelihara:
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
Banyak penyaji Markdown mengizinkan setiap item untuk digunakan 1. sambil tetap menampilkan urutan yang diurutkan:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
Ini mengurangi penomoran ulang noise pada perbedaan sumber.Namun, sumber yang diberi nomor secara eksplisit akan lebih mudah untuk didiskusikan jika petunjuknya mengacu pada “langkah 3”.Pilih satu konvensi proyek dan terapkan secara konsisten.
Jangan gabungkan nomor yang diketik, penanda daftar urut, dan teks paragraf.Konfirmasikan hasil yang diberikan setelah mengedit langkah-langkah bertingkat.
10. Tabel Salah Bentuk
Masalah
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
Pemisah dan baris data tidak berisi jumlah kolom logis yang sama.
Perbaiki
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
Periksa juga karakter pipa yang tidak lolos di dalam sel:
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
Pengelolaan Pemformat tabel Markdown membantu mengekspos baris yang tidak rata dan menghasilkan sumber yang selaras.Untuk membuat tabel baru secara visual, gunakan Markdown Generator tabel.
11. Judul Duplikat dan Tabrakan Jangkar
Sebuah dokumen dapat secara sah mengulangi judul yang terlihat seperti “Contoh,” namun ID jangkar yang dihasilkan secara otomatis dapat menjadi #examples, #examples-1, dan #examples-2.Aturan pastinya berbeda-beda menurut penyaji.
Judul yang berulang membuat tautan manual menjadi rapuh:
- [API examples](#examples)
- [CLI examples](#examples)
Lebih menyukai judul deskriptif:
## API examples
## CLI examples
Kemudian buat daftar isi dengan Markdown Pembuat TOC dan verifikasi jangkar di platform target.
12. Spasi Tambahan
Spasi di akhir baris tidak terlihat.Dalam beberapa dialek Markdown, dua spasi tambahan membuat garis putus-putus, yang berarti tindakan editor yang tidak disengaja dapat mengubah rendering.
Laporan linter di akhir spasi sehingga Anda dapat memutuskan apakah hal ini disengaja.Lebih suka baris kosong untuk pemisahan paragraf.Jika penghentian garis keras benar-benar diperlukan, dokumentasikan dan terapkan konvensi pilihan proyek secara konsisten.
Editor biasanya dapat menghapus spasi tambahan secara otomatis saat disimpan, namun periksa apakah ini tidak mengubah jeda baris yang disengaja dalam konten lama.
13. HTML Mentah yang Mengurangi Portabilitas
Markdown sering kali mengizinkan HTML yang disematkan:
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
Blok tersebut mungkin berfungsi di satu situs web dan di-escape, dibersihkan, atau ditata secara tidak benar di tempat lain.Lebih suka portabel Markdown ketika dapat mengungkapkan arti yang sama:
> **Warning:** Restarting the service ends active sessions.
Gunakan HTML dengan sengaja untuk fitur yang Markdown tidak dapat diungkapkan, seperti ukuran gambar yang dikontrol atau yang didukung <details> blok.Simpan daftar tujuan di mana konten harus dirender dan uji masing-masing tujuan.
Pengelolaan Generator Info dapat menghasilkan sintaks khusus platform untuk GitHub, Obsidian, dan MkDocs ketika portabilitas kurang penting dibandingkan presentasi asli.
14. Paragraf yang Terlalu Panjang dan Kemampuan Pemindaian yang Buruk
Markdown dapat valid secara struktural dan masih sulit dibaca.Dinding teks yang berisi beberapa keputusan, peringatan, dan prosedur harus ditata ulang.
Gunakan:
- paragraf pendek untuk satu gagasan pokok;
- judul deskriptif untuk navigasi;
- daftar untuk item paralel;
- tabel untuk bidang yang benar-benar sebanding;
- blok kode untuk input dan output literal;
- info untuk sejumlah kecil pengecualian penting.
Jangan mengubah setiap kalimat menjadi sebuah peluru.Daftar berfungsi paling baik jika item-itemnya memiliki peran tata bahasa dan konseptual yang sama.
Penggunaan Jumlah kata dan waktu baca untuk memeriksa jumlah paragraf, jumlah judul, dan panjang bacaan, tetapi memperlakukan statistik sebagai sinyal dan bukan target.
15. Sintaks Khusus Perender Tanpa Rencana Kompatibilitas
GitHub daftar tugas, Obsidian tautan wiki, MkDocs peringatan, catatan kaki, daftar definisi, dan materi depan semuanya berguna, namun tidak didukung secara sama di semua tempat.
Misalnya:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
Sebelum mengadopsi ekstensi, jawablah tiga pertanyaan:
- Penyaji mana yang memiliki hasil akhir?
- Apakah konten perlu dipindahkan ke tempat lain nanti?
- Apa yang akan dilihat pembaca jika ekstensi tidak didukung?
Pertahankan fondasi Markdown portabel dan tambahkan sintaks platform di tepi penerbitan jika memungkinkan.
Alur Kerja Linting yang Praktis
Langkah 1: Periksa strukturnya
Tempelkan sumber ke dalam Linter Markdown.Perbaiki kesalahan terlebih dahulu, lalu peringatan, lalu item konsistensi informasi.Pemeriksaan otomatis harus mengidentifikasi lokasi;mereka tidak boleh secara diam-diam menulis ulang maknanya.
Langkah 2: Normalisasikan elemen yang sulit
Gunakan alat terfokus untuk pembersihan mekanis:
- Pemformat daftar bersarang untuk lekukan;
- Pemformat tabel Markdown untuk tabel pipa;
- Pemformat gambar untuk markup gambar;
- Pembuat daftar isi untuk menuju jangkar.
Perubahan terfokus menghasilkan perbedaan yang lebih kecil dan lebih mudah ditinjau dibandingkan pemformat luas yang menulis ulang seluruh file.
Langkah 3: Pratinjau dokumen
Buka sumber di Markdown Penyunting dan bandingkan Markdown dengan keluaran yang diberikan.Periksa:
- judul dan daftar isi;
- daftar dan daftar tugas;
- tabel pada layar sempit;
- gambar dan tautan;
- blok kode dan kode sebaris;
- info atau HTML mentah.
Langkah 4: Uji tujuan sebenarnya
Pratinjau umum tidak dapat mereproduksi setiap penyaji.Buka file di GitHub, Obsidian, GitLab, MkDocs, atau situs dokumentasi sebenarnya sebelum dipublikasikan.
Langkah 5: Tinjau maknanya, bukan hanya sintaksisnya
Tidak ada linter yang dapat menentukan apakah suatu prosedur aman, tautan mengarah ke kebijakan yang dimaksud, atau deskripsi gambar menyampaikan kesimpulan penting.Peninjau manusia harus memastikan keakuratan, kelengkapan, nada, dan kesesuaian audiens.
Rekomendasi Panduan Gaya Tim
Konvensi singkat yang terdokumentasi lebih efektif daripada lusinan preferensi yang tidak terucapkan.Definisikan:
- apakah judul halaman berada di depan atau di badan Markdown;
- perkembangan judul yang diizinkan;
- lekukan daftar dan gaya daftar terurut;
- persyaratan bahasa pagar kode;
- bagaimana gambar dan teks alternatif ditinjau;
- batas kompleksitas tabel;
- mengizinkan HTML dan ekstensi platform;
- panjang garis maksimum, jika tim menggunakannya;
- bagaimana tautan diperiksa;
- aturan linter mana yang memblokir publikasi.
Mulailah dengan aturan yang mencegah cacat nyata.Tambahkan aturan hanya ketika tim memahami masalah yang dipecahkannya.
FAQ
Apakah Markdown dapat diakses secara otomatis?
Tidak. Sintaks yang valid masih dapat berisi teks alternatif yang kosong, tautan yang tidak jelas, judul yang membingungkan, diagram yang tidak dapat diakses, dan urutan bacaan yang buruk.Aksesibilitas memerlukan tinjauan struktural dan editorial.
Akankah Markdown Linter menulis ulang dokumen saya?
Linter WordToMD melaporkan masalah nomor baris.Itu tidak menulis ulang sumber secara diam-diam, jadi Anda tetap memegang kendali atas setiap koreksi.
Mengapa linter melaporkan URL kosong?
Teks tautan deskriptif lebih mudah dipindai dan lebih berguna untuk teknologi bantu.Ganti URL dengan label yang bermakna kecuali alamat literal adalah informasi yang dibutuhkan pembaca.
Apakah pagar kode yang tidak berlabel selalu salah?
Tidak selalu, tetapi pengidentifikasi bahasa yang benar biasanya meningkatkan kejelasan dan penyorotan sintaksis.Gunakan text untuk keluaran biasa bila didukung alih-alih menetapkan bahasa pemrograman yang tidak akurat.
Haruskah semua proyek menggunakan aturan linting yang sama?
No. A GitHub README, brankas Obsidian, referensi API, dan situs penerbitan memiliki konvensi yang berbeda.Bagikan serangkaian aturan struktural dan aksesibilitas inti, lalu tambahkan pemeriksaan khusus tujuan.
Bisakah linting menggantikan proofreading?
Tidak. Linter mendeteksi pola.Itu tidak dapat memverifikasi kebenaran teknis, kualitas argumen, maksud pengguna, atau apakah sebuah kalimat dapat dimengerti dalam konteksnya.
Kesimpulan
Bagus Markdown lebih dari sekadar sumber yang terjadi saat render.Ini memiliki garis besar yang jelas, tautan yang bermakna, gambar yang dapat diakses, pagar kode lengkap, daftar yang konsisten, tabel yang valid, dan hubungan yang jelas dengan platform penerbitannya.
Jalankan Linter Markdown untuk pemeriksaan struktural cepat, gunakan Markdown Penyunting untuk tinjauan visual, dan terapkan pemformat terfokus hanya jika format tersebut membuat sumber lebih mudah dipelihara.Hasilnya adalah Markdown yang lebih portabel, mudah diakses, dan dapat diandalkan dalam pengeditan di masa mendatang.