Compiling Ink to JSON

The web template doesn’t read .ink files directly. You need to compile (or “export”) your story to JSON first.

Why compile?

Your .ink file is written for humans—it’s easy to read and edit. But browsers and other programs don’t understand Ink syntax. Compiling translates your story into JSON (JavaScript Object Notation), a well-known and clearly labeled format browsers can work with easily.

It’s like turning a manuscript into a published book. The content is the same; it’s just in a format readers can access.

Why this is actually helpful

Compiling isn’t just a format conversion—it’s also a safety check. The compiler analyzes your entire story and warns you about problems:

• Dead ends (paths that don’t lead anywhere)
• Missing knots (links to sections that don’t exist)
• Syntax errors (forgotten brackets, typos in divert targets, etc.)

If there’s a problem, you’ll see an error instead of a broken story. Better to catch these issues now than have a player hit a dead end or a syntax error in your story.

Compiling with Inky

Inky is the official Ink editor. If you’re following the Beginner’s Guide, this is what you’re using.

1. Open your .ink file in Inky
2. Click File > Export to JSON…
3. Save as story.json in your template folder

That’s it. Inky uses the official compiler under the hood.

Tip: You don’t have to write in Inky to use it for exporting. You can write in any text editor you like, then open your project in Inky just to export.

Command Line Options

The following options use the command line (or “terminal”). If you’ve never used it before, stick with Inky above—it does the same thing. But if you’re comfortable with the terminal, or curious to learn, these options give you more flexibility.

> inklecate

inklecate is the official command-line compiler—the same one Inky uses under the hood.

Installing inklecate:

1. Download from the Ink releases page:
   • Windows: inklecate_windows.zip
   • Mac: inklecate_mac.zip
   • Linux: inklecate_linux.zip
2. Unzip the file somewhere you’ll remember

Here you have two options. Run it directly, or add it to your PATH to run it from anywhere on your system.

Run it directly

You can run inklecate from wherever you unzipped it:

/path/to/inklecate -o story.json main.ink

This compiles main.ink (and any files it INCLUDEs) and outputs story.json. It also shows you if there are any errors in your Ink.

Add to your PATH (recommended)

Adding inklecate to your PATH lets you run it from anywhere without typing the full path:

inklecate -o story.json main.ink

On Windows:

1. Unzip to a permanent location (e.g., C:\tools\inklecate\)
2. Search for “Environment Variables” in the Start menu
3. Click “Environment Variables”
4. Under “User variables”, find “Path” and click Edit
5. Click “New” and add the folder path (e.g., C:\tools\inklecate)
6. Click OK, restart your terminal

On Mac/Linux:

sudo mv inklecate /usr/local/bin/
chmod +x /usr/local/bin/inklecate

> inkjs

If you have Node.js installed, you can compile without installing anything else:

npx inkjs -o story.json story.ink

This uses inkjs, a JavaScript port of the Ink compiler.

Workflows for Ink Compilation

VS Code Shortcuts

If you’re using VS Code, you can set up a keyboard shortcut to compile with one keypress—using either inklecate or inkjs.

1. In VS Code, press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
2. Type “Tasks: Configure Task” and select it
3. Select “Create tasks.json file from template”
4. Select “Others”
5. Replace the contents with one of the following:

Using inklecate:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Compile Ink",
      "type": "shell",
      "command": "inklecate",
      "args": ["-o", "story.json", "main.ink"],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

Using inkjs:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Compile Ink",
      "type": "shell",
      "command": "npx",
      "args": ["inkjs", "-o", "story.json", "main.ink"],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

Now press Ctrl+Shift+B to compile. Adjust the paths in args if your files are in different locations.

See the Intermediary Guide for a fuller VS Code setup including syntax highlighting, live preview, and multi-file project organization.

Automated Compilation

The Advanced Guide covers setting up automatic compilation as part of your publishing workflow. Every time you create a release, your story compiles and deploys automatically.

Questions? Open an issue on GitHub.