laporan-generator 2.6.1

package/chapters/bab5-penutup.md

@@ -0,0 +1,27 @@
+# PENUTUP
+
+## Kesimpulan
+
+Berdasarkan perancangan, implementasi, dan serangkaian pengujian yang telah dilakukan pada proyek **Laporan Generator**, dapat ditarik beberapa kesimpulan utama:
+
+1. **Efektivitas Paradigma Pemisahan Konten dan Penyajian** --- Penerapan format teks ringan Markdown sebagai lapisan penulisan konten yang dipisahkan dari lapisan tata letak (*layout*) terbukti secara signifikan meningkatkan fokus penulis, mengeliminasi masalah pergeseran tata letak (*layout drift*), serta memudahkan kolaborasi tim melalui sistem kontrol versi Git.
+
+2. **Keunggulan Engine Typesetting Typst** --- Penggunaan Typst sebagai mesin kompilasi PDF utama berhasil memangkas ukuran dependensi sistem dari ~4.5 GB (distribusi TeX Live) menjadi hanya ~25 MB (binary mandiri Typst) dengan kecepatan kompilasi sub-detik, sembari tetap mempertahankan standar tipografi akademik profesional dan tata letak yang presisi.
+
+3. **Keberhasilan Solusi Multi-Pass DOCX** --- Pendekatan multi-pass yang menggabungkan filter Pandoc Lua (`docx.lua`), manipulasi struktur OpenXML (`finalize-docx.py`), dan sinkronisasi nomor halaman via LibreOffice headless (`docx-pagenum.py`) berhasil mewujudkan dokumen Microsoft Word resmi dengan pemisahan seksi yang tepat (sampul tanpa nomor, *front matter* bernomor Romawi *i, ii*, dan isi bab yang dimulai ulang dari angka Arab 1).
+
+4. **Fleksibilitas Sistem Preset Kampus dan Alat Bantu Otomasi** --- Kehadiran sistem preset deklaratif (`presets/*.yml`), didukung oleh pemindai pedoman PDF otomatis (`scan-preset.py`), linter validasi skema (`validate-preset.py`), serta antarmuka baris perintah terpadu (`./laporan`), memberikan kemudahan bagi sivitas akademika di berbagai universitas di Indonesia untuk menyesuaikan format laporan secara instan.
+
+5. **Keandalan dan Keterulangan Sistem (*Reproducibility*)** --- Dukungan konfigurasi Nix Flakes (`flake.nix`) dan kontainer Docker menjamin bahwa pipeline dapat dijalankan secara identik di seluruh sistem operasi pengembang (Linux, macOS, Windows) dengan tingkat kelulusan pengujian 100% pada 78 *test assertions*.
+
+## Saran
+
+Beberapa peluang pengembangan lanjutan yang direkomendasikan untuk meningkatkan fungsionalitas dan adopsi proyek ini di masa depan antara lain:
+
+1. **Pengembangan Antarmuka Web (Web-Based Interactive Generator)** --- Membangun antarmuka berbasis web atau aplikasi WebAssembly (Wasm) agar pengguna tanpa akses terminal atau baris perintah dapat menyunting dan mengunduh laporan langsung melalui peramban.
+
+2. **Ekspansi Basis Data Preset Perguruan Tinggi** --- Menambahkan koleksi preset resmi untuk universitas-universitas besar lainnya di Indonesia, seperti Universitas Diponegoro (UNDIP), Universitas Airlangga (UNAIR), Universitas Brawijaya (UB), Universitas Telkom (Tel-U), dan BINUS University.
+
+3. **Penyediaan Wrapper Baris Perintah PowerShell (`laporan.ps1`)** --- Mengembangkan skrip pembungkus PowerShell native guna menyempurnakan pengalaman pengembang (*developer experience*) bagi pengguna sistem operasi Windows murni tanpa ketergantungan pada WSL atau Git Bash.
+
+4. **Integrasi Ekstensi Editor (VS Code / Antigravity IDE Plugin)** --- Menyediakan plugin editor yang menyertakan fitur cuplikan kode (*snippets*), validasi sitasi BibTeX otomatis, dan pratinjau dokumen (*live preview*) langsung di dalam lingkungan pengembangan terintegrasi.

package/cover.md

