=============================================================================== framework/ - shared assets =============================================================================== Two unrelated things live in here: 1. The SLIDE system - turns a markdown file into a reveal.js presentation. 2. The TEACHING DEMOS framework - styling for the interactive demos in teaching-demos/. Predates the slide system, nothing to do with slides. ------------------------------------------------------------------------------- SLIDE SYSTEM ------------------------------------------------------------------------------- build.html The converter, and the parser itself. Double-click it, drop a .md file on it, download the deck. Self-contained, nothing to install. Opens your source read-only. convert.bat The same converter from the command line. In PowerShell: convert.js & "G:\My Drive\Teaching\framework\convert.bat" "slides.md" & "G:\My Drive\Teaching\framework\convert.bat" "slides.md" --watch The & and the quotes are needed because the paths contain spaces. Output lands next to the .md, same name, .html. --watch leaves it running and rebuilds every time you save, so the loop is just Ctrl+S in VS Code, then refresh the browser. You can also drag a .md onto the .bat. Needs node 18 or newer. NOTE: this machine has node v10 from 2019 on PATH as well as a modern one in Desktop\AppToolkit - convert.bat version-checks and picks the right one, but that old node will ambush other tools. These contain NO parser. They read build.html and run its parser, so both routes are genuinely the same engine - verified by identical output hashes. build.html itself still needs nothing but a browser. template.md The starter file for a new deck, and the documentation for the format. Copy it to begin a lecture. template.html template.md, built. The same documentation as a deck. agSlides.css The stylesheet for presentations. reveal/ reveal.js 6.0.1 - the presentation engine. Third party. mathjax/ MathJax 3.2.2 - renders equations. Third party. readme.txt This file. ------------------------------------------------------------------------------- TEACHING DEMOS ------------------------------------------------------------------------------- agTeachingDemos.css Shared styling for teaching-demos/. agTeachingDemosGuide.html How to use it. Open in a browser. ------------------------------------------------------------------------------- DIAGRAMS ------------------------------------------------------------------------------- agDiagrams.css The house style for the SVG diagrams in diagrams/. Each .svg links it directly, the way an HTML page links CSS, so every diagram can be restyled at any time from this one file. It imports agTeachingDemos.css rather than redefining anything, so a diagram and a demo on neighbouring slides are drawn from one vocabulary. agDiagramsGuide.html Every colour, class and convention, rendered. Open in a browser. Start here. The three things that catch people out are in diagrams/readme.txt: no inline styles (Inkscape adds them for you), keep the viewBox 1200 wide, and most of a good diagram should be quiet. ------------------------------------------------------------------------------- WHERE THE DETAIL IS ------------------------------------------------------------------------------- The slide format template.md - it documents itself Styling and sizing comments in agSlides.css Shared images images/images.json, at the site root - not in here Why anything is like it CLAUDE.md in the repository root One thing worth knowing before your first deck: each .md file sets "base" in its front matter, which is the path back to the folder CONTAINING framework - not to framework itself. Get it wrong and the deck opens with no styling at all. template.md explains it. The same "base" is what makes a leading slash work. Write an image as /images/jf22.png, or a demo as /teaching-demos/cfd/whatever.html, and the builder turns it into the right relative path for wherever that deck sits. Without the slash a path is relative to the deck itself, which is still the right thing for a figure only that one lecture will ever use. Shared images all live in images/ at the site root, and each needs a line in images/images.json saying what it shows, where it came from and what the licence is. Build from the command line and you will be told about anything missing - build.html cannot check it, because a browser page opened from a file picker cannot read other files off the disk.