Konvensi Markdown

Referensi kanonik untuk bentuk dan format Markdown di seluruh artefak .md dan .mdx yang ditulis. Ringkasan di CLAUDE.md bagian Conventions adalah deklarasi inline; halaman ini adalah referensi mandiri yang dikutip kontributor hilir.

---

1. VarianCopy Anchor Link

GitHub-Flavored Markdown (GFM) adalah varian host. Setiap artefak dirender dengan benar di UI web GitHub, di situs dokumentasi Fumadocs, dan di editor standar yang mengenali Markdown.

2. Hierarki headingCopy Anchor Link

Satu H1 per berkas. Heading berikutnya turun secara monoton (H2 → H3 → H4) tanpa melewati level. Heading menggunakan huruf kapital gaya kalimat (sentence case); tanpa HURUF KAPITAL SEMUA, tanpa Huruf Kapital Di Awal Setiap Kata. H1 membawa judul utama dokumen. Pada halaman situs dokumentasi, title di frontmatter dirender sebagai H1 dan menjadi anchor halaman di navigasi situs dokumentasi, sehingga isi halaman dimulai dari H2.

3. Blok kodeCopy Anchor Link

Blok kode berpagar mendeklarasikan bahasanya (```python, ```bash, ```yaml, ```json, ```mermaid). Blok tanpa tag menonaktifkan penyorotan sintaks dan menandakan penyimpangan penulisan; aturan markdownlint MD040, yang dikonfigurasi di .markdownlint.json, menegakkan tag bahasa.

4. Tautan internalCopy Anchor Link

Referensi silang internal menggunakan jalur root situs (mis., [Authorship header](/docs/reference/authorship-header)). Jalur relatif repositori polos dengan ekstensi .md/.mdx (/docs/foo.md) dan URL lengkap ke repo yang sama (https://github.com/ahmed-g-gad/apothem/blob/main/...) dihindari untuk tautan di dalam situs karena menyulitkan penggantian nama halaman dan reorganisasi bagian.

Jalur root situs /docs/... ini — dan bentuk /<locale>/docs/... untuk locale kohor non-default — di-resolve terhadap himpunan halaman di disk di bawah site/content/docs/ oleh validator link-check: /docs/a/b dipetakan ke site/content/docs/a/b.mdx atau ke indeks folder site/content/docs/a/b/index.mdx, dan bentuk locale dipetakan di bawah subpohon site/content/docs/<locale>/. Tautan ke rute yang telah dihapus atau diganti namanya tidak di-resolve ke salah satu dari kedua berkas itu dan dilaporkan sebagai rute mati (404 yang dilihat pengguna) oleh link-check, sebuah matcher advisori yang tidak menggagalkan eksekusi (lihat §6).

Tautan eksternal ke ref yang dapat berubah (main, master, latest, HEAD) dipatok ke SHA commit atau tag rilis setiap kali stabilitas konten yang ditautkan itu penting; referensi yang volatil didokumentasikan sebagai volatil dengan komentar {/* volatile */} di sebelahnya.

5. Header kepengaranganCopy Anchor Link

Setiap artefak Markdown (dengan pengecualian yang dicantumkan di src/apothem/schemas/header-exceptions.txt) membawa header kepengarangan kanonik, yaitu satu baris SPDX-License-Identifier: MIT, dalam varian komentar sesuai tipe berkasnya menurut Header kepengarangan: komentar HTML pada berkas .md dan komentar {/* ... */} pada berkas .mdx. Tanpa frontmatter, baris header berada di baris 1. Dengan frontmatter YAML, frontmatter tetap berada di byte 0 dan baris header mengikuti --- penutup.

6. ValidatorCopy Anchor Link

Hook pre-commit markdownlint di .pre-commit-config.yaml menjalankan markdownlint-cli dengan kebijakan aturan di .markdownlint.json dan menegakkan sebagian besar aturan di §§1–4. Alur kerja Markdown Lint menjalankan hook yang sama di CI pada setiap push ke main dan setiap pull request yang mengubah berkas Markdown, sehingga CI melakukan lint dengan versi yang dipatok oleh hook. Kebijakan tersebut menonaktifkan MD013 (panjang baris), MD033 (HTML inline), dan MD041 (heading di baris pertama). Kebijakan ini juga menonaktifkan MD038, karena akhiran label opsi kanonik (Recommended) mempertahankan spasi di depannya di dalam code span, dan MD060, karena tidak ada gaya kolom tabel yang menerima tabel bersel ringkas dengan baris pembatas |---| yang rapat, yang digunakan korpus. MD024 hanya memeriksa heading yang bersaudara, sehingga heading Added, Changed, Fixed, dan Security yang diulang pada setiap rilis di CHANGELOG.md lolos. Alasan setiap pilihan tercantum di samping hook tersebut. Hook ini melewati pohon fixture pengujian tests/fixtures/, tests/conformity/, tests/conformity-scenarios/fixtures/, dan tests/scripts/inject-header/fixtures/, yang byte-nya ditetapkan oleh pengujian. Hook ini juga melewati plugins/claude-code/, yang dihasilkan oleh python scripts/dev/assemble_plugin_tree.py dari src/apothem/: setiap langkah bernomor dalam sebuah perintah menjadi berkas tersendiri, sehingga daftar dalam berkas langkah dimulai dari nomor langkahnya. Sumber di src/apothem/ tetap di-lint, jadi temuan pada konten plugin diperbaiki di sana, lalu pohon plugin diregenerasi.

file-header-grep di src/apothem/conformity/file_header_grep.py memeriksa §5. Validator link-check di src/apothem/conformity/link_check.py memeriksa disiplin resolusi tautan §4 — validator ini me-resolve tautan relatif terhadap direktori berkas sumber, serta rute situs /docs/... (dan /<locale>/docs/...) terhadap himpunan halaman site/content/docs/, lalu menandai setiap tautan yang tidak mengarah ke halaman mana pun di disk. Keduanya adalah matcher per-Write yang bersifat advisori. Keduanya berjalan di hook pre-commit conformity-corpus-perwrite dan di job corpus-perwrite-gate milik alur kerja Conformity di .github/workflows/conformity.yml, dan di kedua tempat tersebut keduanya melaporkan temuan tanpa menggagalkan eksekusi. python -m apothem.conformity.gate --all . --strict pada job kualitas CI di .github/workflows/ci.yml hanya mencakup validator mandiri, sehingga tidak menjalankan satu pun dari keduanya.