@@ -0,0 +1,50 @@
+# KATA PENGANTAR {-}
+
+Puji syukur kehadirat Tuhan Yang Maha Esa atas segala rahmat dan karunia-Nya sehingga laporan yang berjudul **"Otomatisasi Pembuatan Dokumen Laporan Akademik menggunakan Pandoc, Typst, dan Markdown"** dapat diselesaikan dengan baik.
+
+Laporan ini disusun sebagai dokumentasi pipeline otomatisasi dokumen akademik yang dibangun menggunakan kombinasi teknologi Markdown, Pandoc, Typst, ImageMagick, dan Bash. Pipeline ini memungkinkan penulisan konten laporan dalam format Markdown yang sederhana, yang kemudian dikonversi menjadi PDF dengan format profesional melalui Pandoc dan Typst.
+
+Penulis menyadari bahwa laporan ini tidak dapat terselesaikan tanpa bantuan dari berbagai pihak. Oleh karena itu, penulis mengucapkan terima kasih kepada semua pihak yang telah memberikan dukungan dalam penyelesaian laporan ini.
+
+Penulis menyadari bahwa laporan ini masih jauh dari sempurna. Oleh karena itu, kritik dan saran yang membangun sangat diharapkan untuk perbaikan di masa mendatang. Semoga laporan ini dapat memberikan manfaat bagi pembaca dalam memahami konsep otomatisasi dokumen akademik.
+
+```{=typst}
+#v(0.8cm)
+#align(right)[
+  Agustus 2026
+
+  #v(1cm)
+  Tim Penyusun
+]
+#pagebreak()
+#outline(
+  title: [#align(center)[#text(size: 14pt, weight: "bold")[DAFTAR ISI]]],
+  depth: 3,
+)
+#context {
+  let imgs = query(figure.where(kind: image))
+  if imgs.len() > 0 {
+    pagebreak()
+    outline(
+      title: align(center)[#text(size: 14pt, weight: "bold")[DAFTAR GAMBAR]],
+      target: figure.where(kind: image),
+    )
+  }
+  let tbls = query(figure.where(kind: table))
+  if tbls.len() > 0 {
+    pagebreak()
+    outline(
+      title: align(center)[#text(size: 14pt, weight: "bold")[DAFTAR TABEL]],
+      target: figure.where(kind: table),
+    )
+  }
+}
+#pagebreak()
+#set page(numbering: "1")
+#counter(page).update(1)
+```
+
+```{=openxml}
+<w:p><w:pPr><w:jc w:val="right"/><w:spacing w:before="454"/></w:pPr><w:r><w:t>Agustus 2026</w:t></w:r></w:p>
+<w:p><w:pPr><w:jc w:val="right"/><w:spacing w:before="567"/></w:pPr><w:r><w:t>Tim Penyusun</w:t></w:r></w:p>
+```

package/docs/campus-guide.md

