Guides

Multi-file decks

Split a long talk across small files and stitch them into one deck at build time. Reuse fragments between decks. Zero runtime weight added.

Split a long talk into files you can reorder

A single index.html is fine until a talk gets long. Past a point you want one slide per file, you want to reorder without scrolling through a wall of markup, and you want to reuse the same intro across two decks. That's what the assembler is for. It runs at build time and emits a plain rikiki deck. Nothing extra ships to the browser.

The manifest

A deck is a deck.config.js (or .json): the theme, the bundle, an optional transition, and the ordered list of parts.

decks/my-talk/deck.config.js
// decks/my-talk/deck.config.js
export default {
  title: 'My talk',
  theme: 'rikiki/tokens.css',      // default · href, relative to the OUTPUT file
  bundle: 'rikiki/dist/index.js',  // default · runtime href, relative to OUTPUT
  transition: 'slide',             // optional · sets transition on deck-root
  lang: 'fr',                      // optional · <html lang="...">
  slides: [
    'parts/cover.html',
    'parts/intro.md',
    'parts/closing.html',
  ],
};

The .js config is loaded as an ES module: add"type": "module" to your package.json, or name the file deck.config.mjs, or use deck.config.json. A project created with npm init -y declares"type": "commonjs", and assemble stops with a message saying exactly that.

theme and bundle are hrefs written into the output file, so they are relative to where the assembled deck lands, not to the config. Omit them and the assembler writesrikiki/tokens.css and rikiki/dist/index.js, the same spelling rikiki init uses for a source deck. Theslides paths are different: they are read at build time and resolve from the config's own folder.

The parts

Two kinds of fragment, picked by extension:

  • .html · one or more deck-* elements, inlined as-is.
  • .md · one file, one or many slides. A line that is just --- splits the file into separate slides. Each chunk becomes a deck-feature with a deck-md inside. Use *** for a rule inside a slide.
parts/cover.html
<!-- decks/my-talk/parts/cover.html -->
<deck-cover brand="my-talk" speaker="You">
  <h1>Hello</h1>
  <p class="sub">One slide per idea, one file per slide.</p>
</deck-cover>
Live preview · slide canvas
parts/intro.md
<!-- decks/my-talk/parts/intro.md · one file, many slides -->
## First slide

Plain markdown. One idea here.

---

## Second slide

A line with just `---` starts a new slide.
Use `***` if you want a rule inside a slide.
Live preview · slide canvas

Build it

Point the assembler at the config. It concatenates the parts inside onedeck-root and writes the deck next to the config. The config path and the optional output path are both resolved from the directory you run the command in, so run it from the deck's folder or give it paths from wherever you are.

assemble
cd decks/my-talk               # config and output paths resolve from here
npx rikiki assemble deck.config.js

# explicit output, or - for stdout
npx rikiki assemble deck.config.js out/my-talk.html

# with no output argument: <title>, slugged, next to the config
# my-talk.html · a normal rikiki deck

The output is a normal rikiki deck. Open it in a browser, serve it from any static host, present it. Reorder the slides array, run the command again, and you've got the new order.

Checking and bundling an assembled deck

The output is an ordinary deck, so the delivery commands apply to it unchanged: rikiki check reports what is wrong before a rehearsal, and rikiki bundle folds the deck into a single self-contained file. Both are covered in Check & deliver.

Bundling has one condition: the deck must reference rikiki with therikiki/... path style the bundler rewrites, which is what the assembler writes when theme and bundle are left out. Point them at bare ../../ relatives instead and the deck still serves on its own, but assemble prints a note on stderr saying those references will stay external.

Next

  • Recipes · slide patterns to reuse across the decks you assemble.
  • Check & deliver · assemble, check and bundle from the command line.