Generating Writeup

Writeup Generation

Target: $ARGUMENTS

Generates structured academic/technical writeups as markdown with citation support. IEEE [1] style by default. PDF export via pandoc is optional.

Workflow

1. Parse arguments - Extract topic, template (default: project-report-IMRaD), and citation style
2. Create directory - docs/write-up/<topic>/
3. Copy template - Copy from templates/ to docs/write-up/<topic>/:
   • project-report-IMRaD — scientific/academic (Introduction, Methods, Results, Discussion)
   • technical-doc — software documentation (Overview, Architecture, API, Config, Deployment)
4. Fill sections - Replace TODO comments in each chapter file
5. Setup bibliography - Add entries to 09a_bibliography.bib
6. Run markdownlint - npx markdownlint-cli docs/write-up/<topic>/*.md
7. Generate PDF (optional) - If pandoc is available, run make pandoc_run

Additional Resources

• Templates: project-report-IMRaD/ | technical-doc/
• Setup help: make -f $CLAUDE_PLUGIN_ROOT/Makefile setup_pdf_converter HELP
• Pandoc help: make -f $CLAUDE_PLUGIN_ROOT/Makefile pandoc_run HELP=1

Citation Styles

Additional CSL files are available from the Zotero Style Repository.

PDF Export (Optional)

If pandoc and LaTeX are installed, generate PDF using the bundled Makefile:

dir=docs/write-up/<topic> && \
make -f $CLAUDE_PLUGIN_ROOT/Makefile pandoc_run \
  INPUT_FILES="$$(printf '%s\036' $$dir/*.md)" \
  OUTPUT_FILE="$$dir/output.pdf" \
  BIBLIOGRAPHY="$$dir/09a_bibliography.bib"

With custom citation style:

dir=docs/write-up/<topic> && \
make -f $CLAUDE_PLUGIN_ROOT/Makefile pandoc_run \
  INPUT_FILES="$$(printf '%s\036' $$dir/*.md)" \
  OUTPUT_FILE="$$dir/output.pdf" \
  BIBLIOGRAPHY="$$dir/09a_bibliography.bib" \
  CSL="$CLAUDE_PLUGIN_ROOT/scripts/writeup/citation-styles/apa.csl"

Full writeup build (content generation + PDF):

make -f $CLAUDE_PLUGIN_ROOT/Makefile writeup \
  WRITEUP_DIR=docs/write-up/<topic>

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

Manual numbers in markdown headings conflict with pandoc auto-numbering and produce duplicated numbers in the PDF output.

Quality Checks

Before completing:

1. No manual section numbers - Headings must not contain N., N.N, N.N.N prefixes
2. Markdownlint - npx markdownlint-cli docs/write-up/<topic>/*.md
3. Citation validation - Verify all [@key] references exist in .bib file
4. PDF generation (optional) - If pandoc available, run make pandoc_run

Further Reading

• Pandoc User's Guide
• Zotero Style Repository
• Citation Style Language Specification
• BibTeX Entry Types