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

Taliesin is 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 as soon as you save. It reads the Markdown/Pandoc syntax you already know and outputs HTML only.

The edit loop

  • Click-to-source. Every rendered block records the line it came from. Ctrl-click (Cmd-click on Mac) anything in the preview to jump 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 an edit shows up without waiting for either to start, and only the cells whose code changed re-run.

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          # post.html beside the source, code cells executed
taliesin preview blog/           # a directory instead: a whole multi-page site

Open http://127.0.0.1:4321 and edit the source. The block you changed updates in place and your scroll position is preserved. The server binds to loopback only. Getting started explains how to install the binary and set up a kernel.

What it is (and isn’t)

Scope

Taliesin renders to HTML only and has no PDF output. It is one author’s writing workflow, kept small and fast. Choosing Taliesin is the chapter on what that buys and what it costs.

Start with Getting started. The rest of this guide covers 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.