psi-slides · presentation software for lecturers · Diese Seite auf Deutsch

Write the lecture once.

One plain-text file in Markdown goes in, and four HTML files come out: the projection for the room, a presenter cockpit on your own screen (the slide, your note for it, and what comes next), and two handouts – the full text of the lecture on its own, and the same text with your notes in it. All four are built from that one file, so they cannot drift apart: there is nothing to keep in step, and each carries everything it needs to open on its own.

Get started Open a live lecture

The slide carries what the room needs to follow you; the handout carries everything worth taking away. That split costs layout freedom – fewer choices than PowerPoint – and buys four outputs instead of one. A lecture can carry highlighted code, LaTeX formulas and video, and every link gets a QR code the room can scan off the wall. For the hour in front of the room there is an overview board, full-text search, live annotation, a timer and seven colour schemes. All of that runs on your own laptop and keeps working with the network unplugged, without a cloud or a service provider.

The slide as projected: heading, sub-heading, the first sentence of each paragraph and the phrases marked bold, in one column.

The same slide with the shortening switched off: all four paragraphs in full, laid out in two columns.

The same four paragraphs, written once. One keypress separates the first two pictures; the third is a different file built from the same source, and the switch marked show: in the second picture’s title bar brings it up. Click any picture to see it full size.

The one-minute version

The argument on this page as a film: what a lecture is made of, what comes out of one file, and what the hour in front of the room looks like. Just under a minute, subtitled. Es gibt ihn auch auf Deutsch.

psi-slides in a minute

The file sits on a server of the chair at the University of Bamberg, not in the repository, and it is fetched only once you press play.

Every lecture has three kinds of text in it

There is what goes on the slide, which has to be sparse enough to read from the back row. There is the script – the full argument, the sentences that actually explain the thing, which belongs in a handout and not on a wall. And there are the notes to yourself: ask the room first, skip this if you are short on time, do not send this out.

The programs people present with give you slides and a notes field. Neither is a place for the script, and the script is the part students want most. The script then goes one of two ways. Either the slides take its job and fill up until nobody can read them from the back row, which is death by PowerPoint. Or the script lives in a second document that stops matching the slides the first time you edit either one.

With psi-slides you write each paragraph once and mark the one sentence that carries the paragraph. The projection gets only that sentence, the handout gets the whole paragraph, and your > note: lines stay on your screen.

everything on the slides

slides, and a script beside them

psi-slides

What the Markdown becomes

This is the Markdown behind the slide in the pictures above. The lecture it comes from is a real one, an introduction to Python built from 36 chunks – a chunk is one heading with the text under it, and each chunk becomes one slide. Two of the four paragraphs are shortened to fit this page.

## free: Why Playwright | the modern web is rendered, not served {.wide #why-playwright}

::: cols 2

**A lot of the web is rendered by JavaScript in the browser.**
**`requests` and plain `urllib` see only the HTML shell** – often just
`<div id="app"></div>` plus a pile of script tags. Useful text, links, and
titles never arrive.

**Playwright drives a real browser** – Chromium, Firefox, or WebKit – over a
debugging protocol. The page renders, scripts execute, the DOM settles, and
then you query it. You see what a human sees.

**For a link scanner this matters a lot.** …

**The cost is weight.** …

:::

::: margin
`requests` is still the right tool for an API that answers in JSON. The
browser is for pages meant to be looked at.
:::

> note: Show the difference live if the room is awake: open a JS-heavy site,
> curl it, and let them find the missing text themselves.

In the projection the two columns fold into one, because four abridged paragraphs do not balance. With the shortening switched off, and in the handout, the author’s two columns stay.

The presenter cockpit: a chapter scrubber across the top, a mirror of the projected slide, the private speaker note below it, a strip of neighbouring slides, and a footer with timer and key legend. — **The cockpit**, opened with `S` from the projection. The `> note:` from the source sits under the mirrored slide, where only you can read it, at a size you set with the two buttons beside the note; the strip shows what is coming. The two windows keep each other in step directly in the browser, with no server between them.

The overview board: the whole 36-chunk lecture laid out as a grid of readable slides, with the current one outlined. — **The whole lecture at once.** Not thumbnails – the real slides, still legible. Drag to move around the board, `Enter` opens the slide you picked.