@@ -0,0 +1,120 @@
+# Panduan Preset & Kustomisasi Format Kampus
+
+Dokumen ini berisi panduan untuk menyesuaikan format laporan akademik sesuai dengan pedoman penulisan di berbagai perguruan tinggi di Indonesia menggunakan sistem **Preset Declarative** (`presets/*.yml`).
+
+---
+
+## 1. Menggunakan Preset Kampus
+
+Setiap perguruan tinggi memiliki aturan tata letak, margin, jenis huruf, dan gaya sampul tersendiri. Anda dapat memilih preset yang diinginkan melalui berkas `metadata.yml`:
+
+```yaml
+preset: "itb-ta"   # Ganti dengan ID preset kampus Anda
+```
+
+Atau gunakan bantuan CLI interaktif:
+```bash
+./laporan preset list                # Lihat semua preset yang tersedia
+./laporan preset show ui-skripsi      # Lihat rincian konfigurasi preset
+./laporan preset apply itb-ta        # Terapkan langsung ke metadata.yml
+```
+
+> **Kompatibilitas**: Field lama `margin_preset: "skripsi-4433"` atau `margin_preset: "standard"` tetap didukung penuh.
+
+---
+
+## 2. Daftar Preset Kampus Bawaan
+
+| ID Preset | Institusi / Format | Margin (Atas - Bawah - Kiri - Kanan) | Catatan Khusus |
+|---|---|---|---|
+| `standard` | Standar Modern | 2.0 cm - 3.0 cm - 2.5 cm - 2.5 cm | Format default tugas akhir, magang, praktikum |
+| `skripsi-4433` | Skripsi Tradisional | 4.0 cm - 3.0 cm - 4.0 cm - 3.0 cm | Hardcover jilid tebal margin kiri 4cm |
+| `ui-skripsi` | Universitas Indonesia (UI) | 2.5 cm - 2.5 cm - 2.5 cm - 2.5 cm | Sesuai Pedoman Karya Ilmiah UI |
+| `itb-ta` | Institut Teknologi Bandung (ITB) | 4.0 cm - 3.0 cm - 4.0 cm - 3.0 cm | Cover minimalis (tanpa dosen pembimbing di cover luar) |
+| `ugm-skripsi` | Universitas Gadjah Mada (UGM) | 4.0 cm - 3.0 cm - 4.0 cm - 3.0 cm | Full academic cover |
+| `its-skripsi` | Institut Teknologi Sepuluh Nopember (ITS) | 4.0 cm - 3.0 cm - 4.0 cm - 3.0 cm | Standard Tugas Akhir & Tesis ITS |
+
+---
+
+## 3. Contoh Konfigurasi Berbagai Kampus
+
+### A. Format Universitas Indonesia (UI)
+```yaml
+title: "IMPLEMENTASI DEEP LEARNING UNTUK DETEKSI PENYAKIT PADA CITRA MEDIS"
+subtitle: "LAPORAN TUGAS AKHIR"
+course: "Proyek Perangkat Lunak Lanjut"
+lecturer: "Prof. Dr. Ir. Dosen Pengampu, M.Sc."
+author:
+  - name: "Nama Mahasiswa"
+    nim: "2106012345"
+institution: "UNIVERSITAS INDONESIA"
+faculty: "FAKULTAS ILMU KOMPUTER"
+year: "2026"
+preset: "ui-skripsi"
+```
+
+### B. Format Institut Teknologi Bandung (ITB)
+```yaml
+title: "RANCANG BANGUN SISTEM KONTROL DAN MONITORING SMART GRID BERBASIS IOT"
+subtitle: "LAPORAN TUGAS AKHIR"
+course: "Sistem Tertanam"
+author:
+  - name: "Nama Mahasiswa"
+    nim: "13521001"
+institution: "INSTITUT TEKNOLOGI BANDUNG"
+faculty: "SEKOLAH TEKNIK ELEKTRO DAN INFORMATIKA"
+year: "2026"
+preset: "itb-ta"
+```
+
+### C. Format Universitas Gadjah Mada (UGM)
+```yaml
+title: "ANALISIS PERFORMA ARSITEKTUR MICROSERVICES PADA CLOUD COMPUTING"
+subtitle: "LAPORAN PRAKTIKUM LAPANGAN"
+course: "Rekayasa Perangkat Lunak"
+lecturer: "Dr. Dosen Pengampu, S.Kom., M.Cs."
+author:
+  - name: "Mahasiswa Satu"
+    nim: "21/475123/TK/52123"
+  - name: "Mahasiswa Dua"
+    nim: "21/475124/TK/52124"
+institution: "UNIVERSITAS GADJAH MADA"
+faculty: "FAKULTAS TEKNIK"
+year: "2026"
+preset: "ugm-skripsi"
+```
+
+---
+
+## 4. Mengganti Logo Kampus
+Cukup salin gambar logo resmi kampus Anda ke direktori utama dengan nama **`logo.jpg`** (atau format PNG yang dikonversi ke JPEG):
+```bash
+cp /path/ke/logo-kampus.png logo.jpg
+```
+Pipeline akan secara otomatis menyesuaikan ukuran dan memposisikannya secara proporsional di tengah halaman sampul sesuai konfigurasi `cover_logo_width` pada preset.
+
+---
+
+## 5. Memindai Otomatis Pedoman Kampus Baru (PDF Scanner)
+
+Jika kampus Anda belum tersedia di daftar preset bawaan, Anda dapat memindai berkas PDF Buku Pedoman Penulisan Skripsi / Tugas Akhir kampus Anda secara otomatis:
+
+```bash
+./laporan preset scan /path/ke/pedoman-penulisan-kampus.pdf
+```
+
+Sistem pemindai cerdas akan:
+1. Mengekstraksi teks dokumen dan mencari pasal format fisik/tata cara pengetikan.
+2. Mendeteksi margin (kiri, atas, kanan, bawah), jenis dan ukuran font, spasi baris, format penomoran bab/sub-bab, dan nama institusi.
+3. Menampilkan ringkasan temuan aturan format di terminal.
+4. Menyimpan konfigurasi otomatis ke berkas `presets/<preset-id>.yml`.
+
+Contoh pemindaian dengan opsi khusus:
+```bash
+./laporan preset scan pedoman-unpad.pdf --preset-id unpad-skripsi --name "Universitas Padjadjaran" --apply
+```
+
+---
+
+## 6. Membuat Preset Kustom Secara Manual
+Selain pemindaian otomatis, Anda juga dapat menulis berkas preset YAML baru secara manual di direktori `presets/`. Baca panduan lengkapnya di [docs/preset-schema.md](preset-schema.md).

package/docs/metadata-schema.md

