markdown linting accessibility panduan gaya documentation

Panduan Linting Markdown: 15 Masalah Umum dan Cara Mengatasinya

Temukan dan perbaiki masalah umum Markdown termasuk judul yang dilewati, teks alternatif gambar hilang, URL kosong, pagar kode rusak, daftar tidak konsisten, dan format tabel salah.

W
WordToMD Tim
·

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

PeriksaMengapa itu pentingOtomatis atau manual?
Hirarki judulMempertahankan struktur dokumenLinter
Teks alternatif gambarMembuat gambar dapat dimengerti tanpa penglihatanLinter
Tautan deskriptifMeningkatkan aksesibilitas dan pemindaianLinter + tinjauan manual
Pagar kode tertutupMencegah sisa halaman menjadi kodeLinter
Label bahasa kodeMengaktifkan penyorotan sintaksis yang bergunaLinter
Spasi tambahanMenghindari perilaku khusus dialek yang tidak terlihatLinter
Satu judul halaman jelasMenjaga tujuan halaman tetap jelasTinjauan manual
Daftar yang konsistenMencegah kerusakan sarangTinjauan manual
Tabel yang validMenjaga struktur kolom tetap utuhTinjauan manual
Judul unikMencegah kebingungan jangkar duplikatTinjauan manual
Penggunaan portabel HTMLMenghindari kegagalan khusus perenderTinjauan manual
Paragraf yang dapat dibacaMeningkatkan pemahamanTinjauan 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

![](architecture.png)

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

![Request flow from the browser through the API gateway to the orders service](architecture.png)

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.

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:

  1. Penyaji mana yang memiliki hasil akhir?
  2. Apakah konten perlu dipindahkan ke tempat lain nanti?
  3. 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:

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.