psi-slides · back to the front page · Diese Seite auf Deutsch
Getting started
A lecture is one text file, source.md. Two ways
turn it into four web pages, the views: the slides for the room, a cockpit
for the lecturer and two handouts. Both write the same four views beside
it.
Option 1: you download an app
that builds the files at the press of a button. Open a
source.md in it and it rebuilds every time you save, or let
New lecture… write a first one. Nothing else has to be
installed and no terminal is needed: the app carries its own copy of
psi-slides.
Option 2: you run the build on
the command line. It starts
with a copy of the repository and one npm install. A server can
then build lectures with nobody watching, and a coding assistant such as
Claude Code finds instructions in the repository
that describe the format to it.
The app
Open a lecture’s source.md, or drop it on
the window, and the four views are built. Leave the window open beside your
text editor and it builds them again each time you save.
One line says whether the last build worked, and four buttons let you open the four views it wrote. There is no project to set up either, and no settings to fill in before the first build.
Under them the window counts what the lecture holds – sections, slides, pictures, drawings, and how many words went to the handout against the speaker notes – so the size of a talk is readable without opening it.
Download it
Take the package for your system from the three below. They belong to the latest psi-slides release, and the app builds a lecture exactly as the command line of the same version does.
Windows 64-bit (experimental)
Installerruns through without a question and starts the apppsi-slides-builder-win-x64.exe
The first start
Windows and Linux are experimental. Those two packages are built automatically and have not yet been started on a real Windows or Linux computer. If you try one, please report in an issue whether it ran. The macOS package has been used on a real Mac.
The packages are not signed, apart from the macOS one, signed and notarised by hand before upload – Apple’s own check. If that signing has not happened yet, macOS warns on a double click that the developer cannot be verified: open it once with a right click and Open instead, and it is gone. Windows shows its SmartScreen warning once – More info, then Run anyway. An AppImage needs to be marked executable first.
What it is, and what it is not
When a build fails, the window shows the build’s own message, naming the line in your source. The four views keep the last build that worked, so a broken save never takes your slides away mid-lecture.
There are two switches. Set Open the views through a local web address and you get a small local server: embedded YouTube and Vimeo players refuse to run from a file and need an address. Under Open the views in you pick Chrome or Edge, the browsers psi-slides is tested in, or whatever your system opens HTML with.
It is not a Markdown editor. You write the lecture in whatever text editor you already use; the window watches the file. There is no split view, no preview pane, no Git client and nowhere to type build commands.
Nor are the two ways two tools: the app runs the same
build.js on the same source.md and produces the
same four views, and Export as PDF… writes the same three PDFs
the command line does. Nothing leaves the computer. No account,
no telemetry, no update check, no network access – and the local web
address above is bound to 127.0.0.1, reachable from this
machine and from nothing else. The window comes in English and German: the system language decides the first time, and a setting changes it afterwards.
Your first lecture
New lecture…, on the app’s start screen and in the File menu, asks for a folder name and a place to put it. It writes a starter lecture there – a title slide, one slide of text and a small figure for the diagram editor to open – and opens it, built. Change the text in your editor and save, and the four views follow.
Help ▸ How to write a lecture opens the tutorial in your browser: a lecture about writing lectures, with its source to copy from.
To have the example lectures on your own computer, take the
release
archive, psi-slides.zip. It holds the five lectures the
front page links to, already built, with their source.md
files beside them. Unpack it and double-click
lectures/tutorial/audience.html; nothing has to be installed
for that.
The command line
The same build the app runs, typed into a terminal. It needs Node 22 or newer and nothing else: no LaTeX, no Pandoc, no server, nothing installed system-wide. Not even git: the clone below is the quickest way to the files, and the release archive holds the same tool as one ZIP.
Build the tutorial
You run npm install once. It fetches the typefaces
psi-slides embeds into a lecture and the handful of packages the build
uses, all of it into a node_modules folder beside
build.js.
The four views appear beside source.md as HTML
files, and they are what you hand over: each one carries its own fonts,
pictures and code, and fetches nothing when it is opened.
Where a PDF is asked for instead,
--slides-pdf writes the slides as one,
--print-pdf and
--print-notes-pdf the two handouts on A4. These
three need a Chromium-based browser: the build looks for one in $PSI_CHROME, then in the Playwright cache, then for a system-wide Chrome. The desktop app prints with its own and needs nothing extra.
git clone https://github.com/UBA-PSI/psi-slides
cd psi-slides
# once: the bundled typefaces and the 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
# the slides as a PDF, one page per step; the two handouts as A4 PDFs
node build.js lectures/tutorial/source.md --slides-pdf
node build.js lectures/tutorial/source.md --print-pdf --print-notes-pdfA lecture of your own
--new writes a lecture folder with
the settings block at the top filled in, a title slide, one slide of text
and a small figure – the starter the app’s New
lecture… writes too. Change it rather than starting from an
empty file.
What goes in it is what the tutorial teaches; a German lecture to copy from is the six-slide example.
# a new lecture folder, settings block included
node build.js --new my-lecture
# build it, rebuild on every save
node build.js lectures/my-lecture/source.md --watchWhile you are writing
Add --watch and the build reruns on every save
and reloads every open tab, so the text editor, the projection and the
cockpit stay visible at once. That is what the app does by default.
--serve is for what a file on disk cannot do:
play an embedded YouTube or Vimeo player. lint.js,
which reads a lecture over before you hand it out, has no button in the app
and lives here.
# rebuild on save, reload every open tab
node build.js lectures/tutorial/source.md --watch
# the same, served over http on this computer, for embedded players
node build.js lectures/tutorial/source.md --watch --serve
# chunk ids, word budgets, unclosed ::: blocks, oversized files
node lint.js lectures/tutorial/source.mdFrom a machine with nothing on it
The steps go from that machine to a built copy of the
tutorial. Work down them in order:
running npm install before the cd installs into whatever folder you were already in.
The app above needs none of this.
If you have never installed Node or used a terminal
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 v22 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 a clone if you have git, and the
release archive otherwise –
psi-slides.zip, attached to the latest release on the
releases page
under that name, with the example lectures already built.
Unpack that ZIP 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-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 installYou run npm install once, in that folder, and it takes a
few seconds. It fetches the
typefaces psi-slides embeds into a 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 open without it.
Build the tutorial
node build.js lectures/tutorial/source.mdThe build reports what it embedded – the images, the typefaces, the QR codes, the rendered maths – and ends with what it wrote. The same line works on Windows and macOS, forward slashes included: Node takes them on either system.
Wrote lectures/tutorial/print.html, lectures/tutorial/print-notes.html, lectures/tutorial/audience.html, lectures/tutorial/speaker.html (12 columns, 61 chunks)Open it
Double-click lectures/tutorial/audience.html. It opens in
your browser, and a browser is all it needs: press ? for the
keys, S for the cockpit. Mail the file to somebody who has none of
this installed and it still works.
Linux readers: your package manager has all of this.
Distribution packages are sometimes several versions behind, so
node --version is still worth running.
Writing with an AI assistant
psi-slides comes with six skills: instruction files that
describe the source format and the engine to a language model. With them, an
assistant can draft a lecture’s source.md from your notes
or revise one you have written. The app or build.js still builds
it, and lint.js says what does not fit the format.
The skills use the open
Agent Skills format: a
skill is a folder with a SKILL.md in it, Markdown under a short
header that names the skill and says when to use it. Anthropic developed the
format and released it as an open standard. The
list of tools at agentskills.io
that read it includes Claude Code and claude.ai, and also Gemini CLI,
OpenAI’s Codex, GitHub Copilot and Cursor, among others. A tool without
skill support can still be given a SKILL.md as instructions,
pasted or attached like any other text.
Download them
The first archive holds all six, for a tool that reads a folder of skills. The single ones are for a tool that takes one skill at a time, such as claude.ai, where each upload is one skill. Two of the six are about writing a lecture; the other four describe how the engine is built and matter mostly to somebody changing psi-slides itself.
Writing a lecture
psi-slides-authoring The source format: chunk types, the::: blocks, reveals, notes and the settings block.
psi-slides-authoring.zip
psi-slides-figures
Figures written as text in a ::: draw block, with the guide to laying one out included.
psi-slides-figures.zip
Working on psi-slides
psi-slides-decoration Covers, section dividers, cards, backdrops and overlays, and how the build draws them.psi-slides-decoration.zip
psi-slides-appearance
Typefaces, themes, the viewer defaults and the style: block.
psi-slides-appearance.zip
psi-slides-media
Video, YouTube and Vimeo players, link addresses with QR codes, the live demo.
psi-slides-media.zip
psi-slides-prompter
The live prompter in the cockpit, its settings and its protocol.
psi-slides-prompter.zip
Where the folders go differs from tool to tool, and each tool’s own documentation says where. The two sections below are examples, for Claude Code and for claude.ai.
In Claude Code
A skill is a folder with a SKILL.md in it.
Unpacked into ~/.claude/skills/, the six are there in every
project on this computer; unpacked into a lecture repository’s
.claude/skills/, they come with that repository.
A running session notices new skills. If the folder did
not exist when the session started, /reload-skills picks
them up. A clone of psi-slides needs none of this: the six are in its own
.claude/skills/.
# all six, for every project on this computer
mkdir -p ~/.claude/skills
unzip psi-slides-skills.zip -d ~/.claude/skills
# or for one lecture repository, run in its folder
mkdir -p .claude/skills
unzip psi-slides-skills.zip -d .claude/skillsOn claude.ai and in the Claude desktop app
Skills there need code execution. Under Settings ▸ Capabilities, Code execution and file creation has to be on; on a Team or Enterprise plan an owner switches it on for the organisation. Then open Customize ▸ Skills, press +, choose Create skill and then Upload a skill, and pick one of the single archives. Repeat for each skill you want, and switch each one on in that list.
Those steps are the ones in Anthropic’s help article; menu names change, and the article is the place to check when one is not where it says. Skills switched on there also load in Claude Code when it is signed in with the same account. The skills name files in the psi-slides repository and give each one’s address; whether Claude can open those addresses on claude.ai depends on the network setting for code execution.
Where to read further
- What psi-slides is The front page: one lecture as the room sees it and as the reader gets it, and why those are the same file.
- How psi-slides compares Beamer, reveal.js, Quarto, Marp, Slidev, PowerPoint and friends, in both directions, including where psi-slides loses.
- Figures you write The case for the figure language, then the manual: one figure built a line at a time, and every statement.
- The repository The README explains the format and says what the tool is good at and what it is not good at.
- Versions
Only a major version may change how an existing
source.mdbuilds. 2.0.0 is one: a lecture written for 1.0.0 may need an edit, and the Breaking list at the head of 2.0.0 in the changelog says which.