psi-briefing – a generator for briefing decks

Some readers would rather have slides

A report and a deck can carry the same argument, and which one lands better is a preference rather than a ranking. Some people read a running document and take it in. Others want the same content in frames they can scan, step through and come back to. What matters is that the reader gets the version they will actually read.

psi-briefing exists so that creating a deck takes about as long as writing the report would have. Writing the report is the cheaper of the two because you only have to say the thing. Slides ask for that and then for a second job on top: deciding how each thought is split across frames and arranged inside one.

That second job is where the time goes, and it usually goes one of two ways. Either you fall into moving boxes by the pixel, which can absorb an afternoon per slide, or you stop early and end up with slides that look slapdash and pull attention away from what they say. This tool takes that job off you: you keep writing, and the arrangement is decided from what you wrote.

The first deck of this kind was a report from the Chair of Privacy and Security in Information Systems on a student-orientation portal the chair had built, written to be read rather than presented. It is online as Werkstattbericht Studienstart, in German only. psi-briefing is the layout machinery taken out of it.

Most of the decisions are made for you

psi-briefing is quick because the converter decides most things for you: the structure of your Markdown picks the component for each slide. A component is a ready-made slide arrangement, a grid of cards or a two-column split. You set no widths, place no boxes and fill in no template, and the defaults are set so that ordinary cases come out well with nothing specified.

What you give up is fine control. If one panel has to be exactly two centimetres narrower than its neighbour, this is the wrong tool and Keynote is the right one. Most decks never need that control, and the ones that do are easier to build by hand than to describe.

An AI assistant can finish the deck, because the output is HTML

The file the converter writes is ordinary HTML, and every part of a slide is named in the markup, so adjusting one slide by hand means editing one piece of text. That also makes the deck something you can hand to an AI assistant directly, with nothing to export or convert first.

Two of the documents in the repository are written for machines rather than for people. The component catalog is long and repetitive on purpose, because a language model choosing between components needs every one of them spelled out; and the Claude Code skill packages the catalog plus the checks, so an AI assistant can build a deck from your notes and then audit its own work against the same rules a person would apply.

Neither is required. Point an AI assistant at the example deck and the tutorial source and the assistant can generally work the format out from those two alone: the input is Markdown, the output is readable HTML, and the class names say what they are. The decks are the specification. The catalog and the skill only save the assistant the guessing.

You write; the converter picks the layout

The converter reads how your Markdown is arranged and picks the slide layout from that. Four headings at the same level become a bordered grid, because they are four points of equal weight. A quotation becomes the highlighted band across the bottom of the slide, because that is where a slide's conclusion goes.

## Four roles on an exam

### Candidates
They sit the exam.

### Examiner
Owns the paper.

### Invigilators
Set up and watch.

### Technical lead
Knows the system.

> Who leads is settled **before**
> the exam day.

Four roles on an exam

CandidatesThey sit the exam.

ExaminerOwns the paper.

InvigilatorsSet up and watch.

Technical leadKnows the system.

Who leads is settled before the exam day.

The slide in this figure is not a picture. It is a 16:9 box built the same way a real slide is, so it rescales with this page the way a deck rescales with its window.

See it

Two slides from the example deck, as they come out.

The example deck’s title slide: a headline in a serif display face on deep blue, a row of three figures, and a white card headed In one sentence. — The title slide. The card on the right is the deck’s one-sentence summary, and the three figures under the headline come from a list in the Markdown.

A slide with a bar chart of commits per week, three dashed milestone markers labelled Kickoff, Feature freeze and Launch, and a phase band underneath reading Explore, Lull, Push. — A chart slide. The browser draws the chart as the deck opens, and takes the colours from the theme at that moment, so the chart matches whichever theme is loaded without being told.

Open the example deck Open the tutorial deck

One HTML file each, and not a preview: save either file and it still opens with the network unplugged. The example is a project retrospective. The tutorial teaches the format by being written in that format, with the Markdown beside the result on every slide.

Getting started

Download the ZIP from the latest release and unpack it, then run the converter on your Markdown. The one thing you need installed is Node, the program that runs the converter, in version 18 or newer. Git is not needed.

cd psi-briefing-1.1.0
node tools/md-to-deck.mjs my-deck.md -o my-deck.html
node tools/build-deck.mjs my-deck.html -o send-me.html

If you have never installed Node or used a terminal

The steps below take a Windows or macOS machine with nothing on it to a finished copy of the example deck, Project Aurora.

