training-kit: Build a Complete Training from Numbered Slides and Workshops

Discover training-kit and create-training-kit, two npm packages that turn a folder of numbered Markdown slides and workshops into a Slidev deck, a Starlight workshops site with an online editor, PDFs and ZIPs.

As a trainer, I spend a lot of time writing slides and workshops. And for every training, I ended up rebuilding the same things around the content: a slide deck, a website for the workshop instructions, a PDF of the slides, a PDF handbook, a ZIP of the starters, a ZIP of the solutions… and a lot of manual work every time a chapter was added or moved.

To stop doing that by hand, I built two tools, now published on npm:

In this article, I’ll present what they do and how to use them.

What training-kit Produces

You write Markdown and code. From that, training-kit generates:

  • a slide deck built with Slidev;
  • a workshops site built with Starlight, with one page per workshop and an optional online editor (StackBlitz) loaded with the workshop folder;
  • the deck and the workshops as PDFs;
  • ZIPs: a starter and a solution per workshop, all the solutions, and a participant kit.

There is no list of chapters to maintain: the number at the start of a file name defines its place.

Getting Started with create-training-kit

The quickest way to start is the generator:

npm create training-kit my-training

It also works with the other package managers:

pnpm create training-kit my-training
yarn create training-kit my-training

The generator asks for the title of the training, the author, the stack of the workshops, the language, and whether the workshop pages should include an online editor. Then:

cd my-training
npm install
npm run dev     # the deck and the site, live: http://localhost:3030 and :4321
npm run build   # the deck, the site, the PDFs and the ZIPs, into build/

The printed commands match the package manager you used (pnpm dev after pnpm create, for example), and the new training starts as a git repository.

Everything can also be passed as options, which is handy in a script:

npm create training-kit my-training -- --title "Advanced Vue.js" --author "Jane Doe" --template vue --lang fr --yes

Choosing a Stack

The --template option picks the first workshop and its solution. The deck and the rest of the project are the same for every stack.

Stack The workshop Its tests Online editor
vanilla a form that greets, in app.js none, checked in the browser on
vue the same form as a Vue component, on Vite Vitest + @vue/test-utils on
react the same form as a React component, on Vite Vitest + Testing Library on
node a greet() function to write test by test node --test on
java a Greeter.greet() method, with Maven and JDK 21+ JUnit 6, mvn test off

Each starter contains TODOs that its README turns into steps, and its solution passes its tests. The template is available in English and in French (--lang fr), and --empty creates a project without any example if you prefer to start from scratch.

The Project Layout

Here is what a training looks like:

my-training/
  training.config.mjs
  slides/
    1-introduction.md         chapter 1
    2-reactivity.md           chapter 2
    10-testing.md             chapter 10, after 9: the order is numeric
    _11-draft.md              turned off: kept on disk, left out of everything
  workshops/
    README.md                 optional: the introduction of the workshops
    1-devtools/
      README.md               the instructions
      package.json  src/ …    the starter code
    2-composables/
  solutions/
    1-devtools/               the solution of workshops/1-devtools, same name
    2-composables/

The Numbering Rule

The whole tool relies on a single convention: the number at the start of a name is its place, in the deck, on the site, in the PDFs and in the ZIPs.

  • 1-intro.md, 01_intro.md and 1 intro.md are all read as number 1: any separator, any padding.
  • 10-testing.md comes after 9: the order is numeric, not alphabetical.
  • _3-optional.md is turned off: it is kept on disk but left out of everything.
  • Two entries sharing the same number is an error.

A solution is the folder of solutions/ with exactly the same name as its workshop. The build reports a workshop without a solution, and a solution that matches no workshop, so a typo never silently publishes nothing.

Writing Workshops

The README of a workshop is the single source of its instructions. Its first heading becomes the page title, and the blockquote right under it becomes the page description:

# TP 3 — Routing

> Add a detail page, and keep the back button working.

## Steps

…

Whatever the heading looks like (TP 3 — Routing, Workshop 3: Routing or just Routing), it appears as 3. Routing in the menu: the number always comes from the folder name.

For learners who get stuck, a :::hint block contains help displayed as a collapsed section on the site, and left out of the printed handbook:

:::hint[Stuck on the route parameter?]
Read it with `useRoute().params.id`.
:::

Configuration

The configuration lives in a training.config.mjs file, and only the title is required:

import { defineConfig } from "@emmanueldemey/training-kit";

export default defineConfig({
  title: "Advanced Vue.js",
  author: "Jane Doe",
  playground: true,
  repository: "https://github.com/me/advanced-vue",
  deck: { theme: "seriph", headmatter: { lineNumbers: true } },
});

The playground option enables the StackBlitz online editor on the workshop pages, and repository adds “edit this page” and “browse the folder” links. The deck option accepts any Slidev theme and headmatter.

To add training-kit to an existing project instead of using the generator:

npm install -D @emmanueldemey/training-kit @slidev/cli @slidev/theme-default astro @astrojs/starlight sharp

Slidev, Astro and Starlight are peer dependencies: your training pins their versions, and can move to a newer Slidev without waiting for a training-kit release.

The CLI

training-kit comes with a CLI that covers the whole life of a training, not only the build:

training-kit list                       # what the numbering picks up, and what it leaves out
training-kit check                      # what would break, without building
training-kit new chapter "Forms"        # slides/<next number>-forms.md
training-kit new workshop Routing       # a new workshop and its solution folder
training-kit insert workshop 3 Routing  # insert at position 3, the next ones move one up
training-kit move chapter 5 2           # chapter 5 becomes 2, the ones in between shift
training-kit verify                     # run the tests of every solution
training-kit dev                        # the deck and the site, live, side by side
training-kit build                      # everything, into build/

A few commands deserve a closer look:

  • check reads the project without building it, so it is fast enough for a pre-commit hook or a CI step. It reports duplicated numbers, workshops without a README or a solution, broken relative links and images, and missing slide assets.
  • insert and move renumber files for you. A workshop’s solution folder is renamed with it, and every target is checked before the first rename: on a clash, nothing is renamed.
  • verify runs npm run test in every solution. It is the check to run after a dependency upgrade, to make sure all the solutions still work.

What the Build Produces

training-kit build writes a static site into build/:

build/
  index.html                      the workshops site: the overview
  workshops/<n-name>/             one page per workshop
  resources/                      every download
  slides/                         the deck
  downloads/
    <slug>-slides.pdf             the deck, printed slide by slide
    <slug>-workshops.pdf          the handbook: cover, contents, one workshop per page
    <slug>-solutions.zip          all the solutions
    <slug>-participants.zip       both PDFs and the workshop folders, without solutions
    tp/<n-name>-starter.zip       one workshop, ready to unzip and work in
    tp/<n-name>-solution.zip      its solution

Every workshop page links its starter and solution ZIPs. The PDFs are printed with Chromium from the built deck, one slide per page, which works even for decks with hundreds of slides. If you are in a hurry, training-kit build --no-pdf skips the PDF exports, which are the slow part.

The generated project includes a netlify.toml file, so the training can be deployed on Netlify with nothing else to configure. Any other static host works too, as long as you translate the redirect and header rules.

Conclusion

With training-kit, a training is just Markdown and code in numbered folders. The deck, the workshops site, the online editor, the PDFs and the ZIPs are all generated from the same sources, and the CLI takes care of the numbering, the checks and the solutions tests.

If you write trainings or workshops, give it a try with npm create training-kit, and don’t hesitate to open an issue if something is missing for your use case.

Resources