Workshop Handbook Template

Template for workshop handbooks using mdBook + mdbook-callouts.

Maintained by CompClub as a starting point for workshop handbooks. Fork it, replace the placeholder chapters, and deploy to GitHub Pages.

What's included

• Starter chapters — introduction plus example pages under src/examples/
• Workshop page templates — guided workshop, CTF challenge, and quick-reference pages under src/templates/
• Callout examples — src/examples/callouts.md (INFO, TIP, WARNING, etc.)
• Answer widget demo — src/examples/answer-widget.md (interactive check-your-answer pattern)
• Neutral default theme — built-in coal theme with minimal theme/custom.css
• Deploy workflow — .github/workflows/mdbook.yml builds and publishes on push to main

Prerequisites

Install Rust, then:

cargo install mdbook mdbook-callouts

Pin versions for reproducible builds (optional):

cargo install mdbook --locked --version 0.5.3
cargo install mdbook-callouts --locked --version 0.3.0

Note: mdbook-callouts 0.3.x requires mdBook 0.5.x.

Local development

Preview with live reload:

mdbook serve --open

Build static output to book/:

mdbook build

First-time fork setup checklist

• Rename the repo (if forking for a specific workshop)
• Update book.toml → title, author, description
• Update book.toml → site-url to /<your-repo-name>/
• Update book.toml → git-repository-url
• Replace placeholder content in src/
• Enable GitHub Pages → Settings → Pages → Build and deployment → GitHub Actions
• Push to main and verify the deploy workflow completes

Customization (optional)

None of this is required — pick what fits your workshop.

Adding chapters

1. Create a .md file under src/.
2. Link it in src/SUMMARY.md.
3. Run mdbook serve --open to preview.

For a faster start, copy a page from src/templates/, rename it, and replace the bracketed placeholder content.

Changing theme

Set default-theme in book.toml to any built-in mdBook theme: coal, navy, light, rust, or ayu.

For light tweaks, edit theme/custom.css. For full custom branding, see the archived pirate example at theme/examples/pirate/README.md.

Callouts

See src/examples/callouts.md. Syntax:

> [!TIP] Optional title
> Body text.

Answer widgets

See src/examples/answer-widget.md for the copy-paste HTML + inline script pattern.

Deployment

Pushing to main triggers .github/workflows/mdbook.yml, which installs Rust, builds the book, and deploys to GitHub Pages.

Ensure Pages is set to GitHub Actions (not “Deploy from a branch”) in the repo settings.

Canonical template note

This repository (Workshop-handbook-template) uses:

site-url = "/Workshop-handbook-template/"
git-repository-url = "https://github.com/davidjosesao/Workshop-handbook-template"

Forks must update site-url and git-repository-url in book.toml to match their own repo name, or navigation and asset links will break on GitHub Pages.