feat: modernize build tooling, themes, and project docs

calvinhp · claude · calvinhp · commit fe140372d532 · 2026-03-23T11:54:51.000-04:00
Migrate SCSS themes from @import to @use/sass:color module syntax, update Makefile for Vite-based Reveal.js builds with automatic plugin copying, fix GitHub Actions workflow raw/endraw placement, and add AGENTS.md and root .gitignore. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.claude
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repo is a Cookiecutter template. The root `cookiecutter.json` defines prompts (title, event, year, slug, keywords, author info), and all scaffolded assets live in `{{cookiecutter.presentation_slug}}/`. Inside that directory:
+
+- `slides.md` — Pandoc Markdown source with YAML front matter and Jinja2 template variables.
+- `images/` — presentation media (tracked with Git LFS in generated projects).
+- `themes/` — SCSS themes (`wildclouds`, `wildclouds_night`, `wildclouds_white`, `minions_white`). During builds, the active theme is copied to `css/theme/` and compiled via Vite.
+- `tricks.yaml` — watchdog config for `make watch`.
+- `Makefile` — orchestrates Reveal.js fetch, npm install, plugin copying, Pandoc rendering, and dev server.
+- `.github/workflows/static.yml` — GitHub Actions workflow (wrapped in `{% raw %}`/`{% endraw %}` Jinja tags) that builds and deploys to GitHub Pages using Pandoc 3.8.2 with LFS support.
+
+The default theme is `wildclouds`, set via the `slide-theme` variable at the top of the Makefile.
+
+## Build, Test, and Development Commands
+- `cookiecutter .` scaffolds a new presentation locally; pass the GitHub URL for remote use.
+- `nvm install --lts` aligns Node with the expected Reveal.js toolchain.
+- `make index.html` fetches Reveal.js (if not present), runs `npm install`, copies built plugins to `plugin/` paths expected by Pandoc's revealjs template, and renders slides via Pandoc.
+- `make start` builds then launches the Reveal.js dev server with live reload.
+- `make watch` (requires `watchmedo` / `watchdog`) rebuilds whenever Markdown changes; configured via `tricks.yaml`.
+- `npm run build:styles` regenerates theme CSS if you touch SCSS sources (the Makefile calls this automatically for the active theme).
+- `make clean` removes all Reveal.js artifacts (js/, css/, dist/, node_modules/, etc.) to reset the working directory.
+- `make help` prints available Make targets with descriptions.
+
+## Coding Style & Naming Conventions
+Author slides in Markdown with Pandoc attributes; prefer fenced blocks and explicit IDs (`# Slide Title {.class}`). Use fenced divs with colons for credits and speaker notes (`::: notes`). Indent YAML front matter with two spaces. Follow SCSS conventions already present: 2-space indentation, descriptive `$variable` names, and import ordering (`@import` template files before custom rules). Name new template files with lowercase-hyphenated or lowercase-underscore patterns to match existing assets (e.g., `wildclouds_night.scss`).
+
+When editing the GitHub Actions workflow, keep the `{% raw %}`/`{% endraw %}` wrapper intact so Jinja2 doesn't interpret GitHub Actions expressions like `${{ }}`.
+
+## Testing Guidelines
+There is no automated test suite; rely on manual verification. After edits, run `make index.html` to ensure Pandoc completes without warnings, then use `make start` to review behavior in the browser. If you adjust themes, confirm `dist/theme/<theme>.css` regenerates via `npm run build:styles` and inspect slides for visual regressions. For GitHub Actions changes, verify the workflow YAML is valid and that the `{% raw %}` wrapper is preserved. Document any required manual checks in the generated project's README when you introduce nonstandard behavior.
+
+## Commit & Pull Request Guidelines
+Adopt Conventional Commit prefixes (`feat:`, `fix:`, `docs:`) as seen in the history (`feat: enable Git LFS…`). Scope template-only changes with clear descriptions (e.g., `feat: add keynote-style layout`). For pull requests, include: summary of template impact, sample command output or screenshots from a generated project, and links to related issues. Run the relevant `make` targets before submission and note any manual verification performed to help reviewers reproduce results quickly.
diff --git a/{{cookiecutter.presentation_slug}}/.github/workflows/static.yml b/{{cookiecutter.presentation_slug}}/.github/workflows/static.yml
@@ -1,3 +1,4 @@
+{% raw %}
 # Simple workflow for deploying static content to GitHub Pages
 name: Deploy Reveal.js Presentation Content to Pages
 
