Skip to content
Taliesin User Guide

Taliesin

The user guide: how to write, preview, execute and publish a .tmd document, from your first preview to a deployed site.

Why Taliesin

A fast, single-purpose dev server that turns .tmd files into live HTML (blog posts, papers, books, and whole websites) with executable code blocks and an editing loop that updates the instant you save. It reads the Markdown/Pandoc syntax you already know, and makes one trade: do one thing, author HTML, and make the edit loop instant.

Three things it gets right

  • Click-to-source. Every rendered block remembers the line it came from. Ctrl-click (Cmd-click on Mac) anything in the preview to jump straight to its source, even across {{< include >}}d files.
  • Block-level incremental updates. A save re-renders only the blocks that changed. Live canvases (Three.js, {js} cells) keep their state; the page never reloads.
  • No per-edit startup cost. A warm server and a warm Jupyter kernel mean edits show up immediately, and only the cells whose code actually changed re-run.

That loop is the whole product; everything below is what you can put inside it.

This guide is itself a multi-page book built with Taliesin: the Chapters drawer, search (press Cmd/Ctrl-K), live diagrams, and executed code cells included. A companion book, Internals, covers how it works inside, and the Gallery shows one-page demos you can open and poke at.

Get running

taliesin preview post.tmd 4321   # live preview, updating as you save
taliesin build post.tmd          # one self-contained HTML file, code cells executed
taliesin preview blog/           # a directory instead: a whole multi-page site

Open http://127.0.0.1:4321, edit, and watch a single block update in place with your scroll preserved. The server binds to loopback only. Getting started installs the binary and sets up a kernel.

What it is (and isn’t)

Scope

Taliesin renders to HTML only: there is no PDF path and no format matrix. It is one author’s writing workflow, kept small and fast on purpose. Choosing Taliesin is the chapter on what that buys and what it costs.

Start with Getting started. The rest of this guide tours what you can put on a page: the live preview loop, executable content (Python cells), interactive content ({js} cells, 3D graphics), rich writing (math, diagrams, figures, citations), and recipes for books and sites.