@@ -0,0 +1,76 @@
+# Spesifikasi Skema Metadata (metadata.yml)
+
+File `metadata.yml` digunakan oleh Pandoc, template Typst (`template.typ`), dan filter DOCX (`docx.lua`) untuk mengisikan informasi sampul (cover page), judul laporan, identitas penyusun, dosen pengampu/pembimbing, serta abstrak laporan.
+
+---
+
+## Struktur File & Contoh Lengkap
+
+```yaml
+---
+title: "Otomatisasi Pembuatan Dokumen Laporan Akademik Menggunakan Pandoc, Typst, dan Markdown"
+subtitle: "Laporan Projek Akhir Pipeline Dokumentasi"
+author:
+  - name: "Ahmad Dahlan"
+    nim: "101234567"
+  - name: "Budi Santoso"
+    nim: "101234568"
+lecturer: "Dr. Ir. Hendra Wijaya, M.T."
+lecturer_label: "Dosen Pengampu:"   # Opsional: "Dosen Pembimbing:", "Pembimbing 1:", dll.
+course: "Pengolahan Citra Digital dan Pembelajaran Mesin"
+institution: "Universitas Gadjah Mada"
+faculty: "Departemen Teknik Elektro dan Teknologi Informasi"
+year: "2025/2026"
+date: "Juli 2026"
+abstract: |
+  Laporan ini membahas pipeline otomatisasi dokumen akademik
+  menggunakan Markdown, Pandoc, Typst, dan Bash. Pipeline ini
+  memungkinkan penulisan konten laporan dalam format Markdown
+  yang kemudian dikonversi menjadi PDF berkualitas percetakan
+  melalui Pandoc dan Typst serta berkas Microsoft Word (.docx).
+...
+```
+
+---
+
+## Penjelasan Field Metadata
+
+| Field | Tipe Data | Wajib? | Keterangan |
+|---|---|---|---|
+| `title` | String | **Ya** | Judul utama laporan (tampil tebal di halaman sampul). |
+| `subtitle` | String | Opsional | Sub-judul atau keterangan tambahan laporan. |
+| `author` | List of Objects | **Ya** | Daftar penulis. Setiap entri memiliki `name` dan `nim`. |
+| `author[].name` | String | **Ya** | Nama lengkap mahasiswa / penyusun. |
+| `author[].nim` | String | **Ya** | Nomor Induk Mahasiswa (NIM / NPM / NISN). |
+| `lecturer` | String | **Ya** | Nama lengkap dan gelar Dosen / Guru Pengampu / Pembimbing. |
+| `lecturer_label` | String | Opsional | Label peran dosen (default: `"Dosen Pengampu:"`, bisa `"Dosen Pembimbing:"`). |
+| `course` | String | **Ya** | Nama Mata Kuliah atau Mata Pelajaran. |
+| `institution` | String | **Ya** | Nama Universitas, Institut, Politeknik, atau Sekolah. |
+| `faculty` | String | **Ya** | Nama Fakultas, Departemen, atau Program Studi. |
+| `year` | String | **Ya** | Tahun Ajaran (contoh: `2025/2026`). |
+| `date` | String | Opsional | Bulan dan Tahun pembuatan (contoh: `Juli 2026`). |
+| `abstract` | Multiline String | Opsional | Ringkasan/Abstrak laporan dalam Bahasa Indonesia. |
+
+---
+
+## Dukungan Multi-Author (Individu / Kelompok)
+
+Skema ini mendukung jumlah penulis dinamis (1 orang hingga banyak orang):
+
+* **Single Author (Individu)**:
+  ```yaml
+  author:
+    - name: "Budi Santoso"
+      nim: "101234567"
+  ```
+
+* **Multi Author (Kelompok)**:
+  ```yaml
+  author:
+    - name: "Mahasiswa A"
+      nim: "101234561"
+    - name: "Mahasiswa B"
+      nim: "101234562"
+    - name: "Mahasiswa C"
+      nim: "101234563"
+  ```

package/docs/preset-schema.md