@@ -25,9 +26,9 @@ jobs:
   deploy:
     environment:
       name: github-pages
-      {% raw %}
+
       url: ${{ steps.deployment.outputs.page_url }}
-      {% endraw %}
+
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -54,9 +55,10 @@ jobs:
           mv dist/ _site/
           mv plugin/ _site/
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v4
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+{% endraw %}
diff --git a/{{cookiecutter.presentation_slug}}/.gitignore b/{{cookiecutter.presentation_slug}}/.gitignore
@@ -12,19 +12,19 @@ dist/
 examples/
 .sass-cache
 CONTRIBUTING.md
-bower.json
 css/
-gruntfile.js
-ignores
 js/
-lib/
+public/
 package-lock.json
 package.json
 plugin/
 reveal.js-master/
+scripts/
+react/
 test/
-.travis.yml
 index.html
 .github/
-.npmignore
-gulpfile.js
+tsconfig.json
+tsconfig.node.json
+vite.config.ts
+vite.config.styles.ts
diff --git a/{{cookiecutter.presentation_slug}}/Makefile b/{{cookiecutter.presentation_slug}}/Makefile
@@ -14,12 +14,19 @@ js/reveal.js:
 	bsdtar --strip-components=1 --exclude .gitignore --exclude LICENSE --exclude README.md --exclude demo.html --exclude index.html -xf master.zip
 	rm master.zip
 	npm install
+	@# Copy built plugins to paths expected by Pandoc's revealjs template
+	@for p in notes search zoom math highlight markdown; do \
+		if [ -f dist/plugin/$$p.js ]; then \
+			mkdir -p plugin/$$p; \
+			cp dist/plugin/$$p.js plugin/$$p/$$p.js; \
+		fi; \
+	done
 
-css/theme/source/$(slide-theme).scss: themes/$(slide-theme).scss
+css/theme/$(slide-theme).scss: themes/$(slide-theme).scss
 	cp "$<" "$@"
 
-dist/theme/$(slide-theme).css: css/theme/source/$(slide-theme).scss
-	npm run build -- css-themes
+dist/theme/$(slide-theme).css: css/theme/$(slide-theme).scss
+	npm run build:styles
 
 start: index.html ## bulid presentation and start server
 	@echo "Starting the local presentation server 🚀"
@@ -28,19 +35,23 @@ start: index.html ## bulid presentation and start server
 clean: ## clean up the working directory
 	rm CONTRIBUTING.md || true
 	rm LICENSE || true
-	rm .npmignore || true
 	rm -rf css/ || true
-	rm gulpfile.js || true
 	rm index.html || true
 	rm -rf examples/ || true
 	rm -rf js/ || true
-	rm -rf lib/ || true
+	rm -rf public/ || true
 	rm package-lock.json || true
 	rm package.json || true
 	rm -rf plugin/ || true
+	rm -rf scripts/ || true
 	rm -rf test/ || true
 	rm -rf node_modules/ || true
 	rm -rf dist/ || true
+	rm -rf react/ || true
+	rm tsconfig.json || true
+	rm tsconfig.node.json || true
+	rm vite.config.ts || true
+	rm vite.config.styles.ts || true
 
 watch: ## Watch for changes and rebuild
 	@echo "♻️ Watching for changes..."
diff --git a/{{cookiecutter.presentation_slug}}/themes/minions_white.scss b/{{cookiecutter.presentation_slug}}/themes/minions_white.scss
@@ -4,47 +4,51 @@
  * By Hakim El Hattab, http://hakim.se
  */
 
+// Load utils
+@use 'sass:color';
+@use 'template/mixins' as mixins;
 
