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.

---
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.

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

Bullets that appear one at a time

Wrap a list in an incremental block and each item appears on its own click.

The source looks like this:

::: {.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

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:

::: {.top-tip .fragment}
Appears on a click.
:::

A plain fragment block groups several things onto one click — everything inside it appears together:

::: {.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.

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

:::: {.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

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.

<!--
Your notes go here. They can run to
several lines.
-->

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.

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.

Use it sparingly. One per slide at most, and not on every slide.

Definitions and top tips

Two more, both set apart from the main line of the argument rather than being part of it.

The source for semantic blocks

::: {.keypoint}
The thing to remember
:::

Four are defined, and four is deliberate — beyond about six nobody remembers which is which:

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.

The source for learning outcomes

::: {.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:

![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:

![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:

![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:

![](/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:

## 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.

The source:

| 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 source:

> 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:

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.

# 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.

Attributes on a slide

Anything in braces after a slide title becomes an option on that slide. This is optional — most slides need nothing.

## Key Points {.card}
## Method {data-background-color="#440099"}
## Case study {data-background-image="diamond.jpg"}
## Half-written thing {.skip}

{.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.

Style classes

A small set of class names is reserved for slides that need a distinct layout:

card · stat · grid · timeline · team · closing

## 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.

## 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.

# 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:

# 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.

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.