3 The live preview loop

What survives a save (scroll position, kernel state, a running canvas) and how Ctrl-click jumps from the page back to the line that made it.

Taliesin is built around the edit loop: change the source, and the preview reflects it immediately, without reloading the page, losing your scroll, or resetting any live content already on screen. See Section 2.2 for what “immediately” is in milliseconds.

3.1 Incremental updates

On every save the server re-parses the document, diffs the new block list against the old one by content-hash id, and pushes only the blocks that changed over a websocket. An unchanged block is never touched, so:

your scroll position is preserved,
a running {js} cell or Three.js canvas keeps its state,
the page never flashes white.

The block you just edited pulses briefly when it re-renders, so you can find the change at a glance.

3.2 Click-to-source and editor sync

In the browser preview, a plain click browses normally; Ctrl-click (Cmd-click on Mac) any block to open its exact source line in your editor (including across {{< include >}}d files) via a vscode:// deep link. The client also speaks a tali-goto / tali-cursor postMessage protocol, so an editor can host the preview and add cursor sync without forking anything. The in-repo VS Code companion (editor/vscode/) is that host.

Click-to-source is VS Code only

The deep link is vscode:// and there is no configuration key for it, so Ctrl-click does nothing in Neovim, Helix or Zed. Those editors get everything taliesin lsp serves and the live preview itself. Only the jump from the page back to the editor is limited to VS Code.

Getting the companion. It is not on the VS Code Marketplace or Open VSX. Each release from v1.1.0 on attaches it as taliesin-companion-<version>.vsix on the releases page; download that file and install it:

code --install-extension taliesin-companion-<version>.vsix

To build it from a clone instead (this needs Node):

cd editor/vscode && npm install && npm run build && npx @vscode/vsce package
code --install-extension taliesin-companion-<version>.vsix

Then make sure the taliesin binary is on your PATH, or point the extension’s taliesin.path setting at it.

A chapter of a book previews as the book. Open the preview on any page that lives under a _site.yml and the companion serves the whole project and opens it at that page’s URL, so you get the nav, the breadcrumb and working cross-page links instead of an orphan page. One server serves every chapter: opening a second one reveals the preview you already have, moved to that chapter. Moving your cursor into another chapter’s file moves the preview to it too, and Ctrl-clicking a block resolves against the page you are looking at, not the one you opened.

The other direction, editor to preview, is split. Moving your cursor marks the matching block in the preview but does not move the page, so scrolling somewhere to compare two figures survives your next keystroke. When you do want the preview to come to you, press Ctrl+Alt+J (Taliesin: Reveal Cursor in Preview), which scrolls it there and leaves the keyboard focus in your editor.

Reuse the editor tab instead of opening a new one

If repeated Ctrl-clicks from a browser preview open new tabs instead of moving the cursor in the tab you already have, add "workbench.editor.revealIfOpen": true to your settings.json. The companion does not need it.

3.3 What the editor does while you write

Completion for front-matter keys and values, cell options and their values, cell languages, div classes, cross-references, citations, shortcode names, anchor ids, math commands, and file paths anywhere a path is legal.
Div attributes, narrowed to the class you wrote. ::: {.callout-note offers title= and collapse=, the two a callout reads; a plain div offers layout-ncol= and neither of those.
Lists and blockquotes continue on Enter, keeping the marker you chose (-, *, +, >, and task items). Pressing Enter on an empty item is how you leave the list.
_site.yml completion is your YAML language server’s job, not Taliesin’s: the config schema is a file you point it at with one comment line, the same step in every editor (see Configuration).

3.3.1 What the document’s structure gets you

Neither of these needs a preview window open, and neither is specific to VS Code: they are LSP features, so cmd = { "taliesin", "lsp" } gets them in Neovim, Helix or Zed too.

Folding follows the document’s own structure instead of indentation. Front matter, each heading down to the next of equal or shallower level, ::: divs and code fences each fold as a unit, so you can collapse a chapter to its headings.
Go to definition crosses files. F12 on @sec-priors jumps to the chapter that defines it, whichever file that is. Your open buffer takes precedence: an anchor you just typed and have not saved resolves to where you typed it, never to the older copy on disk. Hovering a cross-chapter reference names the page that defines it, since the number belongs to that page and is not known here.

3.3.2 Checking the pages you have not opened

The language server only sees files you have opened, so the squiggles miss every other page. Run the project lint in the terminal instead:

taliesin build . --check-only

Every located line it prints is clickable in VS Code’s integrated terminal, straight to the file and line, whether or not that page has ever been open.

Every live preview carries a small dev menu: a </> button tucked in the bottom corner of the page. It belongs to the preview only, so a static build never ships it.

The button itself is a connection light: a coloured dot that reads live while the websocket is connected, reconnecting while the server restarts, and error on a failed render or while an error stands among the diagnostics (each is marked error or warning exactly as build --check-only reports it). A small badge appears on it when there are diagnostics waiting.

Click it to expand a panel with the preview-only tools:

Status and a live word count for the prose.
Restart kernel: drops the warm Jupyter kernel and re-runs every cell against a fresh one. Reach for it when the kernel wedges, or after you fix TALIESIN_PYTHON or install a missing package and want a clean replay.
A reminder that Ctrl-click (Cmd-click on Mac) opens any block’s source in your editor.
A theme toggle (light/dark), for the preview only: see Theming for what a reader’s built page does instead.
The diagnostics list (detailed below), each entry click-to-source, with the button’s badge tracking the count.

3.5 Live-edit feedback

The preview reports what is happening, so you do not have to watch the terminal:

A non-fatal problem (a broken {{< include >}}, a missing kernel, a typo’d extension, a broken [@citation] or @cross-reference) appears in the dev menu’s diagnostics list.
A broken front matter points at the bad line: the diagnostic shows a small code frame and is clickable to open that line in your editor.
A failed render throws a prominent, dismissible error overlay over the last good content, so a broken save is impossible to miss. It clears on the next successful render.
The watcher follows the whole document, not just the served file: editing an included subsection, a .bib or an image re-renders the pages that use it, and so does creating one a page names but could not find yet.

3.6 Reading on any screen

The reading layout is responsive: wide tables, long code, display math and embedded canvases scroll within their own box instead of stretching the page, motion honours prefers-reduced-motion, and on a phone the table of contents leaves the sticky sidebar and appears inline after the article.

The preview binds to loopback only, so it is reachable from the machine running it and nowhere else. To read a draft on a phone, build it and serve the folder from somewhere both devices can see.

Pressing Cmd/Ctrl-P gives a clean print/PDF: the dev menu, the TOC handle, and any diagnostics are hidden, the palette forces light, and content flows full width without clipping code, tables, or math.