@@ -0,0 +1,79 @@
+# Spesifikasi Skema Preset Format Kampus (Preset Schema)
+
+File preset format kampus disimpan di dalam direktori `presets/<preset-id>.yml`. File ini mendefinisikan aturan tata letak visual (*page geometry*), tipografi, gaya penomoran heading, serta susunan sampul (*cover page*) untuk dokumen PDF (Typst) dan Word (DOCX).
+
+---
+
+## Contoh Lengkap Skema Preset
+
+```yaml
+# presets/itb-ta.yml
+preset_id: "itb-ta"
+name: "Institut Teknologi Bandung (ITB)"
+description: "Format Tugas Akhir / Tesis sesuai Pedoman Penulisan Karya Ilmiah ITB."
+
+# 1. Geometri & Margin Halaman
+margin_top: 4cm
+margin_bottom: 3cm
+margin_left: 4cm
+margin_right: 3cm
+
+# 2. Tipografi & Spasi
+font_family: "Libertinus Serif"   # Font utama (Times New Roman standard)
+font_size: 12pt                  # Ukuran teks isi
+line_spacing: 0.75em             # Spasi antar baris (1.5 spasi)
+first_line_indent: 1.25cm        # Indentasi awal paragraf
+
+# 3. Penomoran Heading
+heading_chapter_prefix: "BAB "   # Prefix bab ("BAB ")
+heading_chapter_num_format: "roman" # Angka Romawi ("roman") atau Arab ("arabic")
+heading_sub_dot: true            # true: "1.1." | false: "1.1"
+heading_subsub_dot: false        # true: "1.1.1." | false: "1.1.1"
+
+# 4. Pengaturan Halaman Sampul (Cover)
+cover_show_lecturer: false       # true: tampilkan dosen | false: sembunyikan
+cover_hide_lecturer: true        # Flag pembantu untuk parser
+cover_logo_width: 4.5cm          # Lebar logo di sampul depan
+```
+
+---
+
+## Daftar Field & Tipe Data
+
+| Kategori | Field | Tipe Data | Nilai Bawaan (Default) | Keterangan |
+|---|---|---|---|---|
+| **Identitas** | `preset_id` | String | *Nama file tanpa .yml* | ID unik preset (contoh: `ui-skripsi`). |
+| | `name` | String | - | Nama lengkap format / institusi. |
+| | `description` | String | - | Penjelasan singkat karakteristik preset. |
+| **Margin** | `margin_top` | String / Satuan | `2cm` | Jarak batas atas halaman. |
+| | `margin_bottom` | String / Satuan | `3cm` | Jarak batas bawah halaman. |
+| | `margin_left` | String / Satuan | `2.5cm` | Jarak batas kiri halaman (misal: `4cm` untuk jilid). |
+| | `margin_right` | String / Satuan | `2.5cm` | Jarak batas kanan halaman. |
+| **Tipografi** | `font_family` | String | `Libertinus Serif` | Keluarga font dokumen (TNR standard Typst). |
+| | `font_size` | String / pt | `12pt` | Ukuran font teks isi. |
+| | `line_spacing` | String / em | `0.75em` | Jarak leading baris (0.75em = setara 1.5 line). |
+| | `first_line_indent` | String / cm | `1.25cm` | Lebar indentasi baris pertama paragraf. |
+| **Heading** | `heading_chapter_prefix` | String | `BAB ` | Awalan judul bab level 1. |
+| | `heading_sub_dot` | Boolean | `true` | Apakah nomor sub-bab diakhiri titik (`1.1.` vs `1.1`). |
+| | `heading_subsub_dot` | Boolean | `false` | Apakah nomor sub-sub-bab diakhiri titik (`1.1.1`). |
+| **Cover** | `cover_show_lecturer` | Boolean | `true` | Tampilkan blok Dosen Pengampu di cover depan. |
+| | `cover_logo_width` | String / cm | `4cm` | Lebar visual gambar logo di halaman cover. |
+
+---
+
+## Cara Membuat Preset Kampus Baru
+
+1. Buat berkas baru di direktori `presets/`, misalnya `presets/its-skripsi.yml`.
+2. Isi nilai sesuai buku pedoman kampus Anda.
+3. Terapkan preset pada dokumen dengan menambahkan field `preset` di `metadata.yml`:
+   ```yaml
+   preset: "its-skripsi"
+   ```
+   Atau gunakan perintah CLI helper:
+   ```bash
+   ./laporan preset apply its-skripsi
+   ```
+4. Jalankan kompilasi:
+   ```bash
+   ./laporan build
+   ```

package/docs/syntax-cheatsheet.md

