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.
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.
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 same argument 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.
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.
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.
> 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.
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-intro | Tutorial | Short example | |
|---|---|---|---|
| The projection | audience | audience | audience |
| The cockpit | speaker | speaker | speaker |
| The document | |||
| 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 elsewhereIf 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 --versionThe 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-slidesThe 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 installnpm 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.mdThe 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 xzThat 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.mdKeep 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.