2 Choosing Taliesin

Every other chapter tells you how to use the tool. This one is for the decision before that: what you are committing to, what you get, and what leaving costs. It is deliberately specific, because the honest version of “should I adopt this” is a set of numbers, not a set of adjectives.

2.1 Your source stays yours

The first worry about a single-author tool is lock-in: that a year of writing ends up in a dialect only this program understands. Here is the measurement.

Across the 81 .tmd documents in Taliesin’s own corpus, 7,095 lines of real writing, the largest sample that exists, 476 lines, 6.7%, carry any construct beyond plain CommonMark. The other 93.3% is Markdown, and any Markdown tool reads it.

(Measured 2026-08-20 over corpus/**/*.tmd; a line using two constructs is counted once in the total and once per family, so the family rows sum to more than the total. Reproduce it with python3 tools/portability-census.py, which is where these numbers come from and which spells out each family’s definition. The script is committed for a reason: this table was first published in July as “measured rather than asserted” while the script that measured it was not, and by August its document and line counts no longer reproduced.)

None of those six is invented here. Every one is Pandoc or Quarto vocabulary that predates Taliesin, which means the 6.8% is not stranded either: it is the same syntax another Pandoc-family tool already parses. .tmd is a file extension, not a format, and the same argument runs backwards: a project arriving from Quarto brings its sentences, fenced cells, #| options, ::: divs, math, citations and cross-references across unchanged. taliesin build . --check-only names the short list of vocabulary that differs, with a file and a line for each, which is a better migration assistant than any page could be.

One thing it cannot flag is an unknown cross-reference prefix. Only @fig-, @tbl-, @sec-, @eq- and @lst- are references here; anything else (@thm-, @def-) is left as literal text on purpose, because @rust-lang in a sentence is indistinguishable from a typo. Grep your source for those prefixes before you migrate.

2.2 The speed story, in absolutes

Speed is the reason this tool exists, so it is worth stating without a marketing multiplier. These are absolute numbers on one machine, and they measure Taliesin’s work only. A batch document compiler doing a cold Pandoc pass with execution is doing different work; comparing the two as a ratio would be dishonest arithmetic, so no ratio appears here.

(Build and ready figures measured 2026-08-10, best of three, release build, warm _freeze/ cache. Each build figure is the duration the build prints for itself, and each page count is the one it reports (find … -name '*.html' is not the page count, since a project may ship its own 404.html and _-prefixed files are never pages). The warm-edit and cross-reference rows come from tools/live-edit-bench, re-measured 2026-08-18, release build; its committed RESULTS.md labels them indicative (the numbers vary by machine). The structural rows it also records, the op counts and payload bytes, are deterministic and gated by a regression test.)

The number that matters is not any single row: it is that the warm edit is a diff, so its cost tracks what you changed rather than how large the document is. See the block model for the operation breakdown behind that payload figure.

The last row is the honest asterisk on that sentence. Inside a multi-page project a save is not only the diff: the cross-reference registry is re-derived first, and its harvest renders every page to recover the cross-page figure and equation numbers. That pass is flat per page (about 3 ms for a page in this guide), so it scales with the size of the project while the diff scales with the size of the edit. At this guide’s 16 pages it is 48 ms; a 200-page project of heavy pages would pay around 2.5 s, which is the number to know before assuming the 12 ms row describes a book.

2.3 What Taliesin claims, and who asked for it

Each of these is a thing users of comparable tools have asked for in public. They are listed with their sources so you can check that the need is real rather than retrofitted.

• Edit in your own editor, see output alongside. (marimo #3114) The .tmd file is the only editing surface; the browser is a read-only view, and click-to-source is the one bridge back. It never writes to your source.
• A format a human can read and git diff. (marimo #1379) .tmd is Markdown. See the table above for exactly how much of it is not.
• Reload on disk change, without losing state. (marimo #2675) A save re-renders and patches in place; scroll position and live canvases survive.
• Stop restarting the kernel. (Quarto #4201) The kernel is warm for the life of the server, so an edit costs one cell, not one boot.
• Re-render only what changed; freeze a single cell. (Quarto #3674, #10429) Both are the same mechanism here: a per-cell cumulative content hash.

The strongest claim is the one nobody else makes. Cached-output systems in this space carry a standing complaint that the cache can serve a stale result: an output produced by code that has since changed. Taliesin’s cache key is the cumulative hash of a cell’s own code plus every upstream cell in its language plus the interpreter’s identity, so editing anything upstream invalidates that cell and everything downstream. For the axes the key can see (cell code, its upstream, the interpreter) a stale hit is not unlikely, it is unrepresentable. The key is deliberately blind to what a cell reads: a data file, an environment variable, a fetched URL, the clock, a library upgraded in place. Mark such a cell #| cache: false and it re-runs every time, along with everything downstream. See Executable content and the cache notes in Troubleshooting.

2.4 Continuity: what you are relying on

Read this part before you commit a book to it.

Taliesin has one maintainer, and the scope is closed. That is the plain fact, and 1.0 does not change it: the version means the feature set is final for this tool’s one use case, not that a team stands behind it. What it means concretely: there is no support contract, no release cadence you can plan around, and no second person who knows the codebase. If the maintainer stops, the project stops.

What does not stop:

• Your source is Markdown, 93.3% of it plain CommonMark, all of it in your repository.
• Pages you already built keep working: they are static HTML with no runtime dependency on the tool that made them.
• The code is AGPL-3.0, so a fork is always available to anyone who wants one.

So the realistic downside is not “your writing is lost”, it is “you migrate to another Pandoc-family tool and re-do a small fraction of the syntax.” That is a cost worth naming, and it is bounded by the table in Your source stays yours.

The mitigation the project actually offers is dogfooding rather than a promise: everything the author writes goes through this tool. Both books of this manual, the public website and the regression corpus are .tmd rendered by Taliesin: 112 tracked .tmd files, 12,904 lines, of which the 81-document corpus is re-rendered by every cargo test run. The manual you are reading is not a description of the tool; it is output from it. A defect that breaks a page breaks the documentation for that page in the same commit.