Static sites with cascivo-web

cascivo-web builds a static website from a folder of Markdown, content collections and templates. Components from cascivo-html work inside Markdown. It also does locales (/de/...), RSS feeds and a sitemap, and it deploys to Cloudflare Workers Static Assets. It needs no React, no Node build and no JavaScript runtime to build the site. The same input gives the same files.

It is a command-line tool and a Rust library.

When to use it

You wantUse
A running React app@cascivo/react or npx cascivo add (GETTING-STARTED.md)
One static HTML file (report, dashboard)cascivo-html (USING-CASCIVO-HTML.md)
A static site: pages, a blog, locales, RSScascivo-web

Install

cargo install cascivo-web

Prebuilt binaries are attached to the GitHub release cascivo-web@<version>. See RELEASING.md. From a checkout: cargo install --path crates/cascivo-web.

Quick start

cascivo-web new my-site     # write a starter site
cd my-site
cascivo-web dev             # http://127.0.0.1:4321/ with live reload
cascivo-web build           # write dist/

The starter has a home page, an About page, a blog with two posts, an RSS feed, a layout, a favicon, a 404 page and a wrangler.jsonc. new refuses to overwrite files.

Site layout

site.toml                       settings
content/<name>/_schema.toml     schema of one collection
content/<name>/<slug>.md        one entry
content/<name>/<locale>/<slug>.md   a translation of that entry
layouts/*.html                  templates
pages/**.md | **.html           routes
pages/<locale>/...              translated pages
i18n/<locale>.toml              message bundles
public/**                       copied as is
wrangler.jsonc                  deploy config

Files and folders that start with . or _ in pages/ and public/ are skipped. Symlinks are not followed. Slugs and page folders use only a-z, 0-9 and -.

site.toml

title = "My site"
base_url = "https://example.com"
lang = "en"
theme = "light"

[i18n]
default = "en"
locales = ["en", "de"]
fallback = true

[[feeds]]
collection = "posts"
path = "rss.xml"
title = "Blog"
description = "New posts"
limit = 20
KeyMeaning
titleRequired. Site name.
base_urlAbsolute origin. Default empty. Without it there is no sitemap.xml, and feeds fail.
langLanguage of the site. Default en.
themeA cascivo theme name. Default light.
[i18n] defaultDefault locale, served at /. Must be in locales.
[i18n] localesAll locales. Others are served at /<locale>/.
[i18n] fallbackDefault true. See Locales.
[[feeds]] collectionRequired. The collection to publish.
pathFeed file. Default rss.xml.
titleFeed title. Default: the site title.
descriptionFeed description. Default empty.
limitNewest items to include. Default 20.

An unknown key is an error with the line number.

Content collections

A collection is a folder in content/ with a _schema.toml and one Markdown file per entry. The file name is the slug.

# content/posts/_schema.toml
[fields]
title = { type = "string", required = true }
date = { type = "date", required = true }
description = { type = "string" }
tags = { type = "array" }
+++
title = "Hello"
date = 2026-02-01
tags = ["news"]
+++
The body is Markdown.

Front matter is TOML between two +++ lines. Field types:

TypeAccepts
stringa string
intan integer
floata float or an integer
booltrue or false
datea TOML date (2026-01-31) or a "YYYY-MM-DD" string
arrayan array

A missing required field, a wrong type and a field the schema does not list are all errors. Every collection needs a schema file.

Routes

Files in pages/ become routes.

FileURL
pages/index.md/
pages/about.md/about/
pages/blog/index.html/blog/
pages/blog/[posts].html/blog/<slug>/, once per entry of posts

A Markdown page has optional front matter. layout = "post" picks layouts/post.html; the default is default. Other front matter keys are available as page.<key>. A .html page is a template. A dynamic route [collection].html must be a .html template, and the collection must exist. Two files that give the same URL are an error.

Layouts and templates

Layouts and .html pages are minijinja templates (Jinja syntax). Use {% extends "default.html" %} and {% block body %} to share a frame.

VariableValue
sitetitle, base_url, lang, theme. In a locale, lang is that locale.
pageFront matter plus url. On a dynamic route: the entry (fields, slug, url, content).
contentThe page or entry body as rendered HTML.
collectionscollections.<name>: a list of entries with slug, url, content and the fields.
localeThe locale being rendered.
alternatesTranslations of this page: a list of {locale, url, href}. href is absolute.
t(key, **args)A message from i18n/<locale>.toml.
cv(text)Renders .cv text to HTML.

url on an entry exists only when a [collection].html route exists.

<ul>{% for p in collections.posts|sort(attribute="date", reverse=true) %}
  <li><a href="{{ p.url }}">{{ p.title }}</a> {{ p.date }}</li>
{% endfor %}</ul>
{{ cv('page-header "Blog"') }}

Every page links one shared /cascivo.css. It holds the base styles, the theme and only the component CSS the site uses. Layouts need no link tag. Component scripts are added to the page for you.

Head, images, assets and Vite

Template functions take positional or keyword arguments. An unknown keyword is an error.

CallResult
head(title, description, canonical, og_title, og_description, og_image, og_image_alt, og_image_width, og_image_height, og_type, robots, twitter_card, jsonld, theme_color)<title>, description, canonical, robots, og:*, twitter:* and JSON-LD tags. Canonical defaults to base_url + the page URL; there is none without base_url. theme_color is a string or {light, dark}.
img(src, alt, widths=[480, 960, 1440], sizes, class, loading="lazy", format="webp", priority=false)An <img srcset>. Resized, content-hashed copies go to /_cw/img/. It never upscales. format="keep" keeps JPEG, PNG or WebP. priority=true is for the LCP image: eager, fetchpriority="high" and a preload in <head>. priority="<media query>" preloads only where the query matches.
asset(path)Copies a file from [assets] dir to /_cw/<stem>.<hash>.<ext> and returns the URL.
code | highlight("ts")A highlighted <code> element for bash, css, js or ts. Another language is an error.
theme_script(storage_key="cascade-theme", attribute="data-theme", default_light="poster", default_dark="poster-dark", blocking=[...])An inline script that sets the theme before paint.
data.<name>A file listed in [data] (JSON or TOML).

WebP output is lossless. img() and asset() read from [images] dir and [assets] dir (default assets, relative to the site root).

A site that has its own Vite build can use its output. Set it in site.toml; paths are relative to the site root, may point outside it, and are read-only:

[build]
cascivo_css = false     # default true; false: write and link no cascivo.css
[vite]
manifest = "../dist/.vite/manifest.json"
css_modules = "../dist/.vite/css-modules.json"   # { "<x.module.css path>": { local: hashed } }
islands = "src/islands/{name}.tsx"               # manifest key of an island
[data]
web = "../dist/.vite/web-data.json"
CallResult
vite(entry)/ + the hashed file of a manifest entry.
vite_css(entry)CSS URLs of the entry and its static imports, dependencies first.
css_bundle(hrefs, name="bundle")One content-hashed /_cw/<name>.<hash>.css from those files, in order. Top-level @layer a, b; statements go first. A relative url() is an error.
m(module, class)The hashed class of a CSS module. module is the x.module.css stem.
island(name, client="visible", props=none)The data-island, data-client, data-src, data-css and data-props attributes. client is visible, idle or load.
islands_script()A small inline module that loads each island and calls its default export (el, props). A failure leaves the static markup.

Write the static fallback markup inside the island element. The loader replaces it only when the module loads.

Components in Markdown

A line ::name[text]{attrs} is one component. An attribute named like a positional argument fills it, so you need not know the order. A cv code fence holds any .cv tree.

::alert[Body text]{title="Tip" variant=info}

```cv
cols 3
  stat Users 1204
```

For the component list and .cv syntax see USING-CASCIVO-HTML.md or run cascivo-html guide. Markdown inside a component is not supported.

Locales

Add [i18n] to site.toml. The default locale is served at /. Every other locale gets a prefix: /de/, /de/about/, /de/blog/hello/.

Pages. pages/about.md is the default locale. pages/de/about.md translates it. Do not put default-locale pages under pages/<default>/; that is an error.

Collections. content/posts/hello.md is the default entry. content/posts/de/hello.md translates it (same slug). Locale folders must name a configured locale, and not the default.

locale on entries. Every entry gets a locale value: the language its text is in. If your schema declares its own locale field, yours is used.

Fallback. With fallback = true (default), a locale without a translation reuses the default text: the page is rendered at /de/about/ from the default source, and the entry appears in the German collections with locale = "en". With fallback = false, only real translations are rendered. A missing page gives no /de/... URL, and a locale without translated entries has an empty collection.

Messages. i18n/<locale>.toml holds UI strings. Nested tables are flattened with dots.

# i18n/en.toml
[nav]
home = "Home"
hi = "Hello {name}"
{{ t('nav.home') }} {{ t('hi', name=user) }}

{name} placeholders are filled from keyword arguments. A missing key is a build error naming the file. With fallback, a key missing in a locale is read from the default locale. Values must be strings.

hreflang. Put this in your layout <head>:

{% for a in alternates %}<link rel="alternate" hreflang="{{ a.locale }}" href="{{ a.href }}">{% endfor %}

With base_url set, sitemap.xml lists each page once, with xhtml:link entries for every translation and an x-default link to the default locale.

Why TOML, not Fluent. A static page needs lookup and {name} filling, not plural selection at run time. TOML is already the config format here and adds no dependency.

RSS feeds

Each [[feeds]] entry writes one RSS 2.0 file (rss.xml by default).

Link it from a layout: <link rel="alternate" type="application/rss+xml" href="/rss.xml">.

Deploy to Cloudflare

cascivo-web deploy builds the site, then runs npx wrangler deploy in the site folder (Cloudflare Workers Static Assets). The starter's wrangler.jsonc:

{
  "name": "my-site",
  "compatibility_date": "2026-11-01",
  "assets": { "directory": "./dist", "not_found_handling": "404-page" }
}
cascivo-web deploy --dry-run          # build, then print the wrangler command
cascivo-web deploy                    # build and deploy
cascivo-web deploy -- --env staging   # args after -- go to `wrangler deploy`

A wrangler.jsonc, wrangler.json or wrangler.toml must exist in the site folder; without one the command fails before it builds. You need Node (for npx) and a Cloudflare login: npx wrangler login, or CLOUDFLARE_API_TOKEN in the environment. If you use --out, point assets.directory at the same folder (the tool warns when they differ).

Dev server

cascivo-web dev [site] [--port 4321] serves the site on 127.0.0.1. It checks your files every 20 ms, re-renders on change (no cargo rebuild) and reloads open pages over Server-Sent Events. A broken build prints the errors in the terminal and in the browser; fix the file and it recovers.

Commands

cascivo-web new <dir>
cascivo-web build [site] [--out <dir>]
cascivo-web dev [site] [--port <n>]
cascivo-web deploy [site] [--out <dir>] [--dry-run] [-- <wrangler args>]

site defaults to . and --out to <site>/dist. Exit code is 0 on success and 1 on error.

Errors

A build reports every problem it finds, not only the first. Each one names the file and line:

content/posts/hello.md:1: missing required field `date`
pages/blog/[posts].html: no collection `posts` under content/
layouts/default.html:7: undefined value

Writes are confined to the output folder, and paths are checked before they are written.

Use it from Rust

let site = cascivo_web::Site::load(std::path::Path::new("my-site"))?;
let output = site.render()?;       // a map of path -> bytes
output.write(std::path::Path::new("dist"))?;

With the axum feature, cascivo_web::router(&site)? returns an axum::Router that serves the rendered site from memory. Mount it with merge or nest.

Limits

As Markdown: /docs/using-cascivo-web.md

← All guides