Build a publication, not a publishing system.

Raymatic v0.2.0 is a convention-first static publisher. This guide documents the behavior that exists today across the source project, CI, and release workflow.

Getting started

$ ray new my-site
$ cd my-site
$ ray dev
Preview available at http://127.0.0.1:3000

Open the preview in a browser. The generated starter project contains a content/ directory, a shared presentation/page.html template, and a short README.

Writing content

Pages are Markdown files with TOML front matter between +++ delimiters. The title attribute is required.

+++
title = "A page title"
+++
A page title
Write the page in Markdown.

Raymatic renders each content file as a static page using the shared presentation template. Assets are copied, image dimensions are detected, and an assets-manifest.json file describes published assets.

Presentation

Edit presentation/page.html to control the document shell. The template receives {{ title }}, rendered {{ body }}, site identity, SEO metadata, navigation, and publication metadata. Plain HTML and CSS are the supported presentation boundary.

Local development

ray dev serves the latest valid preview at 127.0.0.1:3000 (with fallback ports), watches content, presentation, and assets, and classifies the dependency that triggered each rebuild. An invalid edit leaves the last valid preview running; a later fix recovers automatically.

Validation and diagnostics

Run ray check before building. Diagnostics are structured and source-aware. They can identify malformed front matter, missing titles, invalid dates, missing assets, empty image alt text, template failures, route collisions, and broken internal references.

Building

Run ray build to validate and produce static output in output/. Output is staged and replaced only after a successful evaluation, so failed validation does not commit an invalid production tree.

Project structure

my-site/
├── content/
├── presentation/
├── assets/
├── site.toml             optional site identity and base URL
├── README.md
└── output/              generated by ray build

Generated publication

A successful build produces pages, archive and taxonomy views, RSS, Atom, sitemap, robots metadata, copied assets, and assets-manifest.json. Draft content is validated but excluded from public output.

More guides

Read the practical guide for front matter, site configuration, migration, deployment, and release checks. The source repository also contains the complete English documentation set.