elemes/docs/13-content-sub-home.md

Sub Bab (sub-home.md) — Mengelompokkan Materi dalam Folder

Tanggal: 2026-08-13 Status: Aktif Lokasi kode: Backend services/lesson_service.py + routes/lessons.py

---

1. Latar Belakang

Konten LMS biasa ditulis sebagai file .md langsung di content/ dan didaftarkan satu per satu di content/home.md. Ketika materi bertambah banyak, daftar global menjadi panjang dan susah dirawat.

Fitur sub-home memungkinkan penulis menaruh sekelompok materi di dalam folder satu level di content/ (misal content/bab1/), lengkap dengan halaman bab sendiri (/bab/<folder>) dan daftar materi yang akurat untuk folder itu.

2. Cara Kerja

Struktur Folder

content/
├── home.md              # Halaman utama + daftar global (fallback)
├── hello_world.md       # Materi di root (tanpa sub bab)
└── bab1/                # Satu folder = satu sub bab (level satu)
    ├── sub-home.md      # "Halaman bab" — judul, intro, daftar materi
    ├── materi_a.md
    ├── materi_b.md
    └── materi_c.md

Format sub-home.md

# Judul Bab

Intro / deskripsi bab (opsional).

----Available_Lessons----
1. [Materi A](lesson/materi_a.md)
2. [Materi B](lesson/materi_b.md)
3. [Materi C](lesson/materi_c.md)

Aturan:

1. Baris pertama # Judul menjadi judul bab (ditampilkan di halaman /bab/<folder>).
2. Teks sebelum ----Available_Lessons---- menjadi intro bab (dirender markdown).
3. Bagian setelah ----Available_Lessons---- adalah daftar materi folder — format sama dengan home.md ([Judul](path.md), boleh dengan awalan lesson/).
4. sub-home.md tidak dihitung sebagai materi — di-skip oleh find_lesson_file() dan _parse_lesson_links(), jadi tidak muncul di daftar lesson global maupun sinkronisasi lesson registry.

Fallback

• Folder tanpa sub-home.md tidak memiliki halaman bab — materinya tetap diambil dari daftar global home.md (perilaku lama, tidak berubah).
• Lesson di dalam folder yang memiliki sub-home.md mendapat ordered_lessons (sidebar) dan navigasi prev/next scoped ke folder itu. Bila lesson belum dicantumkan di sub-home.md, fallback ke daftar global home.md.

3. API

GET /bab/<folder> (via proxy frontend: /api/bab/<folder>)

Mengembalikan JSON isi sub-home.md:

{
  "title": "Judul Bab",
  "intro_html": "<p>Intro bab...</p>",
  "lessons": [
    { "filename": "materi_a.md", "title": "Materi A", "description": "...", "path": "...", "prerequisite_titles": [] },
    { "filename": "materi_b.md", "title": "Materi B", "description": "...", "path": "...", "prerequisite_titles": [] }
  ],
  "folder": "bab1",
  "url": "/bab/bab1"
}

Respons 404 bila folder tidak ada atau tidak memiliki sub-home.md.

GET /lesson/<slug>.json

Bila lesson berada di folder yang memiliki sub-home.md, field ordered_lessons diisi daftar materi dari sub-home.md folder itu (bukan dari home.md global), dan field sub_home berisi metadata folder:

{
  "ordered_lessons": [ { "filename": "materi_a.md", "title": "Materi A" }, "..."],
  "sub_home": { "folder": "bab1", "url": "/bab/bab1", "title": "Judul Bab" }
}

Bila tidak ada sub-home.md, ordered_lessons memakai daftar global home.md dan sub_home bernilai null.

4. Cache

Parsing sub-home.md di-cache berbasis mtime: setiap kali file diubah, hasil parsing otomatis segar tanpa restart aplikasi (tidak memakai lru_cache yang bisa mengembalikan data basi). Perubahan pada sub-home.md juga meng-invalidate cache find_lesson_file() agar materi yang baru ditambahkan langsung terdeteksi.

5. Contoh Siap Pakai

Contoh lengkap ada di examples/content/:

• examples/content/dasar/sub-home.md
• examples/content/arduino/sub-home.md

6. FAQ

Q: Apakah sub bab bisa bersarang (folder di dalam folder)? Tidak. Fitur ini dirancang untuk folder satu level di dalam content/. Sub bab bertingkat di luar lingkup.

Q: Apakah materi di dalam folder harus didaftarkan juga di home.md? Tidak wajib. Materi folder cukup didaftarkan di sub-home.md folder tersebut. Lesson yang tidak ada di home.md tidak akan disinkronkan ke lesson registry (progress per-lesson di halaman guru mengikuti daftar home.md global).