easy-laporan-its

name	easy-laporan-its
description	Easy-to-use stack for generating ITS-format academic reports (laporan praktikum, telaah artikel, skripsi, tesis) using JSON → Jinja2 → Pandoc pipeline. Use when user mentions "laporan ITS", "laporan akademik", "buat skripsi", "academic report", "thesis", "pandoc", "jinja template", "structured json to docx", or any academic document generation task.

Easy Laporan ITS

Core Philosophy

Strict separation of concerns — never violate this:

Layer	Responsibility	Tool
Agent	Content only	JSON (filled)
Jinja2	Structure & layout	report.j2
Pandoc	Rendering to DOCX/PDF	pandoc CLI

🔬 If you are a Research / Content Agent: Read FOR_RESEARCH_AGENT.md instead of this file. It tells you exactly what to do without the pipeline details.

Absolute rules — never break these:

• ❌ NEVER generate a JSON file from scratch. Always copy a project template first.
• ❌ Never let the agent control heading levels, TOC structure, page numbers, or margins.
• ❌ Never produce .docx or .pdf directly — always go through the pipeline.
• ❌ python-docx is only for minor post-processing (e.g. centering images), not layout.
• ✅ The agent's only job is to fill content fields in a copied template.

---

Workflow — Follow This Exactly

Step 1: Copy the Right Project Template

Never start from a blank file. Pick the closest template from projects/:

Institution / Type	Template Path
Laporan ITS (default)	projects/laporan-its/report.json

How to copy (run this command):

Copy-Item projects/laporan-its/report.json my-report.json

Then edit only my-report.json. The original template must stay untouched.

---

Step 2: Fill the JSON Content Fields

Open the copied JSON. Fill every field marked TODO:. Leave fields you do not need as empty strings "".

Keys you must fill:

• title, subtitle — Cover page headline
• authors[] — Each member's name and NRP/NIM
• supervisors[] — Each supervisor's full name and title
• semester, year — Academic term
• chapters[].subsections[].content — The actual report prose (see formatting guide below)

Keys that are pre-filled and should NOT be changed (for ITS template):

• study_program, faculty, institution, logo_file

---

Step 3: Write Content (Formatting Guide)

Content fields accept Pandoc Markdown. Follow these rules precisely:

Paragraphs

Separate paragraphs with a blank line (\n\n). A single line break is NOT a paragraph break.

"content": "Paragraf pertama membahas latar belakang masalah secara umum.\n\nParagraf kedua menjelaskan kondisi spesifik yang melatarbelakangi proyek ini."

Bold and Italic

"content": "**DuckDB** merupakan OLAP engine yang berjalan secara *in-process*."

Numbered Lists

"content": "Rumusan masalah dalam penelitian ini:\n\n1. Bagaimana mengonstruksi pipeline ETL?\n2. Bagaimana mereduksi beban OLTP?\n3. Bagaimana merancang Star Schema?"

Bullet Lists

"content": "Teknologi yang digunakan:\n\n- **SQL Server**: repositori OLTP transaksi daring.\n- **DuckDB**: OLAP engine analitik in-process.\n- **Power BI**: platform visualisasi eksekutif."

Inline Code (nama fungsi, tabel, file, perintah)

"content": "Ekstraksi menggunakan filter `ModifiedDate > watermark` pada tabel `SalesOrderHeader`."

Tables

Use Pandoc pipe table syntax inside the content string:

"content": "Berikut hasil KPI utama:\n\n| Metrik | Nilai |\n| :--- | ---: |\n| Total Revenue | $85,49 juta |\n| Profit Margin | 35,05% |\n| YoY Growth | 8% |"

Do NOT use:

• Raw HTML (<br>, <b>, <table>)
• LaTeX commands (\textbf{}, \begin{table})
• Heading markers (#, ##) — headings are controlled by the template, not content
• Hardcoded page numbers or section references like "lihat halaman 5"

---

Step 4: Generate the Report

python scripts/generate-report.py --input my-report.json

Output will appear in generated/my-report.docx.

If the file is open in Word: close it first, or use a different output name with --output-dir.

---

Step 5: Update Daftar Isi in Word

The Table of Contents is a live Word field. After opening the DOCX:

1. Press Ctrl+A to select all.
2. Press F9 to update all fields.
3. Click "Update entire table" when prompted.

---

---

Iterative Editing

Reports are rarely right on the first pass. The JSON file is the source of truth — never edit the generated .md or .docx files directly.

The Edit Loop

my-report.json  →  edit content fields  →  re-run generator  →  review output

Edit your JSON, then regenerate:

python scripts/generate-report.py --input my-report.json

Versioning Convention

When making multiple passes, copy the JSON with a version suffix so every revision is reproducible:

Copy-Item my-report.json my-report_v2.json   # before editing
# ... edit my-report_v2.json ...
python scripts/generate-report.py --input my-report_v2.json

Use consistent suffixes: _v2, _v3, _final. This keeps both input and output paired in generated/ for easy comparison.

Comparing Versions

Use --verbose to dump the intermediate Markdown and diff across versions:

python scripts/generate-report.py --input my-report_v2.json --verbose
# → generated/my-report_v2.md

---

Deliver the Report

After generating the final version, copy the DOCX out of generated/ so the user can find it:

Copy-Item generated/my-report_final.docx .

Or to a specific location:

Copy-Item generated/my-report_final.docx C:\Users\user\Desktop\

The generated/ directory is gitignored — files there won't be committed. Copy the deliverable to a non-ignored location if it should live in the repo.

Project Templates Reference

projects/
└── laporan-its/
    └── report.json    ← Template laporan ITS (Sistem Informasi / FTEIC / ITS)

To add a new template for a different institution or report type, copy an existing project folder, rename it, and update the pre-filled institutional fields.

---

File Map

Need	File to edit
Write report content	Your copied my-report.json
Change cover / TOC layout	templates/report.j2
Change font / heading styles	styles/reference.docx
Change citation format	styles/apa.csl
Change build pipeline / options	scripts/generate-report.py
Add a new institution template	projects/<name>/report.json

See REFERENCE.md for the full JSON schema with all fields annotated.