| 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 headlineauthors[] — Each member's name and NRP/NIMsupervisors[] — Each supervisor's full name and titlesemester, year — Academic termchapters[].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:
- Press
Ctrl+A to select all.
- Press
F9 to update all fields.
- 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.
