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; the README has the commands and the platform table. Windows is not supported. The binary is self-contained, 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:

git clone https://github.com/AJBogo9/taliesin && cd taliesin
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 will do) so you can run 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 need a Python with a Jupyter kernel. A one-time setup, in your project directory:

python3 -m venv .venv
.venv/bin/pip install ipykernel numpy matplotlib   # + whatever your cells import

Taliesin finds a .venv in the project directory, or in a parent directory up to the repository root, with no configuration; taliesin doctor shows which Python it picked. (On Debian and Ubuntu, python3 -m venv needs the python3-venv package.)

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 “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.

To use a Python outside the project, set TALIESIN_PYTHON to it. Every environment variable 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 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/. A larger project is an edit to those files, which the CLI reference spells out. init never overwrites: 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 file; local images stay beside it)
taliesin build hello.tmd --out dist      # -> dist/index.html + copied local assets

Point build/preview at a directory instead and you get a 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, editor and merge leftovers such as index.tmd~, #index.tmd# and .orig, a folder whose only pages are drafts, 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 file a page references is copied even from an _-prefixed folder such as _images/ or a draft’s folder; one under a .-prefixed folder never 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. By design, a plain build writes the page and exits 0 even when a cross-reference resolves to nothing or an image is missing. --check-only 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, publish _site/ as the Pages artifact, or build into docs/ on your default branch with --out docs. A branch deploy runs Jekyll, which leaves out every folder whose name starts with _, including _assets/ with the stylesheets and scripts, so add an empty .nojekyll file to docs/; a rebuild into docs/ leaves it alone.

On a host that builds for you (Netlify, Vercel, Cloudflare Pages), download the Linux binary in the build command (the README’s install commands with TARGET=x86_64-unknown-linux-musl) rather than compiling it on every deploy, then run taliesin build <dir> --check-only && taliesin build <dir> and set the publish directory to the emitted _site/ (_book/ for a book). {python} cells need a Python with ipykernel there too. Without one, build stops with an error (exit 1) rather than publish cells it could not run, and a committed _freeze/ does not stand in for it: its key includes the interpreter’s path and version, which differ on the builder. So install Python and ipykernel in that same build command, pass --no-exec to publish the code as highlighted source with no outputs, or build locally and upload the output folder.