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, on purpose – and buys four outputs instead of one. A lecture can carry highlighted code, LaTeX maths 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 themes. All of that runs on your own laptop and keeps working with the network unplugged, without a cloud or a service provider.

what the room sees
The slide as projected: heading, sub-heading, the first sentence of each paragraph and the phrases marked bold, in one column.
what the reader gets
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.

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

What psi-slides does

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.

speaker.html
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.
audience.html · O
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.
audience.html · /
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.
print-notes.html
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.

Open the lectures yourself

Three 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. Both are in English. The short example is one section of a first-year networking lecture, in German – 80 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-introTutorialShort example
The projection audience audience audience
The cockpit speaker speaker speaker
The document print print print
With the notes print-notes print-notes print-notes

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

Download the latest release and unpack it. That folder is the whole tool, and the three lectures listed above are already built inside it: open lectures/tutorial/audience.html and the tour runs, with nothing installed and nothing to set up.

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

Download the latest release and unpack it, the way you would any other download; double-clicking is enough on both systems. You get a folder called 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 (10 columns, 38 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.

On Windows take the .zip from the same releases page. A git clone of the repository works identically – the archive is the same set of files without the version history. If you would rather not click at all, one line does the download and the unpacking:

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

That builds the tutorial: a lecture that teaches the tool by being the tool. Press ? for the cheat sheet, S to open the cockpit. The tutorial’s source.md is the reference for writing your own, and the four files just built 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.

Documentation

  • How psi-slides compares – Beamer, reveal.js, Quarto, Marp, Slidev, PowerPoint and friends, in both directions, including where psi-slides loses.

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.