@@ -0,0 +1,122 @@
+# Cheatsheet Sintaks Markdown Akademik
+
+Panduan referensi cepat sintaks Markdown yang kompatibel dan teruji untuk pipeline **Laporan Generator** (Typst PDF dan Microsoft Word DOCX).
+
+---
+
+## 1. Sitasi & Bibliografi (BibTeX APA)
+
+Daftar pustaka dikelola melalui `references.bib` dan format APA melalui `apa.csl`.
+
+| Sintaks Markdown | Hasil Tipografi | Keterangan |
+|---|---|---|
+| `[@knuth1984texbook]` | (Knuth, 1984) | Sitasi tanda kurung standar |
+| `@knuth1984texbook menyatakan bahwa...` | Knuth (1984) menyatakan bahwa... | Sitasi naratif dalam kalimat |
+| `[-@knuth1984texbook]` | (1984) | Hanya tahun penerbitan |
+| `[@apa2020manual, hal. 45]` | (American Psychological Association, 2020, hal. 45) | Sitasi dengan nomor halaman |
+| `[@apa2020manual; @pandoc2024]` | (American Psychological Association, 2020; Pandoc, 2024) | Multi-sitasi sekaligus |
+
+---
+
+## 2. Struktur Heading & Penomoran Bab
+
+Gunakan heading Markdown tanpa menyisipkan angka manual. Engine Typst dan Lua filter DOCX akan menomori sub-bab secara otomatis:
+
+```markdown
+# PENDAHULUAN
+Heading Level 1 akan menjadi "BAB I PENDAHULUAN" secara otomatis.
+
+## Latar Belakang
+Heading Level 2 akan menjadi "1.1 Latar Belakang".
+
+### Identifikasi Masalah
+Heading Level 3 akan menjadi "1.1.1 Identifikasi Masalah".
+
+# KATA PENGANTAR {-}
+Gunakan atribut `{-}` atau `{.unnumbered}` untuk bagian front-matter tanpa nomor bab.
+```
+
+---
+
+## 3. Gambar & Diagram
+
+Letakkan berkas gambar di dalam folder `gambar/`:
+
+```markdown
+![Arsitektur Sistem Multi-Engine](gambar/arsitektur.png){#fig:arsitektur width=80%}
+```
+
+* **Penomoran Otomatis**: Menjadi `Gambar 1.1: Arsitektur Sistem Multi-Engine` (indeks bab otomatis).
+* **Format yang Didukung**: `.png`, `.jpg`, `.jpeg`, `.webp`.
+* **Transparansi Alpha**: Script `build.sh` otomatis menormalkan saluran alpha PNG agar optimal di Typst.
+
+---
+
+## 4. Tabel Formal Akademik
+
+Gunakan format Pipe Table standar Pandoc:
+
+```markdown
+: Ringkasan Pengujian Kompatibilitas {#tbl:pengujian}
+
+| Platform | Versi Minimum | Status Dukungan |
+|:---|:---:|:---|
+| Linux (Ubuntu/Debian) | 20.04 LTS | Didukung Penuh (Nix / Native) |
+| macOS | Monterey 12+ | Didukung Penuh (Apple Silicon & Intel) |
+| Windows | 10 / 11 | Didukung Penuh (PowerShell native) |
+```
+
+* Judul tabel diletakkan di atas dengan awalan titik dua `:`.
+* Menjadi `Tabel 1.1: Ringkasan Pengujian Kompatibilitas` secara otomatis.
+
+---
+
+## 5. Persamaan Matematika (LaTeX Math)
+
+* **Persamaan Inline**:
+  ```markdown
+  Nilai fungsi aktivasi dihitung dengan formula $f(x) = \frac{1}{1 + e^{-x}}$.
+  ```
+* **Persamaan Blok (Display Math)**:
+  ```markdown
+  $$
+  MSE = \frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)^2
+  $$
+  ```
+  Persamaan blok secara otomatis diberi nomor indeks bab, misalnya `(1.1)`.
+
+---
+
+## 6. Blok Kode & Listing
+
+```markdown
+```python
+def hitung_akurasi(y_true, y_pred):
+    return sum(t == p for t, p in zip(y_true, y_pred)) / len(y_true)
+```
+```
+
+Typst akan membungkus blok kode dalam background abu-abu terang dengan font `DejaVu Sans Mono`.
+
+---
+
+## 7. Catatan Kaki & Kutipan Langsung
+
+* **Kutipan Blok (Blockquote)**:
+  ```markdown
+  > "Rekayasa perangkat lunak bukan sekadar menulis kode, melainkan membangun sistem yang dapat diandalkan dan dipelihara dalam jangka panjang."
+  ```
+* **Catatan Kaki (*Footnotes*)**:
+  ```markdown
+  Laporan ini menggunakan Pandoc[^pandoc_note] sebagai compiler dokumen universal.
+
+  [^pandoc_note]: Pandoc dikembangkan oleh John MacFarlane dan mendukung lebih dari 40 format dokumen.
+  ```
+
+---
+
+## 8. Tips Kompatibilitas Lintas Engine
+
+1. **Hindari Karakter Box-Drawing**: Jangan menggunakan karakter seperti `├──`, `└──`, atau `│` di dalam teks biasa; gunakan list Markdown (`-` atau `*`) atau blok kode monospace.
+2. **Jangan Mengetik Angka Bab Manual**: Jangan menulis `## 1.1 Latar Belakang` karena akan menghasilkan penomoran ganda `1.1 1.1 Latar Belakang`.
+3. **Nama File Gambar Tanpa Spasi**: Gunakan tanda hubung (`diagram-alur.png`) alih-alih spasi (`diagram alur.png`).