-// Default mixins and settings -----------------
-@import "../template/mixins";
-@import "../template/settings";
-// ---------------------------------------------
+$active-color: #2a76dd;
+
+// Inject theme variables (with some overrides)
+@use 'template/settings' with (
+  $background-color: #fff,
+
+  $block-margin: 10px,
+
+  $main-color: #222,
+  $main-font-size: 40px,
+  $main-font: "'Roboto', sans-serif",
+
+  $heading-color: #222,
+  $heading-margin: 0 0 10px 0,
+  $heading-font: "'Saira Condensed', Impact, sans-serif",
+  $heading-text-shadow: none,
+  $heading-letter-spacing: -0.03em,
+  $heading-line-height: 1,
+  $heading-text-transform: uppercase,
+  $heading-font-weight: 900,
+
+  $heading1-size: 2.3em,
+  $heading2-size: 1.7em,
+  $heading3-size: 1.3em,
+  $heading4-size: 1.0em,
+
+  $code-font: "'Fira Code', monospace",
+
+  $link-color: $active-color,
+  $link-color-hover: color.scale($active-color, $lightness: 15%),
+  $selection-background-color: color.scale($active-color, $lightness: 25%)
+);
+
+// Inject the theme template
+@use 'template/theme';
 
 // Include theme-specific fonts
 @import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@500&family=Roboto&family=Saira+Condensed:wght@900&display=swap');
 
