Writeup Generation
Target: $ARGUMENTS
Generates structured academic/technical writeups with pandoc citation
support. IEEE [1] style by default.
Workflow
- Parse arguments - Extract topic and optional citation style
- Create directory -
docs/write-up/<topic>/ - Generate sections - Use template.md for structure and formats
- Setup bibliography - Create
references.bib(see template for BibTeX format) - Add YAML frontmatter - See template for required fields
- Run markdownlint -
make lint_md INPUT_FILES="docs/write-up/<topic>/*.md" - Generate PDF -
make pandoc_runwithBIBLIOGRAPHYvariable
Additional Resources
- For document structure, frontmatter, and BibTeX format, see template.md
- For planning academic research papers and technical writeups (Introduction → Literature Review → Methods → Results → Discussion → Conclusion), see research-paper-plan.md
Citation Styles
| Style | How | Notes |
|---|---|---|
| IEEE (default) | Bundled (scripts/writeup/citation-styles/ieee.csl) |
Numeric [1] |
| APA | Bundled (scripts/writeup/citation-styles/apa.csl) |
Author-date (Smith, 2024) |
| Chicago | Bundled (scripts/writeup/citation-styles/chicago-author-date.csl) |
Author-date (Smith 2024) |
| Vancouver | Bundled (scripts/writeup/citation-styles/vancouver.csl) |
Numeric (1) |
Additional CSL files are available from the Zotero Style Repository.
Pandoc Command
Generate PDF with citations:
dir=docs/write-up/<topic> && \
make pandoc_run \
INPUT_FILES="$$(printf '%s\036' $$dir/*.md)" \
OUTPUT_FILE="$$dir/output.pdf" \
BIBLIOGRAPHY="$$dir/references.bib"
With custom citation style:
dir=docs/write-up/<topic> && \
make pandoc_run \
INPUT_FILES="$$(printf '%s\036' $$dir/*.md)" \
OUTPUT_FILE="$$dir/output.pdf" \
BIBLIOGRAPHY="$$dir/references.bib" \
CSL="scripts/writeup/citation-styles/apa.csl"
Section Numbering (MANDATORY)
NEVER add manual section numbers to headings. Pandoc --number-sections
handles all numbering automatically.
- Wrong:
# 2. Projektvorstellung,## 2.1 Motivation,### 2.1.1 Details - Correct:
# Projektvorstellung,## Motivation,### Details
The NUMBER_SECTIONS parameter in the Makefile writeup recipe controls this.
Manual numbers in markdown headings conflict with pandoc auto-numbering and
produce duplicated numbers in the PDF output.
Quality Checks
Before completing:
- No manual section numbers - Headings must not contain
N.,N.N,N.N.Nprefixes - Markdownlint -
make lint_md INPUT_FILES="docs/write-up/<topic>/*.md" - Citation validation - Verify all
[@key]references exist in.bibfile - PDF generation - Run pandoc command above and confirm output
