mcpedia/.hermes/plans/hierarchical-folders.md

Phase 14 — Hierarchical Folder Structure

User: "gk ada bedanya, maksud saya inginnya itu bisa yg bertingkat seperti github yg memiliki folder dalam folder" Context: after the full dynamic-custom-fields overhaul (Phase 13), the user wants document URLs/content organized in nested folders like GitHub — writeups/ctf/defcon-quals-2024/pwn-100/... with subfolders under subfolders, not just one level deep.

Problem

The current URL scheme is /<section>/<slug> where slug can contain / (e.g. writeups/ctf/defcon-quals-2024/pwn-100-ret2win-alignment → /writeups/ctf/defcon-quals-2024/pwn-100-ret2win-alignment). This works for files but there are no folder-level index pages — navigating to /writeups/ctf/defcon-quals-2024/ returns 404 because Next.js catch-all [section]/[...slug]/page.tsx requires at least one slug segment beyond the section, and the sidebar only shows flat doc titles (no folder tree).

GitHub's model: github.com/org/repo/tree/main/path/to/folder/file — every folder has an index page (/path/to/folder/) listing its contents.

Solution

1. Folder Index Pages

Create apps/web/app/[section]/[...slug]/folder.tsx (or a parallel route). Actually — cleaner approach per Next.js App Router: the catch-all [section]/[...slug]/page.tsx handles both. Add logic: if the slug resolves to an actual markdown file → doc page (existing behavior). If the slug resolves to a directory (folder of docs) → render a folder index listing all docs whose path starts with that prefix.

Mechanism:

• Call listDocuments() to get all docs.
• The incoming URL path is {section}/{...slug}.
• Build the "folder prefix" = ${section}/${slug.join("/")}/ (with trailing /, or just ${section}/${slug.join("/")} if no slug segments).
• Filter docs whose doc.path starts with that prefix.
• If exactly one doc matches AND its path === prefix (trimmed .md) → it's a doc page (existing). If zero or multiple match and they all start with the prefix → it's a folder index.
• Edge: a folder with exactly one doc whose path matches exactly — still a doc page. A folder is when there are docs at prefix/sub/....

Better heuristic: A slug path is a "folder" if there exist docs whose path is prefix/deep/... (i.e., the slug is a parent of other doc paths, not a leaf itself). A slug is a "leaf doc" if path === prefix + ".md".

2. Sidebar Tree

Update Sidebar.tsx:

• listDocuments() already returns all docs with their full slug and path.
• Build a tree from the flat list: split each slug by /, create nested folder nodes.
• Render nested <ul> with indentation (already done via marginLeft based on depth).
• Folder nodes (collapsed/expanded) get a folder icon 📁 and a CSS class.
• Clicking a folder → navigates to the folder index page /{section}/{path}.
• Leaf doc nodes → link to /{doc.slug} (existing behavior).
• Group by the first segment after section too (e.g. ctf/defcon-quals-2024/ is a folder, then pwn-100-... are children).

Tree-building algorithm (from flat slugs):

For slug "writeups/ctf/defcon-quals-2024/pwn-100-ret2win-alignment":
  parts = ["writeups", "ctf", "defcon-quals-2024", "pwn-100-ret2win-alignment"]
  → tree: writeups → ctf → defcon-quals-2024 → pwn-100-ret2win-alignment (leaf)

3. DocForm / Folder Selection

Update DocForm.tsx:

• Add a "Parent folder" input (autocomplete or text) that shows existing folders for the selected section. The slug field already supports / but the user experience is better with folder picker.
• When creating, the slug becomes {parentFolder}/{slug} automatically.
• Show existing folder structure as <select> or tree picker.

4. Example Hierarchy

Create a real hierarchical structure to demonstrate:

writeups/
  ctf/
    defcon-quals-2024/
      pwn/
        pwn-100-ret2win-alignment.md
        pwn-200-bof-heap.md
      crypto/
        crypto-100-xor.md
        crypto-200-rsa.md
      template/
        writeup-template.md
      _index.md              ← folder index (optional intro)
    hackthebox/
      machine-name/
        walkthrough.md

For now, reorganize the existing Defcon writeup into proper subfolders + add a folder index page. The existing content/writeups/ctf/defcon-quals-2024/ is already a folder — just need the folder index route to work.

5. Route Changes

Current: [section]/[...slug]/page.tsx — catch-all requires ≥1 slug segment.

• /writeups → notFound() (no index for bare section unless we add one)
• /writeups/ctf → catch-all gets slug=["ctf"] → currently treated as a doc (looks up writeups/ctf doc, 404 if none)
• /writeups/ctf/defcon-quals-2024/ → catch-all slug=["ctf","defcon-quals-2024"]

Plan:

1. Add /writeups/page.tsx (section index) — lists top-level folders + root docs in that section. (Currently /docs/page.tsx exists but /writeups/page.tsx doesn't.)
2. In [section]/[...slug]/page.tsx: at the top of the page component, check if the slug path is a folder (has child docs). If so, render folder index instead of doc page.

Section index pages: Create [section]/page.tsx for all 4 sections, or a generic one. Currently only /docs/page.tsx exists. Add a shared SectionIndex component.

6. Files to Change

new:    apps/web/app/[section]/page.tsx               # generic section index (folder + doc listing)
mod:    apps/web/app/[section]/[...slug]/page.tsx     # add folder-index detection
mod:    apps/web/app/components/Sidebar.tsx            # tree from flat slugs
mod:    apps/web/app/components/DocForm.tsx            # parent folder picker
new:    content/writeups/ctf/defcon-quals-2024/_index.md  # folder intro (optional)
new:    content/writeups/ctf/_index.md                # CTF section intro
mod:    apps/web/app/docs/page.tsx                    # may need generic version

7. Verification

• /writeups → 200, shows folders: ctf/, template/
• /writeups/ctf → 200, folder index listing defcon-quals-2024/
• /writeups/ctf/defcon-quals-2024 → 200, folder index listing pwn-100-...
• /writeups/ctf/defcon-quals-2024/pwn-100-ret2win-alignment → 200, doc page
• Sidebar shows nested tree with folder icons
• DocForm parent folder picker works
• bun run test green, turbo run typecheck green
• Live verification via curl

Constraints

• User: "pastikan semua dinamis dan rapih untuk banyak situasi jadi tergantung user bukan hardcode" — folder detection must be content-driven, not config.
• No breaking existing flat slugs.
• Section icons/labels stay the same.