The search panel over the slide: the query async, and five results, each with its tag, heading and the matching sentence. — **Full-text search**, from anywhere, mid-talk. Each hit shows the kind of chunk, its heading, and the sentence the match sits in.

The handout: the same chunk set as flowing justified prose with hyphenation, the margin note as an aside, and the speaker note in a tinted block beneath it. — **The lecturer’s handout.** The same source set as a document – hyphenated, at a line length made for reading, with the speaker note folded in under its chunk. There are two handouts: `print.html` carries the script alone and is the one to give the students, `print-notes.html` adds the speaker notes and stays with you.

Title slides and dividers

The default is below, the rest one click away. Click a tile to see it full size.

These are a preview, like the figure language below. They are not in the 1.0.0 release, so a lecture that names a cover: or a section: needs the repository rather than the download on the releases page. Getting started has both.

cover: names the title slide. They are ordered quiet to loud.

A title slide with the type set in the lower left third of an otherwise empty slide. — `classic` the type in the lower left third. The default

A title slide with white type reversed out of a full field of deep blue. — `panel` pale type on a full field of the colour scheme’s accent

A title slide where a picture fills the frame and the type is reversed out of a dark gradient over it. — `hero` the picture fills the slide, the type set over a dark gradient

The other seven title slides

A title slide with the title at the top edge, a lede in the middle, and the credits under a rule at the bottom. — `masthead` the title at the top edge, credits under a rule at the foot, and the chunk’s own text between them

A title slide with the whole type block centred on both axes. — `stack` centred on both axes, for an opening that wants to be still

A title slide with the title set very large, filling the upper half of the slide. — `display` the title set large enough to fill the slide, everything else small under it

A title slide that opens on a sentence set large, with the lecture title small underneath it. — `quote` the talk opens on a claim; the title reads as the attribution

A title slide with the type on the left and a picture bled off the right edge. — `split` the type on the left, a picture running off the right edge

A title slide with the title on the left and a three-box diagram inset on the right. — `beside` the chunk’s own content beside the title – so a drawing can be the cover

A title slide with a three-box diagram across the top and the title centred in the band below it. — `above` the same content on top, the title centred in the band below

cover-align: puts the type high, in the middle or low, on the compositions that leave it any freedom. cover-ratio: is a percentage saying how much of the slide the picture gets, on the ones that divide it.

The stack cover with its type block moved down to sit on the bottom margin. — `cover: stack` with `cover-align: bottom`

The beside cover with the diagram given a wider share of the slide than the default. — `cover: beside` with `cover-ratio: 62%`

section: draws the divider slide a new part of the lecture opens with. They are all quieter than any title slide.

A divider slide showing only the part heading on an empty slide. — `plain` the heading alone. The default

A divider slide where the whole slide takes a light tint of the theme accent. — `tinted` the accent at 12%. From the back of a room the colour arrives before any word

A divider slide with the heading between two rules across the measure. — `rule` the quietest, and one that survives a black-and-white print

A divider slide with the heading sitting on a tinted panel. — `card` the heading on a tinted panel

A divider slide with a large accent numeral two above the part heading. — `number` a large numeral above the heading, counting the parts of the lecture

A divider slide listing all three parts of the lecture with the second one set large and live. — `outline` the running agenda: which part, out of how many, and how far in

Everything one lecture can carry at once – a closing slide, dividers carrying a quotation or a photograph or a figure, items laid out as cards, a full-slide photograph that opens up as you press Space – is in the decoration lecture.

Open the lectures yourself

Five lectures are published on this site. python-intro is the one the pictures come from. The tutorial is a self-referential tour that explains the tool by being the tool. The figures lecture draws every construction the figure language has, with figures from a real course among them, and is the worked example behind Figures you write. Decoration shows every construction that puts something other than a text column on a slide – the title slides, the dividers, items laid out as cards, a photograph that opens up as you press Space. The short example is one section of a first-year networking lecture, in German – eighty-odd lines of Markdown, short enough to read end to end beside what it produces (source, set from the lecture notes under CC BY-NC-SA 4.0).

	python-intro	Tutorial	Figures	Decoration	Short example
The projection	audience	audience	audience	audience	audience
The cockpit	speaker	speaker	speaker	–	speaker
The document	print	print	print	print	print
With the notes	print-notes	print-notes	print-notes	–	print-notes

