chfoit-ipa/README.md

CHFOIT-IPA

CHFOIT-IPA is a specialized Typst library and template tailored for the "Individuelle Produktivarbeit" (IPA) within the Federal Office of Information Technology (BIT) of Switzerland.

It automates the administrative overhead of documentation-versioning, schedule syncing, and code embedding. It allows you to focus on the technical content of your project.

Features

• Swiss Government Styling: Implements the official color palette and typography of the Swiss Design System.
• Automated Document Assembly: A modular structure that pulls content from structured subdirectories.
• Open API Spec renderer: You can use "@local/chfoit-ipa:0.0.0": oasviz to render your swagger.json
• Dynamic Asset Pipeline:
  • Draw.io Integration: Automatic export of .drawio diagrams to PDF.
  • Excel to Document: Syncs Excel-based schedules into PDF attachments and provides the timetable for the "Arbeitsjournal"
• Git-Powered Versioning: Automatically populates the "Version History" table using git log metadata and person mapping.
• Smart Appendix: Automatically tracks and renders source code from the 04_Code/ directory with syntax highlighting.
• Language Support: Automatic "ß" to "ss" conversion.

Usage

Setup Configuration

1. Clone this Repository

2. Make a symlink to your local Typst packages: ln -s "$PWD" "${data-dir}/typst/packages/local/chfoit-ipa/0.0.0"

   The variable data-dir is:

   • $XDG_DATA_HOME or ~/.local/share on Linux
   • ~/Library/Application Support on macOS
   • %APPDATA% on Windows

3. Initialize your IPA with this command:

   typst init @local/chfoit-ipa:0.0.0 test
   

4. Change the placeholder Variables

5. Have a successful IPA

Build Process

The template relies on a Makefile to handle external dependencies like Draw.io and Excel.

Here are the most important targets:

• Build everything: make
• Live Preview: make watch (Watches only Typst files).
• Build Diagrams: make drawio.

Requirements

To use the full automation suite, ensure the following are installed:

• Typst CLI: The core compiler.
• Draw.io Desktop: For automated diagram exports. If you are on macOS you may have to specify DRAWIO_CMD="/Applications/draw.io.app/Contents/MacOS/draw.io" when running your makefiles.
• LibreOffice (Headless): To convert .xlsx project plans to PDF.
• Python 3: For converting Excel schedules to YAML for dynamic Typst. Make sure you have the dependencies from the 02_Zeitplan/requirements.txt file installed.