package/docs/template-guide.md

@@ -0,0 +1,100 @@
+# Panduan Arsitektur Template Typst (template.typ)
+
+File `template.typ` merupakan jantung dari pemformatan visual PDF pada **Laporan Generator**. Template ini dirancang untuk memenuhi standar penyusunan laporan akademik resmi di Indonesia, dan dikompilasi dengan **Typst** sebagai engine typesetting.
+
+> **Catatan**: Pipeline utama sepenuhnya menggunakan **Typst** (`template.typ`). Template LaTeX lama diarsipkan pada branch `legacy/latex-engine`.
+
+---
+
+## Desain Arsitektur & Pemilihan Font
+
+### 1. Pemilihan Font (Libertinus Serif)
+* Standardisasi karya ilmiah di Indonesia mewajibkan penggunaan font tipe *Times New Roman* 12pt.
+* Untuk menjamin portabilitas kompilasi cross-platform tanpa dependensi font eksternal, template menggunakan **Libertinus Serif** (`Libertinus Serif`) yang sudah dibundel langsung di dalam binary Typst.
+* Blok kode menggunakan **DejaVu Sans Mono** (juga font bawaan Typst).
+
+### 2. Pengaturan Margin & Spacing
+```typst
+#set page(
+  paper: "a4",
+  margin: (top: 2cm, bottom: 3cm, left: 2.5cm, right: 2.5cm),
+)
+#set text(font: "Libertinus Serif", size: 12pt)
+#set par(justify: true, leading: 1.5em)
+```
+* Margin Kiri & Kanan: 2.5 cm
+* Margin Atas: 2.0 cm
+* Margin Bawah: 3.0 cm
+* Spasi Antar Baris: 1.5 spasi (*one half spacing*)
+* Paragraf rata kanan-kiri (*justify*)
+
+---
+
+## Penomoran Bab dan Halaman
+
+### 1. Format Bab & Heading
+```typst
+#set heading(numbering: (..ns) => {
+  if ns.len() == 1 {
+    "BAB " + numbering("I", ns.at(0)) + linebreak()
+  } else if ns.len() == 2 {
+    numbering("1.1", ..ns)
+  } else {
+    numbering("1.1.1", ..ns)
+  }
+})
+```
+* **Bab**: Diformat dengan Angka Romawi (`BAB I`, `BAB II`, `BAB III`, dst). Angka Romawi dan judul dipisahkan oleh *line break*.
+* **Sub-bab**: Diformat dengan Angka Arab (`1.1`, `1.2`, `2.1`).
+* **Sub-sub-bab**: Diformat dengan Angka Arab 3 tingkat (`1.1.1`, `1.1.2`).
+* **Heading tanpa nomor** (Kata Pengantar, Daftar Isi, Daftar Pustaka): menggunakan `{-}` di Markdown yang diterjemahkan Pandoc menjadi `#heading(level: 1, numbering: none)`.
+
+> **Catatan**: Jangan menulis pola `"BAB I"` langsung sebagai format string `numbering(...)`. Typst menginterpretasikan rangkaian huruf `BAB` sebagai pola huruf dan memotong angka Romawinya. Selalu concat literal secara manual: `"BAB " + numbering("I", n)`.
+
+### 2. Penomoran Halaman (frontmatter vs mainmatter)
+* **Bagian Depan** (Kata Pengantar, Daftar Isi): Menggunakan penomoran Romawi kapital (`I`, `II`, `III`) di bagian tengah bawah. Diatur di `cover.md`:
+  ```typst
+  #set page(numbering: "I")
+  ```
+* **Bagian Utama** (BAB I hingga BAB V): Menggunakan penomoran Angka Arab (`1`, `2`, `3`) berurutan, di-reset ulang:
+  ```typst
+  #set page(numbering: "1")
+  #counter(page).update(1)
+  ```
+
+---
+
+## Halaman Sampul (Cover)
+
+Bagian sampul dirender dari metadata `metadata.yml` dengan variabel: `title`, `subtitle`, `course`, `lecturer`, `authors`, `institution`, `logo`, `year`.
+
+```typst
+#block(
+  width: 100%,
+  align(center)[
+    #image(logo, width: 4cm)
+    ...
+  ]
+)
+```
+
+---
+
+## Pemrosesan Elemen Konten
+
+### 1. Tabel
+```typst
+#show table: set stroke(0.75pt)
+#show table.header: set text(weight: "bold")
+```
+* Header tabel dicetak tebal, garis tabel 0.75pt.
+
+### 2. Gambar
+* Caption gambar dirender di bawah gambar (`#show figure: set figure.caption(position: bottom)`).
+* Gambar diproses oleh ImageMagick di `build.sh` (alpha channel dihapus) sebelum dikompilasi.
+
+### 3. Blok Kode
+```typst
+#show raw: set text(font: "DejaVu Sans Mono", size: 9pt)
+```
+* Blok kode menggunakan font monospaced 9pt dengan latar abu-abu muda (`#show raw: set block(fill: luma(240))`).

