arwaa/ticket 5 (point system)

.github/workflows/mdbook.yml

@@ -1,52 +1,52 @@
-# Sample workflow for building and deploying a mdBook site to GitHub Pages
+# Build and deploy the mdBook site to GitHub Pages.
 #
-# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
+# Repo settings: Settings → Pages → Build and deployment → GitHub Actions
 #
 name: Deploy mdBook site to Pages
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  # Build job
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install mdBook & dependencies
+
+      - name: Install Rust
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh
+          sh /tmp/rustup-init.sh -y
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      - name: Install mdBook & mdbook-callouts
         run: |
-          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-          rustup update
-          cargo install mdbook
-          cargo install mdbook-callouts
+          cargo install mdbook --locked --version 0.5.3
+          cargo install mdbook-callouts --locked --version 0.3.0
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
+
       - name: Build with mdBook
         run: mdbook build
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./book
 
-  # Deployment job
   deploy:
     environment:
       name: github-pages

.gitignore

@@ -1 +1 @@
-book
+book

README.md

@@ -1,13 +1,103 @@
-# 2025-CompClub-Spring-Handbook
+# Workshop Handbook Template
 
-Use callouts like so: https://crates.io/crates/mdbook-callouts
+Template for workshop handbooks using [mdBook](https://rust-lang.github.io/mdBook/) + [mdbook-callouts](https://crates.io/crates/mdbook-callouts).
 
-You will need to have rust and run `cargo install mdbook`and `cargo install mdbook-callouts`
-if you don't have the packages already.
+Maintained by **CompClub** as a starting point for workshop handbooks. Fork it, replace the placeholder chapters, and deploy to GitHub Pages.
 
-To build, open the book and have it auto-update on save, do ``mdbook serve --open``.
+## What's included
 
-Alternatively, you can also use ``mdbook build --open``.
+- **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`
 
-**Make sure you are NOT merging directly into master!!** 
-make a branch with ur name and topic in it and do a pull request :)
+## Prerequisites
+
+Install [Rust](https://rustup.rs/), then:
+
+```bash
+cargo install mdbook mdbook-callouts
+```
+
+Pin versions for reproducible builds (optional):
+
+```bash
+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:
+
+```bash
+mdbook serve --open
+```
+
+Build static output to `book/`:
+
+```bash
+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`](theme/examples/pirate/README.md).
+
+### Callouts
+
+See [`src/examples/callouts.md`](src/examples/callouts.md). Syntax:
+
+```markdown
+> [!TIP] Optional title
+> Body text.
+```
+
+### Answer widgets
+
+See [`src/examples/answer-widget.md`](src/examples/answer-widget.md) for the copy-paste HTML + inline script pattern.
+
+## Deployment
+
+Pushing to `main` triggers [`.github/workflows/mdbook.yml`](.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:
+
+```toml
+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.