Helper Markdown dan Daftar Isi

src/utils/markdown.ts menyimpan tiga helper yang mengubah data kategori menjadi markdown: translate, markdownBuilder, dan generateToc. Ketiganya bekerja berurutan di dalam loop penulisan README di src/build.ts:96-103¹. markdownBuilder mengisi blok API START/API END lebih dulu, lalu generateToc membaca result yang sudah berisi tabel beserta heading kategori. Urutan itulah sebabnya judul kategori hasil build ikut masuk ke daftar isi.

graph TD
  V["vocabularies.json"] --> T["translate(key, language)"]
  C["CategoryType dari data JSON"] --> M["markdownBuilder(categories, language)"]
  T --> M
  M --> TBL["tabel Markdown per kategori"]
  TBL --> RM["README berisi heading tingkat tiga"]
  RM --> G["generateToc(markdown)"]
  G --> TOC["daftar isi berindentasi"]
  style V fill:#336791,color:#fff
  style T fill:#8b5cf6,color:#fff
  style M fill:#f59e0b,color:#000
  style G fill:#8b5cf6,color:#fff
  style TBL fill:#2d7d46,color:#fff
  style TOC fill:#2d7d46,color:#fff
%% fig: Pemetaan helper markdown ke keluarannya
%% desc: translate memasok label kolom, markdownBuilder menghasilkan tabel per kategori, lalu generateToc membaca hasil build dan menurunkan daftar isi.

translate membaca label dari kamus

translate(key, language) mengembalikan vocabularies[language][key], dan hanya jatuh ke string 'Unknown' ketika key tidak ditemukan src/utils/markdown.ts:4-6². Kamusnya ada di src/data/vocabularies.json:1-18³ dan hanya memuat dua bahasa, id dan en, masing-masing dengan enam key yang sama persis.

⚠️ Fallback 'Unknown' hanya menutup key yang hilang. Indeks [language] dievaluasi lebih dulu, sehingga kode bahasa di luar id dan en melempar TypeError sebelum fallback sempat terpakai src/utils/markdown.ts:4-6². Pemilihan nilai language dibahas di Dukungan Multi-Bahasa.

markdownBuilder menyusun satu tabel per kategori

Fungsi ini menerima CategoryType[] — bentuknya ada di src/types.ts:1-13⁴ — beserta sebuah language, lalu mengembalikan satu string markdown src/utils/markdown.ts:8-33⁵. Untuk setiap kategori ia menulis heading ### ${category.categoryName}, baris header enam kolom, dan baris pemisah | - | - | - | - | - | - | src/utils/markdown.ts:11-17⁶. Enam label header diambil lewat translate, sehingga urutan kolom selalu apiName, developer, documentation, status, description, dan authentication src/utils/markdown.ts:11-17⁶.

Baris data dibangun di src/utils/markdown.ts:19-27⁷. Nama pengembang dibungkus tautan hanya bila api.developer.profileUrl terisi; kalau tidak, api.developer.name ditulis apa adanya. Kolom dokumentasi selalu menjadi tautan [Link](...), kolom status berisi ✅ atau ❎ dari api.status, dan kolom autentikasi memakai api.authentication dengan fallback false di dalam backtick ketika nilainya kosong.

Setiap kategori ditutup dengan baris kosong, dan hasil akhirnya di-trim() sebelum disisipkan src/utils/markdown.ts:8-33⁵. Pengurutan kategori dan API terjadi sebelum helper ini dipanggil, di dalam Pipeline Build Markdown.

generateToc menurunkan heading menjadi daftar isi

generateToc(markdown) didefinisikan di src/utils/markdown.ts:35-57⁸. Ia memindai seluruh teks dengan regex /^(#{1,6})\s+(.+)$/gm dan mengumpulkan pasangan { level, text }, dengan level diambil dari panjang match[1] src/utils/markdown.ts:36-45⁹. Tidak ada pemeriksaan pagar kode, jadi baris berawalan # di dalam blok kode juga ikut terkumpul.

Setiap heading kemudian menjadi satu baris - [teks](#anchor) dengan indentasi dua spasi per level src/utils/markdown.ts:47-56¹⁰. Anchor diturunkan dengan toLowerCase() lalu replace(/\s+/g, '-') src/utils/markdown.ts:50-52¹¹.

graph LR
  H["teks heading dari grup kedua"] --> LOW["toLowerCase"]
  LOW --> DASH["spasi menjadi tanda hubung"]
  DASH --> ANC["anchor di dalam tanda kurung"]
  LV["level dari grup pertama"] --> IND["indentasi dua spasi per level"]
  IND --> LINE["satu baris daftar isi"]
  ANC --> LINE
  style H fill:#8b5cf6,color:#fff
  style ANC fill:#f59e0b,color:#000
  style LINE fill:#2d7d46,color:#fff
%% fig: Penurunan satu baris daftar isi
%% desc: Teks heading diubah menjadi anchor, level heading menentukan indentasi, lalu keduanya digabung menjadi satu baris daftar isi.

⚠️ Anchor hanya menurunkan huruf dan mengganti spasi dengan tanda hubung. Tanda baca dibiarkan, jadi heading seperti Daftar API (Publik) menghasilkan #daftar-api-(publik) src/utils/markdown.ts:50-52¹¹. Anchor semacam itu tidak sama dengan anchor yang dibuat GitHub untuk heading yang sama.

Keluaran nyatanya bisa dilihat di README.md:13-42¹². Di sana ## Daftar API muncul sebagai baris berindentasi dua spasi, ### E-Commerce berindentasi empat spasi, dan ## Daftar Isi ikut terdaftar sebagai bagian dari daftar isi itu sendiri.

Ketiga helper ini hanya bekerja pada string: tidak ada akses berkas maupun jaringan di dalam src/utils/markdown.ts:35-57⁸ maupun fungsi markdownBuilder. Pembacaan data JSON dan penulisan README berada di Pipeline Build Markdown, sedangkan helper berkas dan filter blacklist dibahas di Helper Berkas dan Filter Blacklist.