Install Node.js

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-briefing needs those tools.

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 v18 upwards works, and a fresh LTS download is well above that. 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 ZIP from the latest release and unpack it, the way you would any other download. Double-clicking it is enough on both systems. You get a folder named after the version, such as psi-briefing-1.1.0, and that folder is the whole tool. Nothing else has to be installed, and no account is needed.

Put the folder somewhere you can find again, because the terminal has to be pointed at it in a moment. Your home folder or the desktop is fine. On Windows, unpack it rather than opening the ZIP by double-click: Windows shows the contents of a ZIP as if it were a folder, but commands cannot run inside it.

Git is not needed for any of this. If you already use it, git clone https://github.com/UBA-PSI/psi-briefing.git gets you the same files under the name psi-briefing, and every step that follows is unchanged apart from that name.

Build the example deck

cd psi-briefing-1.1.0
node tools/md-to-deck.mjs examples/example-deck.md -o examples/aurora.html

The first line is what points the terminal at the folder you unpacked, so it has to name where that folder actually is: on Windows, for instance cd C:\Users\you\Downloads\psi-briefing-1.1.0. Instead of typing the path, drag the folder from the file manager into the terminal window after typing cd and a space, and the path writes itself. The second line is the same on Windows and macOS, forward slashes included: Node takes them everywhere. The converter reports what it built, then a table of the slides and how full each one is.

md-to-deck: 13 slides -> examples/aurora.html

Write the example deck into examples/, because that is where its Markdown expects the stylesheet: the top of example-deck.md names the paths, and they are written from that folder. Your own deck is simplest at the top level of the unpacked folder, next to the framework and themes folders, because that is where a deck looks for them unless its Markdown says otherwise.

The deck you just built still needs the two folders beside it. One more step folds them in:

node tools/build-deck.mjs examples/aurora.html -o aurora.html

That line is the same on Windows, macOS and Linux. It folds the stylesheet, the script and any images into the HTML, then checks that nothing in the file still points outward, and reports the result. You will also see tools/build-deck.sh in the README: that is the same thing under its older name, and it needs a shell that Windows does not have by default. The build-deck.mjs line needs nothing but Node.

Look at the deck

Double-click aurora.html. It opens in your browser and that is all it needs: unplug the network, mail the file to someone who has none of these tools installed, it still works.

The deck in examples/, the one that still needs the folders beside it, is the one to view through a local web server: browsers differ in what they let a page load when you open it straight from a folder rather than over the network. Run python3 -m http.server 8000 in the repository folder and open http://localhost:8000/examples/aurora.html. On Windows the command is usually py -m http.server 8000; if Python is not there at all, build the single file and open that instead.

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

There is nothing to install besides Node itself: no package manager step and no libraries to fetch. The same holds at the other end, by design: the deck you build is the thing you distribute, and it carries no trace of the tool that made it.

What the converter writes is a linked deck: it still needs the stylesheet, the script and the image files that sit around it, so it travels only as a folder. One more step folds all of those into the deck itself. That gives you the self-contained version, the single file with everything inside it, and the step ends by checking that nothing in the file still points at something outside. This is what that step prints for the example deck:

$ node tools/build-deck.mjs examples/example-deck.html -o /tmp/deck.html
3/3  verify       checking for anything still external

built   /tmp/deck.html
        0.02 MB linked  ->  0.13 MB self-contained
        no external references: opens with no server and no network

One check this cannot do without a browser: open the file and confirm
  performance.getEntriesByType('resource').filter(e => !e.name.startsWith('data:'))
is empty, and that no image is broken.

That last check comes out empty on this page as well. Every screenshot on this page, and the icon in the browser tab, is written into the HTML rather than loaded from anywhere, so your browser fetched nothing to show you this page but the page itself.

How you write a deck

A Markdown file and one command. What comes out is an ordinary web page, plain enough to edit by hand, so you can adjust a single slide afterwards.

node tools/md-to-deck.mjs deck.md -o deck.html
python3 -m http.server 8000        # then look at it

node tools/build-deck.mjs deck.html   # one file you can send

What you get back

The deck, and a report of which rule fired on each slide. Every line of the report below is one slide of the example deck: its number, how full it came out, the layout that was picked, and its heading. The percentage is roughly how much of the slide the content covers, and the Markdown reference says what each rule needs and how that number is measured. The lines reading directive: are slides where the Markdown named the layout outright instead of leaving it to be worked out.

$ node tools/md-to-deck.mjs examples/example-deck.md -o /tmp/x.html

