v0.2.0 is out. Grab a binary for Linux or macOS, or the Docker image. Read the release notes

Blog

v0.2.0: pages get a body

Pages built from blocks you define, and rich text you can write in Markdown and read back as HTML. Plus the first code from someone who isn't me.

James Conway4 min read

Here’s what v0.1.0 couldn’t do: hold a blog post. It could store a title, a date, some tags and a link to the author. The post itself went in a textarea, and good luck with the headings.

v0.2.0 is the one where pages get a body. A page can be built from blocks you define, a post can carry real rich text, and you can write that text as JSON or as Markdown, then read it back as JSON, HTML, Markdown or plain text. It’s the first item on the roadmap, done, and the first of what this site needs before it can move onto TachyonCMS itself.

Still pre-alpha

That hasn’t changed. Drafts, media and the admin screen don’t exist yet, so keep it off public networks for now. Drafts are next on the roadmap, and already under way.

Get it, or upgrade

docker pull ghcr.io/tachyon-cms/tachyoncms:v0.2.0

Prefer a binary? The release page has them for Linux on x86_64 and arm64 (both static) and macOS on Intel and Apple silicon. New to it? Install takes you from nothing to your first request.

Already running v0.1.0? Swap the binary or the image and start it. There’s one database migration, and it runs by itself.

What you get

v0.2.0 at a glance. Get it as a binary for Linux or macOS, or as a Docker image; upgrading from v0.1.0 is a swap, and the one migration runs by itself. What's in it: pages built from blocks, shared blocks you write once, rich text with features turned on per field, Markdown input that refuses what it can't convert, output as HTML, Markdown or text, and config mistakes that stop at startup, from @foothillsdigital. Supply chain: an SBOM per archive, cosign-signed checksums, build provenance, a signed image, a weekly Scorecard and DCO sign-off. Pre-alpha: drafts, media and the admin screen come next.
The release on one page. Open it full size, or share it.

Pages built from blocks

A landing page isn’t one long text field. It’s a hero, then a quote, then a call to action, in whatever order the editor wants this week. That’s what a blocks field holds: a list of rows, each one of the block types you define, each with its own fields.

{"name": "layout", "type": "blocks", "blocks": [
  {"slug": "hero", "fields": [{"name": "heading", "type": "text", "required": true}]},
  {"slug": "quote", "fields": [{"name": "text", "type": "textarea", "required": true}]},
  {"blockRef": "cta"}
]}

Every row says which type it is and keeps an id across saves, so you can reorder a page without losing track of what’s what. You can filter into rows, too: where[layout.blockType][equals]=quote finds every page with a quote on it. And field rules work inside blocks exactly as they do anywhere else, so a field only Editors may read stays hidden in every row that has it.

That {"blockRef": "cta"} is a shared block. Define it once, with "kind": "block", and every collection that names it gets the same fields, rules and labels. Change it and each of those schemas changes in the same save. If that would leave a page that no longer validates, the server shows you which and waits for you to confirm. If it would break something elsewhere, such as a join that reads one of its fields, it’s refused. Nothing is ever half saved.

Rich text, and Markdown when you’d rather type

Paragraphs, headings, lists, task lists, quotes, code, tables, links, and blocks placed in the flow of the text. Each field decides which of those it allows: a summary might take bold, italic and links, and nothing else.

It’s stored as a JSON tree, but you don’t have to write one. Send Markdown instead:

{"title": "Clean up", "body": {"format": "markdown", "value": "## Before you start\n\nBack up first. The [backup guide](doc:articles/back-up-first) has the steps.\n\n:::callout{kind=\"warning\"}\nThis empties the **bin**.\n:::\n"}}

That doc:articles/back-up-first link names another document by its slug, and TachyonCMS stores its ID. The :::callout is a block, with Markdown inside it. Ask for the post with ?format=html and the paragraph comes back like this:

<p>Back up first. The <a href="/blog/back-up-first">backup guide</a> has the steps.</p>

The link goes to wherever the articles collection says its documents live. Ask for markdown or text instead and you get those, populated and joined documents included.

What Markdown can’t say faithfully, it doesn’t guess at. Anything that won’t convert is a 422 that tells you where, such as line 3: unknown directive `:::aside` , rather than a post that’s quietly wrong. The Markdown input docs list every rule, down to what happens to an empty paragraph.

Rich text that can’t run a script

HTML output is built by TachyonCMS from that tree, with every piece of text escaped. Nothing you store is ever passed through as HTML. A link can only start with http://, https://, mailto:, tel:, / or #, so javascript:, in any mix of cases or with a tab hidden in the middle, is refused when you save. And every link is checked again on the way out, in case it was stored before a rule changed.

Someone who can’t read a document doesn’t learn it exists by way of your rich text, either. In HTML, Markdown and text, a link to it comes out as its text alone.

Config mistakes stop at startup

This part isn’t mine. A --config file that doesn’t exist, a misspelt key, an origin that could never match: until now those meant a server that started fine and behaved oddly later. Now they stop it straight away and say what’s wrong:

Error: unknown key `lisen` in typo.toml; the top-level keys are database_url, listen, public_url, auth
Error: auth.allowed_origins: `https://*.example.com` uses a wildcard, which isn't supported; list each origin, like https://www.example.com

tachyon schema diff now reads your file before it touches the database, so a typo in the file name doesn’t wait on a connection. And when the database is the problem, the error names the host, port and database it tried, and never the password.

Thank you

To @foothillsdigital, the first person to send code to TachyonCMS. Every startup and CLI fix above is theirs (#47, #48, #52), and so are the docs for the first two. Thank you. It’s a strange and good thing to ship a release with someone else’s name in it.

There are more good first issues waiting, and the next release notes have room.

What’s next

Drafts, versions and scheduled publishing, so nothing goes live before it’s meant to. That’s under way now. After it come media, live preview, authoring tools and then the admin screen, in the order Where TachyonCMS is headed sets out. The roadmap keeps it current.