package/docs/troubleshooting.md

@@ -0,0 +1,105 @@
+# Panduan Penanganan Masalah (Troubleshooting)
+
+Dokumen ini berisi daftar masalah umum, kode kesalahan, dan solusi langkah-demi-langkah saat menjalankan **Laporan Generator**.
+
+---
+
+## 1. ImageMagick Security Policy Error
+
+### Gejala Error:
+```text
+convert-im6.q16: attempt to perform an operation not allowed by the security policy 'PDF'
+```
+
+### Penyebab:
+Kebijakan keamanan default ImageMagick pada beberapa distribusi Linux (seperti Ubuntu/Debian) membatasi pemrosesan berkas PDF/PNG untuk mencegah kerentanan keamanan.
+
+### Solusi:
+1. Buka file kebijakan ImageMagick dengan hak akses sudo:
+   ```bash
+   sudo nano /etc/ImageMagick-6/policy.xml
+   # atau untuk ImageMagick 7:
+   sudo nano /etc/ImageMagick-7/policy.xml
+   ```
+2. Cari baris berikut:
+   ```xml
+   <policy domain="coder" rights="none" pattern="PDF" />
+   ```
+3. Ubah `rights="none"` menjadi `rights="read|write"`:
+   ```xml
+   <policy domain="coder" rights="read|write" pattern="PDF" />
+   ```
+4. Simpan file (`Ctrl+O`, `Enter`) lalu keluar (`Ctrl+X`).
+
+---
+
+## 2. Font Tidak Ditemukan (Missing Font)
+
+### Gejala Error:
+```text
+warning: font 'Nimbus Serif' not found, falling back to default
+warning: failed to resolve font 'Times New Roman'
+```
+
+### Penyebab:
+Font yang disebutkan di dalam `template.typ` tidak tersedia. Typst hanya memakai font yang dibundel di binary-nya (termasuk Libertinus Serif dan DejaVu Sans Mono) plus font yang terinstall di sistem.
+
+### Solusi:
+1. Gunakan font bawaan Typst: `Libertinus Serif`, `DejaVu Sans Mono`, atau `New Computer Modern`.
+2. Jika ingin font sistem lain, pastikan font tersebut sudah terinstall di OS/container.
+3. Cek daftar font yang tersedia:
+   ```bash
+   typst fonts
+   ```
+
+---
+
+## 3. Syntax Error Raw Typst di cover.md
+
+### Gejala Error:
+```text
+error: expected `)`, found `]`
+  ┌─ cover.md:5:1
+```
+
+### Penyebab:
+Blok raw Typst di dalam `cover.md` (diapit ``` ```typst ```) memiliki kesalahan sintaks. Contoh yang sering terjadi: `block(align: center)` (tidak valid di Typst, gunakan `align(center)[block(...)]`) atau `ns.first()` (dihapus sejak Typst 0.13, gunakan `ns.at(0)`).
+
+### Solusi:
+Periksa pesan error Typst yang menyebutkan posisi baris, lalu perbaiki blok raw di `cover.md` atau konstruksi template di `template.typ`.
+
+---
+
+## 4. Citasi "Undefined Reference"
+
+### Gejala Error:
+```text
+[WARNING] Citeproc: citation 'he2016deep' not found
+```
+
+### Penyebab:
+Di dalam Markdown, sintaks sitasi tidak dikenali atau citekey tidak ada di `references.bib`.
+
+### Solusi:
+Gunakan sintaks sitasi Pandoc `[@citekey]` atau `@citekey` di file Markdown:
+- **Salah**: `Menurut \cite{he2016deep}...`
+- **Benar**: `Menurut [@he2016deep]...`
+
+---
+
+## 5. Permission Denied pada Laporan.pdf (Docker Volume)
+
+### Gejala Error:
+```text
+cannot create Laporan.pdf: Permission denied
+```
+
+### Penyebab:
+Container Docker dijalankan sebagai user `root` sehingga menghalangi user lokal untuk mengubah atau menghapus file output.
+
+### Solusi:
+Gunakan perintah `docker compose` yang sudah dikonfigurasi dengan variabel `UID/GID` lokal:
+```bash
+docker compose run --rm laporan-generator
+```
+*(File `docker-compose.yml` pada project ini secara otomatis memetakan `user: "${UID:-1000}:${GID:-1000}"`)*.