md-to-deck: 13 slides -> /tmp/x.html

    1    –            title                               Project Aurora: shipping a portal in ele
    2   89 %          single panel                        What this file is
    3    –            divider                             How the timeline went
    4  100 %          facts grid (bold numbers)           The numbers
    5~  84 % gap 11 %  timeline from 2-column table        Plan against reality
    6  100 %          directive:chart                     Commits per week
    7    –            divider                             How it was built
    8  100 %          4 cards -> .net grid                Four areas of work
    9   97 %          directive:delta                     What changed for the user
   10   93 %          flow steps (ordered, bold leads)    The weekly rhythm
   11    –            divider                             What we learned
   12~  61 % gap 34 %  directive:principles                Two ways of working
   13~  83 % gap 15 %  directive:editorial                 Three lessons

  estimated median row fill: 93 % (target 85 %)

Then what the converter fixed by itself, and what it cannot fix for you:

      78 %  2 cards -> two columns            How a commit is counted
       fix   short row (78 %) -> cols--center; balances the gap, does not fill it
  typography: 6 marks normalised
  layout: 1 correction(s) applied

  thin rows - these need content, which no tool can invent.

The converter rearranges content and splits slides. It will not stretch a box just to close a gap: that took one deck from 74 % to 96 % fill and made the deck worse (§1 of the write-up).

Slides that fit any screen, colours in one file

The same deck holds its proportions on a laptop screen and on a lecture-hall projector, and you can change every colour in it by editing one small file. This is the technical section, and it says how both of those work.

Container-query scaling

The layout scales with the slide rather than being fixed to it. Every slide is a 16:9 box with container-type: size, and everything inside is measured in cqw and cqh – never px, never rem.

Every gap and every type size keeps its proportion, so nothing has to be re-tuned when the deck moves to a different display.

Semantic design tokens

Every colour and face is a CSS custom property, a named variable, and the name states a meaning rather than a value: --accent, --ink, --highlight.

A theme is a :root{} override and nothing else. The charts the browser draws read those same names as they draw, so a chart takes on the new colours with the deck around it.

To recolour a deck you edit one file. Four of its lines, from themes/bamberg.css:

  --accent:      #00457D;
  --highlight:      #FFD300;
  --paper:      #ffffff;
  --ink:        #1a1a1a;

The dark theme that ships with psi-briefing, themes/midnight.css, sets those same four names to #7aa2f7, #e0af68, #16181f and #e6e8ef, and runs to 50 lines. Copy either theme file, change the values, and load your copy after briefing.css.

When not to use psi-briefing

It fits content that is already document-shaped: a retrospective, project documentation, a research summary, lecture notes, a report with numbers in it. Those arrive with their sections and comparisons already in an order their author chose.

psi-briefing is a poor fit for a sparse spoken talk, the kind that runs on timing and on setting up a question before answering it. A conference keynote was built this way once and resisted both treatments: dense, the slides argued with the talk; sparse, they were empty frames with one sentence on them. The argument was in what the speaker said, and slides meant to be read on their own could not carry it.

There is also no animation model beyond click-to-reveal panels, and no speaker view. For either, use psi-slides.

How psi-briefing compares

Letting a tool choose the layout from a Markdown file is not a psi-briefing invention. The table below is the short version; the full comparison names the case where each alternative is the better choice.

Tool	Layout	The artefact	Speaker view
psi-briefing	inferred from content shape	one self-contained file	no
iA Presenter	analysed and chosen for you	HTML package, PDF, PPTX	yes
reveal.js	you specify it	a folder, or a server	yes
Marp	CSS themes	HTML, assets not bundled	via tooling
LaTeX Beamer	frames and templates	PDF	with a second file
PowerPoint / Keynote	you place things	.pptx / .key	yes

iA Presenter, in particular

iA Presenter does the same kind of thing: it analyses a slide’s content and picks a layout. The difference is the default. In iA Presenter the document is a script – an ordinary paragraph is what you say, and you indent one to promote it onto the slide, so what the audience sees is the exception you opt into. In psi-briefing there is no speaker and nothing to demote: everything is on a slide, and the converter asks how the content is arranged rather than which part of it to show.

Which makes iA Presenter a closer relative of psi-slides than of psi-briefing. If you are going to stand up and talk, iA Presenter is a mature, well-designed product, and psi-briefing is not a serious competitor to it.

Read further

The repository MIT licensed, and it depends on nothing: the tools are plain Node scripts, with no libraries to fetch.
Writing a deck in Markdown Which shape becomes which component, what the converter corrects, and what the fill percentage in the report actually measures.
The component catalog All 33 slide arrangements with the HTML for each, ready to copy, and the reasoning behind the ones that are easy to misuse.
What building a real deck taught us Every fault that actually occurred, with the measurement that found it, and the faults no measurement caught.