1 Getting started

1.1 Install

Download the binary for your platform from the releases page, verify it against the .sha256 published beside it, and put it on your PATH. Windows is not supported. That is the whole install: one self-contained binary with KaTeX, its fonts, the syntax definitions and every bundled script inside it, so nothing is fetched at runtime and there is nothing else to set up.

Taliesin also builds from source with a Rust toolchain, which is always supported:

cargo build --release

A first build takes a couple of minutes and produces the same binary at target/release/taliesin. Put it on your PATH (a symlink, or a small wrapper script that rebuilds on source changes before running it) so you can just say taliesin preview … from any directory. Every command below works either way: substitute cargo run -p taliesin-server -- for taliesin if you’d rather not install it on PATH.

1.2 Set up a kernel (for code execution)

Prose, math, diagrams, and {js} cells need no setup. To execute {python} cells you point the server at a Jupyter kernel. A one-time setup:

python3 -m venv .venv && . .venv/bin/activate
pip install ipykernel numpy matplotlib   # + whatever your cells import
export TALIESIN_PYTHON="$(pwd)/.venv/bin/python"

A document’s {python} cells run against one warm kernel, reused across edits. Without a kernel, cells render as highlighted source and the preview shows a quiet “kernel unavailable” note instead of failing, so you can start writing now and add a kernel later. Streaming output, caching and the silence cap are in Executable content.

TALIESIN_PYTHON is the only environment variable most projects ever set. Every other one the server reads is tabled in the CLI reference, and none is required to start; taliesin help prints the same list.

1.3 Scaffold a project (the fast path)

The quickest way to a previewable project is init, which scaffolds one into a directory (the current one by default):

taliesin init my-site        # _site.yml + index.tmd + posts/my-first-post/index.tmd
taliesin preview my-site     # live, immediately

You get three files and nothing else: a minimal _site.yml, a hello-world index.tmd whose listing: collects posts/, and one dated post under posts/my-first-post/. Every larger shape is an edit to those, which the CLI reference spells out. init refuses to overwrite: if any of them already exists it stops without touching anything.

1.4 Your first document

Create hello.tmd:

---
title: "Hello, Taliesin"
toc: true
---

# Introduction

A paragraph with **markdown**, inline math $a^2 + b^2 = c^2$, and a diagram:

```{mermaid}
flowchart LR
  write --> preview --> publish
```

# Compute

```{python}
import numpy as np
np.random.default_rng(0).normal(size=5).round(2)
```

Preview it live:

taliesin preview hello.tmd

Open http://127.0.0.1:4321. Edit the file and watch only the changed block update in place. Ctrl-click (Cmd-click on Mac) any block to jump to its source line in your editor.

1.5 Build for publishing

When you’re happy, build produces output (executing code cells against the kernel, so the HTML carries the computed figures):

taliesin build hello.tmd                 # -> hello.html (one self-contained file)
taliesin build hello.tmd --out dist      # -> dist/index.html + copied local assets

Point build/preview at a directory instead and you get a whole multi-page site or book (see Recipes):

taliesin build blog/         # -> blog/_site/  (one .html per page)
taliesin build docs/         # -> docs/_book/  (a book, if _site.yml says so)

1.5.1 Where the build goes

A site/book build (and the --out form) copies the local files your pages reference (images, audio, videos, vendored scripts) next to the HTML and leaves behind what isn’t deliverable (the source files nothing links to, and anything whose name starts with _ or ., so _freeze/ stays out), so the output folder is self-contained and you can copy or rsync it as-is. A built-in 404.html is emitted unless you supply your own 404.tmd. The full set of flags is in the CLI reference; common build-and-deploy patterns live in Recipes.

1.6 Publish it

Run taliesin build <dir> --check-only first, wherever you deploy from. A plain build writes the page and exits 0 even when a cross-reference resolves to nothing or an image is missing, by design; --check-only is the verb that turns those into a non-zero exit, and it writes nothing. The two-stage form is in the CLI reference.

The output is plain static HTML + assets with no server runtime, so on any host you control you upload the folder as-is. On GitHub Pages, build into docs/ on your default branch or publish _site/ as the Pages artifact. On a host that builds for you (Netlify, Vercel, Cloudflare Pages), install the binary in the build command (cargo install --git https://github.com/AJBogo9/taliesin --locked taliesin-server), then run taliesin build <dir> --check-only && taliesin build <dir> and set the publish directory to the emitted _site/ or _book/. A hosted builder has no Python of its own: install one plus ipykernel and set TALIESIN_PYTHON in that same command, or {python} cells ship as highlighted source.