This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
typst_reporter/docs/writing-reports.md

5.5 KiB

Writing reports

Reports are YAML files stored under reports/. The filename determines the PDF filename, while the YAML determines its content.

Top-level fields

Field Purpose Required
title Main report heading Recommended
id Report or ticket identifier No
organization Name displayed in the header No
subtitle Context below the title No
report_type Report purpose: technical or briefing Recommended
theme Visual theme: default, cic, or eridani No; defaults to default
status Overall workflow state No
severity Overall urgency No
metadata Key/value facts; must contain Date and Author Yes
summary Executive summary callout No
timeline Chronological event table No
findings Evidence and assessments No
sections Free-form structured content No
actions_title Custom heading for the action plan No
actions Ordered work items and commands No
closing Current state or handoff point No

Missing optional fields are simply omitted from the PDF. Compilation fails when the required metadata.Date or metadata.Author value is missing or empty and prints the YAML needed to fix it.

Theme

Select one of the built-in visual themes at the top level:

theme: cic
  • default — neutral, understated corporate styling.
  • cic — a sharper corporate space-operations/cyberpunk palette.
  • eridani — a rugged, grass-and-earth palette.

The default is used when theme is omitted. An unknown name stops compilation and lists the available themes. See Advanced setup to customize or add themes.

Report types

Classify reports by their purpose, not merely whether they are internal or external:

Type Use it for Typical content
technical Investigation, engineering review, and shift handoff Detailed evidence, commands, timelines, hypotheses, and operational precautions
briefing Sharing verified findings with customers, managers, or other stakeholders Concise impact, confirmed findings, decisions, ownership, and next steps
report_type: technical

A technical report may still be shared when appropriate, and a briefing may be internal. The distinction describes depth and purpose rather than access control. The renderer displays Technical report or Stakeholder briefing as a badge near the title.

Avoid putting secrets, credentials, personal data, or unnecessarily sensitive infrastructure details in either type. Classification does not provide security or redact content.

Status and severity

Typical workflow states are open, pending, confirmed, and resolved. Typical severity values are info, medium, high, and critical.

The renderer also recognizes warning, ok, and success when choosing badge and callout colors. Values are case-insensitive, but lowercase keeps YAML files consistent.

Metadata

Metadata accepts arbitrary labels and values:

metadata:
  Date: "2026-09-05"
  Author: "Your Name"
  Device: "DESKTOP-EXAMPLE"
  Owner: "Operations"
  Ticket: "INC-1234"

Quote dates and identifier-like values so YAML does not reinterpret them. Date and Author are required with exactly this capitalization.

Timeline and findings

timeline:
  - time: "09:15"
    event: "Alert received"
    notes: "Monitoring detected repeated storage timeouts."

findings:
  - title: "Storage controller timeout"
    severity: high
    status: confirmed
    evidence: >
      The system log contains three controller resets within ten minutes.      
    assessment: >
      The storage path is the leading cause and needs focused testing.      

Use evidence for observations and assessment for interpretation. Keeping them separate makes technical conclusions easier to review.

Free-form sections

Each item in sections has a title and a list of content blocks:

sections:
  - title: "Investigation notes"
    content:
      - type: text
        text: "A short paragraph."

      - type: bullets
        items:
          - "First observation"
          - "Second observation"

      - type: steps
        items:
          - "Collect logs"
          - "Reproduce the failure"

      - type: callout
        title: "Caution"
        kind: warning
        text: "Back up important data before destructive testing."

      - type: code
        text: "journalctl --since '30 minutes ago'"

      - type: subsection
        title: "Nested detail"
        content:
          - type: text
            text: "Subsections can contain the same block types."

Supported block types are text, bullets, steps, callout, code, and subsection. Unknown types render a warning instead of being silently discarded.

Actions

actions_title: "Next steps"
actions:
  - title: "Collect system logs"
    status: pending
    text: "Export the relevant events and attach them to the ticket."
    commands:
      - "journalctl --since today > system.log"
      - "dmesg > kernel.log"

commands is a list, so an action can contain zero, one, or several commands.

Authoring tips

  • Use > for prose that should wrap into one paragraph.
  • Quote Windows paths and values containing YAML punctuation.
  • Keep evidence factual and put conclusions in assessment.
  • Use metadata for short facts, not long explanations.
  • Render after editing to catch malformed YAML and layout problems early.

For complete files, continue to Examples and boilerplate.