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.

Why

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
export default {
  title: 'My talk',
  theme: '../../tokens.css',       // href, relative to the OUTPUT file
  bundle: '../../dist/index.js',   // rikiki bundle, relative to the OUTPUT file
  transition: 'slide',             // optional · sets transition on deck-root
  slides: [
    'parts/cover.html',
    'parts/intro.md',
    'parts/closing.html',
  ],
};

theme and bundle are hrefs written into the output file, so they're relative to where the assembled deck lands, not to the config.

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, reveal.js style. Each chunk becomes a deck-feature with a deck-md inside. Use *** for a rule inside a slide.

<!-- 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>

<!-- 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, reveal.js style.
Use `***` if you want a rule inside a slide.

Build it

Point the assembler at the config. It concatenates the parts inside one deck-root and writes the deck next to the config.

# from the rikiki checkout
node build/vite-deck.mjs decks/my-talk/deck.config.js

# or the npm script
npm run deck decks/my-talk/deck.config.js

# writes decks/my-talk/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.

Bundling an assembled deck

Want a single self-contained file? bundle.mjs takes an assembled deck the same as any other, on one condition: the deck has to reference rikiki with the rikiki/... path style that the bundler rewrites (the way the examples/ decks do). A deck that points at rikiki with bare ../../ relatives serves fine on its own but won't bundle. Set theme and bundle in the config accordingly when single-file export is the goal.