Decoration and Figures both show work that is not in the 1.0.0 release – the title slides, the part dividers, cards and rows, backdrops, and figures written as ::: draw. Both lectures say so on their third slide, and both need the repository to build. Only the projection and the document are published for decoration.

Start with the projection. Arrow keys move between slides, Space brings in the next part of a slide, C switches between the shortened text and the full text, O (the letter, not zero) opens the overview board, / searches, ? lists every key. A cockpit opened from the table above shows the layout but is connected to nothing – press S inside the projection to open one that follows it.

All four files are self-contained: the styling, the scripts, the images, the typeset maths and the typefaces all sit inside the HTML file itself. Nothing is fetched at run time, and the files open just as happily from a folder on disk (file://) as from this server.

Getting started

There are two versions, and they differ in what they can do.

The latest release is 1.0.0. Its source format is fixed, so a lecture that builds today keeps building the same way. Download the .zip or the .tar.gz and unpack it; the tutorial, python-intro and short example listed above are already built inside, so opening lectures/tutorial/audience.html runs the tour with nothing installed. One line does the same without clicking:

curl -L https://github.com/UBA-PSI/psi-slides/releases/latest/download/psi-slides.tar.gz \
  | tar xz

The repository carries work that 1.0.0 does not: figures written as ::: draw, the title slides and section dividers, cards and rows, and the graphical figure editor. If you came here for any of those, this is the version to take. What you give up is the format promise – those parts are still open to change, so a lecture written against them may need an edit when they reach a release.

git clone https://github.com/UBA-PSI/psi-slides

Without git, take Download ZIP from the repository’s green Code button.

Building a lecture of your own needs Node 20 or newer, which is what runs build.js, and nothing else: no LaTeX, no Pandoc, no server, nothing that has to be installed system-wide.

cd psi-slides

# once: the bundled typefaces and the handful of build dependencies
npm install

# build all four views next to source.md, then open the projection
node build.js lectures/tutorial/source.md
open lectures/tutorial/audience.html   # macOS; xdg-open or your browser elsewhere

If you have never installed Node or used a terminal

The steps below take a Windows or macOS machine with nothing installed on it to a built copy of the tutorial.

Install Node

Open nodejs.org. The button offers the LTS build – the long-term support one – in the right file for the machine you are on; take that download. On macOS you get a .pkg: double-click it, click through the installer, give your password when it asks. On Windows you get an .msi: double-click, accept the defaults, and leave the checkbox about tools for native modules alone. Nothing in psi-slides needs them.

If you already use a package manager, brew install node on macOS and winget install OpenJS.NodeJS.LTS on Windows do the same thing.

Open a terminal

On macOS press Command-Space, type terminal, press Return. On Windows open the Start menu and type terminal: take Windows Terminal if it appears, PowerShell otherwise. You get a window with a cursor in it. You type one line, press Return, and it answers.

node --version

The answer is a version number. Anything from v20 upwards works, and a fresh LTS download is well above it. If you instead get command not found or is not recognized, close the window and open a new one: a terminal that was already running when you installed Node has not seen it yet.

Get the files

Take either version from the two above. The release is the one to click if you are not sure; Download ZIP from the repository’s green Code button is the same kind of file and gets you the figures, the title slides and the cards as well. Unpack it the way you would any other download; double-clicking is enough on both systems. You get a folder whose name starts with psi-slides, and that folder is the whole tool. Put it somewhere you can find again, because the terminal has to be pointed at it in a moment.

On Windows, unpack the .zip rather than opening it by double-click: Windows shows the contents of a ZIP as if it were a folder, but commands cannot run inside it.

Point the terminal at the folder

cd psi-slides

The cd line has to name where the folder actually is: on Windows, for instance cd C:\Users\you\Downloads\psi-slides. Instead of typing the path, type cd and a space, then drag the folder from the file manager into the terminal window – the path writes itself.

Fetch what the build uses

npm install

npm install runs once, in that folder, and takes a few seconds. It fetches the typefaces psi-slides embeds into every lecture and the handful of packages the build uses. All of it lands in a node_modules folder beside build.js: nothing is installed system-wide, and the lectures you build fetch nothing when they are opened.

Build the tutorial

node build.js lectures/tutorial/source.md

The same line on Windows and macOS, forward slashes included: Node takes them everywhere. It reports what it embedded – the images, the typefaces, the QR codes, the rendered maths – and ends with what it wrote.

Wrote lectures/tutorial/print.html, lectures/tutorial/print-notes.html, lectures/tutorial/audience.html, lectures/tutorial/speaker.html (11 columns, 59 chunks)

Open it

Double-click lectures/tutorial/audience.html. It opens in your browser and that is all it needs: ? lists the keys, S opens the cockpit. Mail the file to somebody who has none of this installed and it still works.

Linux readers: you have all of these tools already. Distribution packages are sometimes several versions behind, so node --version is still worth running.

The tutorial teaches the tool by being the tool. Press ? for the cheat sheet, S to open the cockpit. Its source.md is the reference for writing your own, and the four files the build wrote are yours to move, mail or upload – they carry everything they need.

Then write your own lecture

# scaffold a folder with valid frontmatter
node build.js --new my-lecture

# rebuild on save, and reload every open tab over a WebSocket
node build.js lectures/my-lecture/source.md --watch

# chunk ids, word budgets, unclosed directives, oversized assets
node lint.js lectures/my-lecture/source.md

Keep the editor, the projection and the cockpit visible at once: --watch rebuilds on every save and reloads both browser windows as soon as the rebuild finishes. At the end, the four HTML files beside your source.md are what you hand over. Nothing else has to travel with them.

A figure is text too

The lecture figures that get out of date are the ones that live in a drawing program. psi-slides has a small language for them instead: a figure is a few lines in the same Markdown file as the slide it sits on, and the build draws it. Apart from the first element, nothing in it is placed at a point on a canvas – each box is placed against another box – so moving one moves everything attached to it, and a figure can be built up in front of the room one step at a time.

A figure from a network security lecture: four boxes in a row, labelled Frame Header, Datagram Header, Segment Header and Payload, with a leader line from each of the first three up to a note naming the addresses that header carries.

One slide from a real course, drawn by the build. Part of its source is below: the four boxes, one of the three notes, and the step that brings that note in. Two things are worth knowing to read them. Lengths are in grid cells, not pixels – the opening line sets the cell to 150 by 54, so w 0.88 h 0.85 is a box far wider than it is tall, and a figure keeps its proportions when the cell changes. And -- fh.cx,fh.top is a leader line: it points the note at a spot on another box, so the line finds its own way and stays attached when that box moves.

::: draw {unit=150x54}
default box {.tone-3 .sharp} w 0.88 h 0.85
box fh "Frame\nHeader"    at 0,0
box dh "Datagram\nHeader" right of fh gap 0 same as fh
box sh "Segment\nHeader"  right of dh gap 0 same as fh
box pl "Payload"          right of sh gap 0 same as fh {.paper}
text lmac "Ethernet source\nand destination\naddresses*"       above fh gap 0.5 -- fh.cx,fh.top {.muted @l1}
step ethernet
  show @l1
  emph fh

This one is a preview. It is not in the 1.0.0 release, so the download on the releases page does not have it. To try it you need the repository itself – either a clone, or Download ZIP from the repository’s Code menu. The Source code (zip) attached to a release is the tagged release and therefore does not contain this preview.

git clone https://github.com/UBA-PSI/psi-slides
cd psi-slides
npm install
node build.js lectures/diagrams/source.md
open lectures/diagrams/audience.html   # every construct, drawn

Being a preview is not only a question of packaging: the source format is still open to change, and a figure you write now may need an edit when it ships. The drawing above comes from lectures/network-security, a real course rebuilt as figures.

Figures you write is the case for the language – what a lecture figure has to do that a drawing program and an auto-layout language each do badly. The manual builds one a line at a time, then lists every statement, the design rules and worked examples, and shows the graphical editor that lets you drag a box on the live slide and have the source rewritten.

Documentation

How psi-slides compares – Beamer, reveal.js, Quarto, Marp, Slidev, PowerPoint and friends, in both directions, including where psi-slides loses.
The figure language – a preview, with the two pages that describe it and what you need to try it.

Source

github.com/UBA-PSI/psi-slides – the README explains the format, and says what the tool is good at and what it is not good at.