--- title: "Presentation Template" subtitle: "The slide markdown format, documented in its own syntax" kicker: "Framework documentation" author: "Andrew Garrard" institute: "University of Sheffield" date: "2026-08-08" theme: "white" base: "../" --- ## About this system Lectures are written as markdown and converted into a reveal.js presentation. Three pieces: - **This format** — ordinary markdown, with a small number of additions for the things markdown has no answer for - **`build.html`** — a converter you open in a browser. Pick a `.md` file, get an `.html` deck back. Nothing to install - **`framework/`** — the shared folder holding reveal.js and the house stylesheet, which every deck links to The generated deck contains your content and links out to the shared framework, so it is small and the styling is fixed in one place. Upload the whole tree to the website and everything resolves. This file is both the template and the documentation. Copy it to start a deck; read it — as markdown or as the deck it produces — to remember the syntax. ## How a deck is put together Everything above the first `---` is **front matter**. It describes the deck rather than any one slide, and the title slide is built from it — you do not write a title slide yourself. ```yaml --- title: "Steady Conduction" subtitle: "Heat Transfer · Week 3" kicker: "MEC Lecture · Heat Transfer" author: "Andrew Garrard" institute: "University of Sheffield" details: "Diamond Lecture Theatre 1" date: "2026-08-08" theme: "white" base: "../../../" --- ``` The title slide is the University cover: the Diamond photograph fading in from the right, the crest top right, and the deck's details laid out around it. | Field | Where it appears on the cover | |---|---| | `title` | The large heading. The only one you must have | | `subtitle` | Serif italic line under the title | | `kicker` | Small capitals along the top, e.g. the module or type of talk | | `author`, `institute` | The **Presenter** card, bottom left | | `details`, `date` | The **Details** card, bottom right: a room, module code or event — wherever the talk lives. A date written `2026-08-08` is shown as 8 August 2026 | | `cover` | A different photo for this deck, e.g. `/images/jf22.png`. Leave it out for the Diamond | Leave any of them out and that part of the cover simply disappears. `base` is the path from the deck back to the **site root** — the folder that holds `framework`. Set it once when you create a deck: a deck in `teaching-presentations/heat-transfer/Steady Conduction/` is three levels down, so `base` is `../../../`. `theme` picks which stock reveal.js theme to build on. Leave it as `white` unless you have a reason not to; the house styling lives in `agSlides.css`, which loads on top of whichever you choose. The `title` and `author` appear in the bar along the bottom of every content slide, beside the University crest. The bar hides itself on title and section slides. The `footer` field is not needed — the bar always uses the title. Each `##` heading starts a new slide, and its text becomes the slide title. That is the only rule you have to remember. ## A slide of prose Most slides are just text. Write paragraphs as you would anywhere else and leave a blank line between them. Use **strong** for the points you want to land, and _emphasis_ where you want a lighter touch. Both are styled by the theme rather than by anything you do here, so they stay consistent across every deck. Keep prose slides short. If a paragraph runs past three or four lines it has stopped being a slide and started being a handout. ## A slide of bullets Bullets are plain markdown. Use `-` for unordered lists and `1.` for ordered ones. - Heat conduction needs no bulk motion of the material - The flux is proportional to the temperature gradient - The constant of proportionality is the thermal conductivity Numbered lists work the same way: 1. State what is conserved 2. Write the constitutive relation 3. Apply the boundary conditions ## Nesting lists {.smaller} Indent a sub-point to line up with the **text** of its parent — not with the bullet. Use **four spaces per level** and it always works: - Steady state - Temperature does not vary with time - The flux is uniform through a plane wall - Even where the material is not uniform 1. State what is conserved - Mass - Energy A slide that needs three levels is usually a slide that needs splitting. ::: {.top-tip} Two spaces nests under a bullet but **not** under a numbered item, because `1. ` is three characters wide and `- ` is only two. It fails silently — the list just comes out flat. Four spaces avoids the whole question. ::: ## Bullets that appear one at a time Wrap a list in an `incremental` block and each item appears on its own click. ::: {.incremental} - Heat flux is a **local** quantity, measured per unit area - Heat rate is a **total** quantity, integrated over an area - For uniform flux through area A, the two are related by Q = q″A ::: The source looks like this: ```markdown ::: {.incremental} - First point - Second point ::: ``` Only use this where the order genuinely matters. Most lists are reference material and should appear all at once. ## Pausing between blocks An incremental block reveals list items. To pause between whole blocks — paragraphs, images, equations — put three spaced dots on a line of their own. Everything after the dots waits for a click, so put the pause near the end of a slide. This paragraph and the one below demonstrate it. Doubling the cross-sectional area at fixed heat rate halves the flux. . . . And halves the temperature gradient along with it. ## The source for a pause ```markdown First block, on screen straight away. . . . Second block, appears on the next click. ``` Everything following the dots becomes a fragment — not just the next paragraph, but images, equations, code blocks and whole `:::` blocks after it too. That is why the pause belongs near the bottom of a slide rather than the middle. Each block after a pause is its **own click**. To make several blocks appear together on one click, wrap them in a `fragment` block (below) — it needs no `. . .` in front of it. A pause inside a column stays inside that column. To make one particular block appear on a click without pausing everything after it, give it reveal's own `fragment` class instead: ```markdown ::: {.top-tip .fragment} Appears on a click. ::: ``` A plain `fragment` block groups several things onto one click — everything inside it appears together: ```markdown ::: {.fragment} _alternatively_ > Colours for Directors ::: ``` Use it where a point lands better after a beat: a result you want the room to predict before you show it, or a punchline you would rather they did not read ahead of you. ## Two columns Wrap the whole thing in `.columns`, then each side in a `.column` with a width. :::: {.columns} ::: {.column width="50%"} ### Microscopic Molecules vibrating about lattice sites, passing energy to their neighbours. Explains **why** conduction happens. ::: ::: {.column width="50%"} ### Macroscopic A smooth, continuous temperature field obeying a differential relationship. Useful for **calculating** anything. ::: :::: Note the four colons on the outer wrapper and three on each column. The outer block must have more colons than the ones nested inside it. ## The source for two columns ```markdown :::: {.columns} ::: {.column width="50%"} Left hand side ::: ::: {.column width="50%"} Right hand side ::: :::: ``` Widths need not be equal. A narrow figure beside wider text usually wants `width="40%"` and `width="60%"`. ## Equations Wrap inline maths in single dollars: the heat flux $q''$ depends on the conductivity $k$ and the gradient $dT/dx$. Display equations go on their own line, wrapped in double dollars: $$q'' = -k \frac{dT}{dx}$$ The minus sign encodes the second law — heat flows from hot to cold — so if temperature rises with $x$ then $q''$ is negative. Longer expressions work the same way: $$Q = \frac{k A \left(T_1 - T_2\right)}{L}$$ ## The source for equations ```markdown Inline maths like $q''$ sits in the run of text. Display maths goes on its own line: $$q'' = -k \frac{dT}{dx}$$ ``` Anything LaTeX understands will render — fractions, subscripts, superscripts, Greek letters, integrals and matrices. ## Speaker notes Speaker notes are written as HTML comments. They never appear on the slide, and they are invisible in a plain markdown preview too, so your source stays clean. ```markdown ``` Press **S** during the presentation to open the speaker view, which shows your notes, a timer, and a preview of the next slide. This slide has notes attached. Open the speaker view to read them. # Content you will use constantly ## Emphasising a point Some blocks name what a thing **is**, rather than how it should look. The stylesheet decides the appearance, so it stays consistent across every deck and you can change all of them at once later. ::: {.keypoint} This is a keypoint — the thing you want the room to remember ::: Use it sparingly. One per slide at most, and not on every slide. ::: {.question} And this is a question — something you are actually asking them ::: ## Definitions and top tips Two more, both set apart from the main line of the argument rather than being part of it. ::: {.definition} **Thermal conductivity** — a material property describing how readily a material conducts heat, measured in W/m·K. ::: ::: {.top-tip} Write the block that says what you mean, not the one that looks right. If `.keypoint` ever needs to be green, that is one line of CSS rather than a hunt through every lecture you have ever written. ::: ## The source for semantic blocks ```markdown ::: {.keypoint} The thing to remember ::: ``` Four are defined, and four is deliberate — beyond about six nobody remembers which is which: | Block | Means | |:------|:------| | `keypoint` | the thing to remember | | `question` | something you are asking the room | | `definition` | a formal definition | | `top-tip` | a practical aside | Nothing stops you inventing another. The builder will warn you that it is not styled yet, which doubles as a to-do list. ## Learning outcomes Every deck opens with one of these. It is a different kind of block from the four above: they mark something inside the argument, this frames the whole session. ::: {.learning-outcomes} By the end of this lecture you will be able to 1. Explain what a learning outcome is for 2. Write one that starts with a verb you could assess ::: ## The source for learning outcomes ```markdown ::: {.learning-outcomes} By the end of this lecture you will be able to 1. Explain ... 2. Calculate ... ::: ``` Do not type "Learning outcomes" inside the block — the stylesheet supplies the label, so the wording is decided once for every deck. Outcomes work best starting with a verb you could actually assess: *explain*, *calculate*, *compare*. "Understand" is the usual trap — nobody can tell from the outside whether you have. ## Figures Images are plain markdown. Most figures live in the shared `images/` folder at the site root, because subjects overlap and the same figure is often wanted by more than one lecture. Reference those with a **leading slash**, and the deck resolves them wherever it sits: ```markdown ![The JF-22 hypersonic wind tunnel](/images/jf22.png) ``` Every shared image needs an entry in `images/images.json` recording what it shows, where it came from and what its licence is. Build from the command line and you will be told about anything missing. A figure that genuinely belongs to one deck alone can still sit beside it, and is referenced with no path at all: ```markdown ![Temperature profile through a plane wall](profile.png) ``` ## Captions An image on a line of its own becomes a figure with a caption printed under it. By default the caption is the alt text, so every image gets one for free. Where you want them to differ, put the caption on the next line after a colon: ```markdown ![A vast cylindrical vessel filling a hangar](/images/jf22.png) : The JF-22 tunnel at the Chinese Academy of Aerodynamics ``` That version is the better one to write, and the reason is worth knowing. The two are doing different jobs: the alt text describes the picture for someone who cannot see it, and the caption adds context for someone who can. When you let one text do both, it usually does neither especially well. **House rule: alt text and captions end with a full stop.** Not because they are always sentences, but because sooner or later one of them is two sentences — and then the first needs terminating, which leaves the second looking odd unless everything else is punctuated too. Deciding once removes the question. An image with empty alt text gets no caption at all, which is what you want for something purely decorative: ```markdown ![](/images/decorative-background.png) ``` ## Full-bleed images For the slide where the picture is the whole point, add `{.full-bleed}` to the heading. The image fills the screen edge to edge, and the title and caption are laid over it: ```markdown ## Fluent started here {.full-bleed} ![A crowded painting of Sheffield](/images/joe-scarborough-fluent.png) : Joe Scarborough's painting, commissioned in 2000 ``` The image is cropped from the centre to fill the slide, rather than letterboxed — fitting it inside would put the margins back and defeat the point. So a picture with its subject hard against one edge will lose a little of it, which is a reason to choose the picture for this treatment rather than the other way round. One image per full-bleed slide. Both the title and the caption are optional. ## Tables Pipe tables, exactly as markdown defines them. Colons in the separator row set the alignment: left, centre, or right. | Material | $k$ (W/m·K) | Typical use | |:---------|------------:|:------------| | Copper | 400 | Heat sinks, pipework | | Stainless steel | 15 | Structural | | Brick | 0.72 | Building fabric | | Phenolic foam | 0.02 | Insulation | The source: ```markdown | Material | $k$ (W/m·K) | |:---------|------------:| | Copper | 400 | | Brick | 0.72 | ``` Keep tables small. Anything beyond about six rows stops being readable from the back of a lecture theatre. ## Quotations A blockquote is a line beginning with `>`. Use it for anything you are quoting rather than asserting. > The Covid-19 pandemic provided the ultimate empirical test of the > justification for the continued delivery of the contemporary engineering lab > class, by removing learners' access to physical experimental equipment. > > — Garrard, *Practical Engineering Education*, 2024 The source: ```markdown > The Covid-19 pandemic provided the ultimate empirical test of the > justification for the continued delivery of the contemporary engineering lab > class, by removing learners' access to physical experimental equipment. > > — Garrard, *Practical Engineering Education*, 2024 ``` End the quote with a line starting with a dash to give its source. It must be the **last** line, inside the quote. `--` works if an em dash is hard to type; a single `-` does not, because markdown reads that as a list. ## Definition lists A term on one line, its definition on the next beginning with a colon. Thermal conductivity : A material property describing how readily a material conducts heat, measured in W/m·K. Heat flux : The rate of heat transfer per unit area, measured in W/m². A local quantity. Heat rate : The total rate of heat transfer through a surface, measured in W. A global quantity. The source: ```markdown Thermal conductivity : A material property, measured in W/m·K. ``` Definition lists suit glossary and nomenclature slides far better than bullets do, because the visual structure carries the meaning. ## Code Fence a block with three backticks and name the language. ```python # Steady 1D conduction through a plane wall k, A, dT, L = 0.72, 12.0, 18.0, 0.22 Q = k * A * dT / L print(f"Heat loss: {Q:.0f} W") ``` Inline code uses single backticks, like `q''` or `agSlides.css`. # Slide options ## Attributes on a slide Anything in braces after a slide title becomes an option on that slide. This is optional — most slides need nothing. ```markdown ## Key Points {.card} ## Method {data-background-color="#440099"} ## Case study {data-background-image="diamond.jpg"} ## Half-written thing {.skip} ``` | Attribute | Effect | |:----------|:-------| | `{.classname}` | Applies a style class to the slide | | `{data-background-color="..."}` | Sets a solid background colour | | `{data-background-image="..."}` | Sets a full-bleed background image | | `{.skip}` | Omits the slide from the output entirely | `{.skip}` is for slides you are still writing. They stay in the markdown, so you do not lose the work, but they never reach the deck. ## A skipped slide {.skip} This slide carries `{.skip}`, so it appears when you read the markdown file but never appears in the presentation. That is the whole point of it — somewhere to leave a half-finished thought without deleting it or breaking the deck. ## Style classes A small set of class names is reserved for slides that need a distinct layout: `card` · `stat` · `grid` · `timeline` · `team` · `closing` ```markdown ## Key Points {.card} ``` **These are not yet styled.** The house stylesheet is still to be written, so applying one today changes nothing. The names are recorded here so they are used consistently once the CSS exists. ## Embedded teaching demos A demo is embedded by pointing at its HTML file. The converter builds a correctly sized, sandboxed frame around it. ```markdown ## Conduction in action ::: {.demo src="/teaching-demos/heat-transfer/1D_conduction_sim.html" height="460"} ::: ``` The leading slash means the path is from the site root, so the same deck works locally and once uploaded, whatever depth it sits at. Height defaults to a sensible value if you leave it out. Demos are live, not screenshots — the sliders work during the lecture. ## Section dividers A single `#` heading makes a section divider rather than an ordinary slide. Use them to break a long lecture into parts. ```markdown # Transient conduction When the temperature has not settled yet. ``` The divider fills the screen with a violet gradient. It is labelled **Part One**, **Part Two** and so on automatically, in the order the `#` headings appear, so do not number them yourself. A paragraph under the heading becomes an italic sub-heading; leave it out if you do not need one. To label one divider differently, give its heading a `kicker`: ```markdown # Worked example {kicker="Interlude"} ``` The numbering still counts it, so the part after it keeps its place. There are two in this deck. You passed one before the figures section and another before the slide options. Keep it to the heading and at most one short line. A divider is a signpost, not a slide: bullets or pictures under a `#` heading belong on a `##` slide after it. # Putting it together ## Everything, in one place {.smaller} | What | How | |:-----|:----| | Deck metadata | Front matter at the top of the file | | New slide | `## Slide title` | | Section divider | `# Section name` | | Slide options | `## Title {.class key="value"}` | | Two columns | `:::: {.columns}` wrapping `::: {.column width="50%"}` | | Reveal one at a time | `::: {.incremental}` | | Pause between blocks | `. . .` on its own line | | Emphasise a point | `::: {.keypoint}` | | Ask the room | `::: {.question}` | | Define a term | `::: {.definition}` | | Practical aside | `::: {.top-tip}` | | Learning outcomes | `::: {.learning-outcomes}` | | Embedded demo | `::: {.demo src="..."}` | | Speaker notes | `` | | Maths | `$inline$` and `$$display$$` | | Everything else | Ordinary markdown | ## Getting started 1. Copy this file into a new folder and rename it 2. Change the front matter, and set `base` to match how deep the folder sits 3. Delete these slides and write your lecture 4. Open `build.html`, pick your file, download the deck Put figures in the same folder as the deck. Keep the folder structure on your machine identical to the website, and the same relative paths will work in both places.