Skip to main content

Getting Started

This page takes you from nothing to a converted course.

Prerequisites​

  • Node.js 18 or newer. The toolchain declares engines.node >= 18.0.0.
  • An Articulate Storyline .story file. That is the only input format currently implemented — see format support.

Install​

The toolchain is a workspace monorepo. Build it once from a clone:

npm install
npm run build

That produces dist/ for every package, including the oaf binary from @oaf/cli. Link it so oaf is on your path:

npm link -w @oaf/cli

Check it responds:

oaf --version
0.1.0

Look before you convert​

Before converting anything, see what the file actually contains:

oaf inspect my-course.story

inspect prints a tree of scenes and slides. It works by running the same conversion the other commands use, so if a file cannot be read, this is the cheapest way to find out.

Add --slides, --quizzes, or --media for more detail, or --format json to get the whole package as JSON.

Your first conversion​

oaf convert my-course.story

With no other arguments this writes my-course.md beside the input, in Markdown, in full mode, with speaker notes, quizzes, and media references included.

On success it prints a summary:

Summary:
  Title: My Course
  Scenes: 3
  Slides: 24
  Quizzes: 5
  Media files: 18

Choosing a different output​

oaf convert my-course.story --format marp
oaf convert my-course.story --format marp-html
oaf convert my-course.story --format oaf

Or name the output file yourself:

oaf convert my-course.story handbook.md

Read the warnings​

Conversion between formats is rarely lossless, and the converter reports what it could not carry across:

⚠ Conversion completed with warnings
  ⚠ Unsupported object type: drag-drop-panel on slide-014

A warning means the output is missing something the source had. It is not a failure, but it is worth reading before you ship the result.

Where to go next​