-// Override theme settings (see ../template/settings.scss)
-$backgroundColor: #fff;
-
-$blockMargin: 10px;
-
-$mainColor: #222;
-$headingColor: #222;
-
-$mainFontSize: 40px;
-$mainFont: 'Roboto', sans-serif;
-$headingMargin: 0 0 $blockMargin 0;
-$headingFont: 'Saira Condensed', Impact, sans-serif;
-$headingTextShadow: none;
-$headingLetterSpacing: -0.03em;
-$headingLineHeight: 1;
-$headingTextTransform: uppercase;
-$headingFontWeight: 900;
-$codeFont: 'Fira Code', monospace;
-$linkColor: #2a76dd;
-$linkColorHover: lighten( $linkColor, 15% );
-$selectionBackgroundColor: lighten( $linkColor, 25% );
-
-$heading1Size: 2.3em;
-$heading2Size: 1.7em;
-$heading3Size: 1.3em;
-$heading4Size: 1.0em;
-
-section.has-dark-background {
-	&, h1, h2, h3, h4, h5, h6 {
-		color: #fff;
-	}
-}
+// Change text when the background is inverted
+@include mixins.dark-bg-text-color(#fff);
 
 .slide-background {
     filter: grayscale(50%) opacity(20%) blur(0);
@@ -111,7 +115,3 @@ body:after {
   bottom: -14em;
   left: -26em;
 }
-
-// Theme template ------------------------------
-@import "../template/theme";
-// ---------------------------------------------
diff --git a/{{cookiecutter.presentation_slug}}/themes/wildclouds.scss b/{{cookiecutter.presentation_slug}}/themes/wildclouds.scss
@@ -3,27 +3,11 @@
  * Author: Achim Staebler
  */
 
+// Load utils
+@use 'sass:color';
+@use 'template/mixins' as mixins;
 
-// Default mixins and settings -----------------
-@import "../template/mixins";
-@import "../template/settings";
-// ---------------------------------------------
-
-
-
-// Include theme-specific fonts
-@import url(../../lib/font/league-gothic/league-gothic.css);
-@import url(https://fonts.googleapis.com/css?family=Lato:400,700,400italic,700italic);
-
-/**
- * Solarized colors by Ethan Schoonover
- */
-html * {
-	color-profile: sRGB;
-	rendering-intent: auto;
-}
-
-// Solarized colors
+// Solarized colors by Ethan Schoonover
 $base03:    #002b36;
 $base02:    #073642;
 $base01:    #586e75;
@@ -41,19 +25,36 @@ $blue:      #268bd2;
 $cyan:      #2aa198;
 $green:     #859900;
 
-// Override theme settings (see ../template/settings.scss)
-$mainColor: $base1;
-$headingColor: $base2;
-$headingTextShadow: none;
-$backgroundColor: $base03;
-$linkColor: $blue;
-$linkColorHover: lighten( $linkColor, 20% );
-$selectionBackgroundColor: $magenta;
+$active-color: $blue;
+
+// Inject theme variables (with some overrides)
+@use 'template/settings' with (
+  $background-color: $base03,
 
-$heading1Size: 2.3em;
-$heading2Size: 1.7em;
-$heading3Size: 1.3em;
-$heading4Size: 1.0em;
+  $main-color: $base1,
+  $heading-color: $base2,
+  $heading-text-shadow: none,
+
+  $heading1-size: 2.3em,
+  $heading2-size: 1.7em,
+  $heading3-size: 1.3em,
+  $heading4-size: 1.0em,
+
+  $link-color: $active-color,
+  $link-color-hover: color.scale($active-color, $lightness: 20%),
+  $selection-background-color: $magenta
+);
+
+// Inject the theme template
+@use 'template/theme';
+
+// Include theme-specific fonts
+@import url('https://fonts.googleapis.com/css?family=Lato:400,700,400italic,700italic');
+
+html * {
+  color-profile: sRGB;
+  rendering-intent: auto;
+}
 
 .slide-background {
     filter: grayscale(50%) opacity(20%) blur(2px);
@@ -83,8 +84,3 @@ body:after {
   bottom: -9em;
   left: -7em;
 }
-
-
-// Theme template ------------------------------
-@import "../template/theme";
-// ---------------------------------------------
diff --git a/{{cookiecutter.presentation_slug}}/themes/wildclouds_night.scss b/{{cookiecutter.presentation_slug}}/themes/wildclouds_night.scss
@@ -4,29 +4,34 @@
  * Copyright (C) 2011-2012 Hakim El Hattab, http://hakim.se
  */
 
+// Load utils
+@use 'sass:color';
+@use 'template/mixins' as mixins;
 
-// Default mixins and settings -----------------
-@import "../template/mixins";
-@import "../template/settings";
-// ---------------------------------------------
+$active-color: #e7ad52;
 
+// Inject theme variables (with some overrides)
+@use 'template/settings' with (
+  $background-color: #111,
 
-// Include theme-specific fonts
-@import url(https://fonts.googleapis.com/css?family=Montserrat:700);
-@import url(https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic,700italic);
+  $main-font: "'Open Sans', sans-serif",
 
+  $heading-font: "'Montserrat', Impact, sans-serif",
+  $heading-text-shadow: none,
+  $heading-letter-spacing: -0.03em,
+  $heading-text-transform: none,
 
-// Override theme settings (see ../template/settings.scss)
-$backgroundColor: #111;
+  $link-color: $active-color,
+  $link-color-hover: color.scale($active-color, $lightness: 20%),
+  $selection-background-color: $active-color
+);
 
-$mainFont: 'Open Sans', sans-serif;
-$linkColor: #e7ad52;
-$linkColorHover: lighten( $linkColor, 20% );
-$headingFont: 'Montserrat', Impact, sans-serif;
-$headingTextShadow: none;
-$headingLetterSpacing: -0.03em;
-$headingTextTransform: none;
-$selectionBackgroundColor: #e7ad52;
+// Inject the theme template
+@use 'template/theme';
+
+// Include theme-specific fonts
+@import url(https://fonts.googleapis.com/css?family=Montserrat:700);
+@import url(https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic,700italic);
 
 .slide-background {
     filter: grayscale(50%) opacity(20%) blur(0px);
@@ -48,8 +53,3 @@ $selectionBackgroundColor: #e7ad52;
         padding-right: 12px;
     }
 }
-
-
-// Theme template ------------------------------
-@import "../template/theme";
-// ---------------------------------------------
diff --git a/{{cookiecutter.presentation_slug}}/themes/wildclouds_white.scss b/{{cookiecutter.presentation_slug}}/themes/wildclouds_white.scss
