deck-kit
Build a polished static presentation from a single data file — design first, then website. Use when someone says "/deck-kit", "make a presentation/slide deck/pitch", "build a deck for X", or wants a talk they can run in the browser and deploy to their own server. Produces slides from deck/slides.json with an overview, phone reading mode, PDF export and a second presenter-notes window.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bonesisis--deck-kit)HTML
<a href="/listings/bonesisis--deck-kit"><img src="/api/listings/bonesisis--deck-kit/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/<you>/deck-kit cd deck-kit python3 deck/build.py # slides.json -> deck/index.html (cd deck && python3 -m http.server 4321) # then open http://127.0.0.1:4321/
Edit `deck/slides.json`, rebuild, reload. That's the loop.
**Keys:** arrows / space move · **O** overview · **F** fullscreen · **B** blackout · **H** help · **N** notes window.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 133 lines
- ---
- name: deck-kit
- description: Build a polished static presentation from a single data file — design first, then website. Use when someone says "/deck-kit", "make a presentation/slide deck/pitch", "build a deck for X", or wants a talk they can run in the browser and deploy to their own server. Produces slides from deck/slides.json with an overview, phone reading mode, PDF export and a second presenter-notes window.
- ---
- # Deck Kit
- Turn a topic into a static presentation: one data file, a few layouts, and a
- browser engine that already does navigation, an overview, a phone reading mode,
- a PDF export, and a **second notes window** that stays in sync with the deck.
- The order is deliberate: **design first, website second.** Agree the look
- (colours, type, feel) before pouring in content, because the look lives in one
- tokens file and everything else derives from it.
- ## When to use this
- Someone wants a talk, pitch, or lecture they can present in the browser and host
- themselves — not a Google Slides / PowerPoint file. If they want a `.pptx`, this
- is the wrong tool.
- ## What's in the repo
- ```
- deck/
- slides.json all content (you edit this)
- design/tokens.css the design handoff: colours, fonts, spacing
- css/deck.css layout + transitions
- css/notes.css the notes window
- js/deck.js the engine (don't fork it per deck)
- build.py slides.json -> index.html (stdlib only)
- deploy/ nginx + compose for an Ubuntu server
- tools/smoke.mjs headless checks
- ```
- ## Workflow
- ### 1 · Design (do this first)
- Settle the look before the content. Ask, or decide from the topic:
- - **Mood** — calm/editorial, bold/loud, technical/plain?
- - **One accent colour**, plus a background: light (`--paper`) or dark
- (`--night`). A slide opts into dark with `"theme": "night"`.
- - **Type** — the kit ships system fonts (no download, no licence). Point
- `--font-serif` at a licensed face only if asked.
- Then edit **`deck/design/tokens.css`** — only the raw values under "Brand". This
- one file is the whole design system; don't scatter colours into other CSS.
- Show the user one slide rendered in the new palette before writing all the
- content. That rendered slide *is* the design sign-off.
- ### 2 · Build the content
- Put everything in **`deck/slides.json`**. One object per slide; pick a `layout`:
- | layout | fields |
- |-------------|--------|
- | `title` | kicker, title, statement, lead |
- | `statement` | kicker, title, statement, lead |
- | `bullets` | kicker, title, items[] |
- | `split` | kicker, title, left{head,items[]}, right{head,items[]} |
- | `metric` | kicker, title, metrics[{value,label}], lead |
- | `closing` | kicker, title, statement, lead |
- Every slide may also carry:
- - `"kicker": "Topic · Speaker"` — the part after `·` shows as the speaker chip.
- - `"notes": [...]` — speaker notes for the second window. Prefix a line with
- `## ` for a heading, `- ` for a sub-point, `[like this]` for a stage cue.
- Wrap a number in `**bold**` to make it jump out.
- - `"soll": "1:40"` — the target time for this slide's section; the notes clock
- shows `0:48 / 1:40` and turns the accent colour when you run over.
- Text is HTML-escaped at build time: write `<`, `&`, `"` as themselves. To add a
- layout, add one `lay_*` function in `build.py` and a few CSS rules — don't hand-
- write HTML into slides.json.
- Then:
- ```bash
- python3 deck/build.py # writes deck/index.html
- ```
- ### 3 · Verify
- Serve it (not `file://`) and open it:
- ```bash
- (cd deck && python3 -m http.server 4321 &)
- open http://127.0.0.1:4321/ # or xdg-open on Linux
- node tools/smoke.mjs # headless checks
- ```
- Keys: arrows/space move, **O** overview, **F** fullscreen, **B** blackout,
- **H** help, **N** notes window. The notes window also prints every slide's notes
- at `…/index.html?notes&all`.
- ### 4 · Deploy
- See `deploy/DEPLOY.md`. In short: build, copy `deck/` to the server as
- `deploy/site/`, `docker compose up -d`. During the talk, extend (don't mirror)
- to the projector, **F** on the projector, **N** opens the notes window for your
- laptop.
- ## Lessons baked in — don't relearn them the hard way
- - **A CSS-only change still needs a rebuild.** The CSS/JS links carry a content
- hash (`?v=…`), so without re-running `build.py` a cached browser keeps the old
- file. This is the single most common "my change didn't show up".
- - **The hash is output-only.** The engine writes `#3` to the URL but only reads
- it once, at load. There is no `hashchange` listener. When you test, load each
- slide fresh (`index.html#3` as a full navigation with a changing query), don't
- hash-jump inside one page — nothing will move.
- - **Never add an SPA fallback** (`try_files … /index.html`). A missing file must
- 404. With a fallback, one dropped mount makes every path serve index.html and
- the deck looks replaced.
- - **Notes live in a `<template>`.** A `<template>` is never rendered, so notes
- never leak onto the projected slide or into the PDF. Keep them there.
- - **The notes window couples by BroadcastChannel.** Same browser, same device,
- same http origin only. It does not cross devices and does not work under
- `file://`. An iPad on the same tailnet still won't couple — give it the
- `?notes&all` print page instead.
- - **Don't set `html, body { overflow: hidden }` on the notes window.** The deck
- needs it (a deck doesn't scroll); the notes print view must scroll, and the
- live notes window is a fixed frame where only the middle scrolls.
- ## Privacy when publishing
- If you push a deck built from this kit to a public repo, scrub real content and
- infrastructure first: hostnames, IPs, tailnet names, usernames, SSH key paths,
- and the commit author email (set a repo-local GitHub noreply address). Keep
- `.env`, `htpasswd` and real `deploy/site/` content out of git — the shipped
- `.gitignore` already does.
README.md · README · 80 lines
- # Deck Kit
- Build a polished **static presentation** from a single data file. Design the
- look first, then pour in the content. No framework, no build tool, no
- dependencies — just Python's standard library and a browser.
- The engine already does the tedious parts: slide navigation, an overview grid, a
- phone reading mode, a PDF export, and a **second presenter-notes window** that
- stays in sync with the deck and carries a clock.
- > Replace the example deck with your own. The example is neutral on purpose.
- ## Why
- Presentations are usually locked in a desktop app or a cloud account. This keeps
- one as plain files you own: edit `deck/slides.json`, run one command, open the
- result, host it on your own server. Because it's static, it loads instantly,
- works offline, and deploys anywhere.
- ## Quickstart
- ```bash
- git clone https://github.com/<you>/deck-kit
- cd deck-kit
- python3 deck/build.py # slides.json -> deck/index.html
- (cd deck && python3 -m http.server 4321) # then open http://127.0.0.1:4321/
- ```
- Edit `deck/slides.json`, rebuild, reload. That's the loop.
- **Keys:** arrows / space move · **O** overview · **F** fullscreen · **B**
- blackout · **H** help · **N** notes window.
- ## The two steps
- 1. **Design** — set one accent colour, a light or dark background, and the type
- in **`deck/design/tokens.css`**. That one file is the whole design system.
- 2. **Build** — write slides in **`deck/slides.json`**, pick a `layout` per slide
- (`title`, `statement`, `bullets`, `split`, `metric`, `closing`), add speaker
- `notes` and a target time `soll`. Run `python3 deck/build.py`.
- Full guidance — including the presenter notes format and the design handoff — is
- in [`SKILL.md`](SKILL.md). If you use Claude Code, drop this repo in and the
- skill drives the whole design → build → verify → deploy flow for you.
- ## Prerequisites
- - **Python 3** to build (standard library only — nothing to install).
- - A browser to present.
- - To host it: an **Ubuntu server with Docker**, optionally
- [Tailscale](https://tailscale.com) to keep it private. See
- [`deploy/DEPLOY.md`](deploy/DEPLOY.md).
- - Optional: **Node 18+** for the headless checks in `tools/smoke.mjs`.
- ## What's inside
- ```
- deck/
- slides.json all content — the file you edit
- design/tokens.css design handoff: colours, fonts, spacing, motion
- css/deck.css layout, transitions, overview, help
- css/notes.css the second notes window
- js/deck.js the engine (shared; don't fork per deck)
- build.py generator, standard library only
- deploy/ nginx config + docker compose for an Ubuntu server
- tools/smoke.mjs headless smoke test
- SKILL.md the full workflow (and a Claude Code skill)
- ```
- ## Presenting on two screens
- Extend (don't mirror) your laptop to the projector, open the deck, press **F**
- on the projector and **N** to open the notes window on your laptop. Both windows
- move together. This needs both windows served from the **same http address** —
- a double-clicked file won't couple. Printable notes: `…/index.html?notes&all`.
- ## License
- MIT — see [`LICENSE`](LICENSE). Use it, change it, ship your own decks with it.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.