Onboarding

1. Install Knot

   Install from the VS Code Marketplace or by searching "Knot" in the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X). No other setup is required — Knot manages its own dependencies, including the compiler.

2. Open a Twine project

   Open a folder containing .tw or .twee files. If you don't have a project yet, Knot will detect the empty workspace and offer to initialize one for you via the Knot: Initialize Project command.

   A minimal Twine project needs at least two passages:

   story.tw Knot

   1:: StoryData
   2{
   3  "ifid": "D674C58C-DEFA-4F70-B7A2-27742230C0FC",
   4  "format": "SugarCube",
   5  "format-version": "2.37.3"
   6}
   7
   8:: Start
   9Welcome to your story. [[Continue]]
   10
   11:: Continue
   12You made it!

   The StoryData passage tells Knot (and Tweego) which story format to use — the pinned format-version drives the macro catalog, completions, and diagnostics. The Start passage is where the player begins. Knot auto-detects the format from StoryData and activates the right language features.

3. Build and play

   Click Build in the status bar to compile your project into an HTML file. The first build will prompt Knot to download Tweego and the required story format — this happens automatically, no manual setup needed.

   Click Play to open the compiled story in your default browser. If Watch is off, Play builds first; if Watch is on, Play just opens the already-fresh HTML.

   Triggering actions. All Knot actions are triggered through the status bar buttons at the bottom of the window or the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), prefixed with "Knot:". Knot intentionally does not ship default keyboard shortcuts — they tended to clash with VS Code defaults and other extensions. You can always bind your own via VS Code's Keyboard Shortcuts editor.

4. Enable Watch (optional, recommended)

   Click Watch in the status bar to toggle auto-rebuild on save. When Watch is on, every save of a .tw, .twee, .js, or .css file triggers a rebuild in the background. Build progress appears in the "Knot Build" output channel.

   This is the recommended workflow for active development: turn Watch on, open Play in your browser, edit, save, and refresh the browser.

5. Explore the Story Map and the Sidebar

   Click Story Map in the status bar to open an interactive graph of your project. Nodes are passages, edges are links. Click any node to jump to that passage in the editor. The map updates in real time as you edit.

   The Knot icon in the activity bar (left edge of the window) opens the Knot IDE sidebar with three views: Passage Diagnostics (inspect the passage under the cursor), Variable Tracking (where every variable is set and read), and Project Info (workspace statistics — passage and word counts, format, IFID).

   The Story Map is primarily for visualization and navigation at this time; deeper structural editing from the map is on the roadmap.

Status bar reference

Knot adds five items to the left side of the status bar:

Next steps