121 lines
3.5 KiB
Markdown
121 lines
3.5 KiB
Markdown
# Beffroi Reports
|
|
|
|
Create consistent technical PDF reports from readable, version-controlled YAML.
|
|
Typst handles the layout, while each report remains easy to edit, review, and
|
|
diff in Git.
|
|
|
|
## Quick overview
|
|
|
|
### Requirements
|
|
|
|
- [Typst](https://typst.app/) available as `typst`
|
|
- Bash and standard Unix command-line utilities
|
|
|
|
No additional Typst packages are required.
|
|
|
|
### Create and render a report
|
|
|
|
1. Copy an existing file in `reports/`, or start with the
|
|
[minimal boilerplate](docs/examples.md#minimal-report).
|
|
2. Edit the YAML content.
|
|
3. Render it:
|
|
|
|
```bash
|
|
./render.sh reports/my-report.yaml
|
|
```
|
|
|
|
The PDF is written to `build/my-report.pdf`. To render every report recursively:
|
|
|
|
```bash
|
|
./render.sh --all
|
|
```
|
|
|
|
Set the report's purpose explicitly:
|
|
|
|
```yaml
|
|
report_type: technical # Investigation, engineering review, or handoff
|
|
# report_type: briefing # Concise findings for stakeholders
|
|
```
|
|
|
|
See [Report types](docs/writing-reports.md#report-types) for the distinction.
|
|
|
|
Every report must include an author and date, and may select a theme:
|
|
|
|
```yaml
|
|
theme: default # Also available: cic, eridani
|
|
|
|
metadata:
|
|
Date: "2026-09-05"
|
|
Author: "Your Name"
|
|
```
|
|
|
|
Compilation stops with an actionable error if `metadata.Date` or
|
|
`metadata.Author` is absent or empty.
|
|
|
|
### Generate a Windows diagnostics assessment
|
|
|
|
Convert a Full WinDiagnostics text dump into a concise, exception-focused PDF:
|
|
|
|
```bash
|
|
./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" cic
|
|
```
|
|
|
|
The theme argument is optional and defaults to `default`. Render every `.json`
|
|
dump under `diagnostics/` recursively with:
|
|
|
|
```bash
|
|
./render-diagnostics.sh --all "Your Name"
|
|
```
|
|
|
|
The result is written under `build/diagnostics/`. Its first page is a short
|
|
health summary; later pages deduplicate errors, retain useful evidence, and
|
|
record how every collected section was treated without reproducing large lists
|
|
of healthy inventory. See [Diagnostics reports](docs/diagnostics.md), including
|
|
the [safe finding-closure guide](docs/diagnostics.md#closing-findings-safely).
|
|
|
|
You can also invoke Typst directly:
|
|
|
|
```bash
|
|
typst compile \
|
|
--input report=reports/my-report.yaml \
|
|
report.typ \
|
|
build/my-report.pdf
|
|
```
|
|
|
|
### Project layout
|
|
|
|
```text
|
|
report.typ Typst entry point
|
|
model.typ Shared layout and YAML renderer
|
|
render.sh Convenience build script
|
|
assets/ Logos and other static assets
|
|
reports/ Authoritative YAML report sources
|
|
build/ Generated PDFs
|
|
docs/ Detailed documentation and examples
|
|
```
|
|
|
|
## Detailed guides
|
|
|
|
- [Writing reports](docs/writing-reports.md) — field reference, content blocks,
|
|
report types, status values, and authoring guidance.
|
|
- [Examples and boilerplate](docs/examples.md) — complete minimal and full
|
|
reports ready to copy and adapt.
|
|
- [Advanced setup](docs/advanced-setup.md) — nested archives, customization,
|
|
YAML themes, automation, and Git policy.
|
|
- [Diagnostics reports](docs/diagnostics.md) — WinDiagnostics synthesis,
|
|
filtering policy, usage, safe finding closure, and limitations.
|
|
|
|
## Core principle
|
|
|
|
YAML files are the authoritative report sources. Keep content and report state
|
|
in YAML, and keep visual presentation in `model.typ`. For example, prefer
|
|
`severity: high` over fields that specify colors or fonts.
|
|
|
|
Generated PDFs are reproducible artifacts suitable for email, handoff,
|
|
printing, tickets, and archival. Whether they are committed to Git is a project
|
|
policy; see [Generated PDF policy](docs/advanced-setup.md#generated-pdf-policy).
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE).
|