SpiralTrain Presentation as Code Template

This repository is a reusable template for creating high-quality, professional training presentations and exercise guides. It uses a pure TypeScript toolchain driven by Marp (for slides) and Shiki (for syntax highlighting).

---

⚡ Quick Start (Using Bun)

We recommend using Bun for maximum performance and native TypeScript execution. All tooling configuration and dependencies are encapsulated inside the build/ directory to keep the root directory clean.

1. Install dependencies:

   bun install --cwd build
   

2. Build the slides PDF:

   bun run --cwd build build
   

3. Start the live-reloading dev server:

   bun run --cwd build serve
   

   Press P in the browser window to open Presenter Mode with synchronized speaker notes.

4. Build the exercises PDF:

   bun run --cwd build build -- --exercises
   

5. Lint slide heights:

   bun run --cwd build lint
   

---

🐢 Standard Setup (Using Node & npm)

If Bun is not available, you can use the standard Node.js toolchain.

1. Install dependencies:

   cd build
   npm install
   

2. Build the slides PDF:

   cd build
   npm run build
   

3. Start the dev server:

   cd build
   npm run serve
   

4. Build the exercises PDF:

   cd build
   npm run build -- --exercises
   

5. Lint slide heights:

   cd build
   npm run lint
   

---

📂 Directory Structure

├── build/
│   ├── dist/                 # Generated temporary build files
│   ├── build.ts              # Central orchestrator (builds PDFs, serves slides, outlines)
│   ├── lint-slides.ts        # Estimates visual heights to prevent overflows
│   ├── marp.config.mjs       # Marp configuration integrating Shiki
│   └── shiki-exercises.mjs   # Helper to highlight fenced code blocks in exercises
├── src/
│   ├── slides/
│   │   ├── 00-preamble/
│   │   │   └── 00-preamble.md    # Title slide, general course info, and remarks
│   │   ├── 01-introduction/
│   │   │   └── 01-introduction.md# First module slides
│   │   └── spiraltrain.css       # Brand styling and layouts (two-col, version-badge, etc.)
│   └── exercises/
│       └── 01-sample-exercise.md # Hands-on exercises with expandable reference solutions
├── package.json              # Project scripts and dependencies
├── tsconfig.json             # TypeScript settings
└── README.md                 # This guide

---

🎨 Slide Authoring Guide

Rules for Slide Layout

• Static Lists (-): Use dashes for lists where all items appear at once.
• Two-Column Layout (.two-col):

  <div class="two-col">
  <div>
  
  - Left column item 1
  - Left column item 2
  
  </div>
  <div>
  
  - Right column item 1
  - Right column item 2
  
  </div>
  </div>
  

• Version/Runtime Badges (.version-badge):

  <span class="badge-row">
    <span class="version-badge">C# 13</span>
    <span class="version-badge dotnet">.NET 9</span>
  </span>
  

• Speaker Notes: Include notes inside <!-- NOTES: ... --> blocks at the end of each slide.

---

🛠️ Advanced CLI Options

The build orchestrator accepts several configuration flags:

• --slides-dir <path>: Build slides from a different folder (default: src/slides).
• --out <filename>: Override the default output filename.
• --force: Bypass slide height budget linter warnings and build anyway.

Example:

bun run --cwd build build -- --slides-dir my-other-slides-folder --out Custom-Course-Deck.pdf