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 want | Use |
|---|---|
| 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, RSS | cascivo-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
| Key | Meaning |
|---|---|
title | Required. Site name. |
base_url | Absolute origin. Default empty. Without it there is no sitemap.xml, and feeds fail. |
lang | Language of the site. Default en. |
theme | A cascivo theme name. Default light. |
[i18n] default | Default locale, served at /. Must be in locales. |
[i18n] locales | All locales. Others are served at /<locale>/. |
[i18n] fallback | Default true. See Locales. |
[[feeds]] collection | Required. The collection to publish. |
path | Feed file. Default rss.xml. |
title | Feed title. Default: the site title. |
description | Feed description. Default empty. |
limit | Newest 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:
| Type | Accepts |
|---|---|
string | a string |
int | an integer |
float | a float or an integer |
bool | true or false |
date | a TOML date (2026-01-31) or a "YYYY-MM-DD" string |
array | an 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.
| File | URL |
|---|---|
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.
| Variable | Value |
|---|---|
site | title, base_url, lang, theme. In a locale, lang is that locale. |
page | Front matter plus url. On a dynamic route: the entry (fields, slug, url, content). |
content | The page or entry body as rendered HTML. |
collections | collections.<name>: a list of entries with slug, url, content and the fields. |
locale | The locale being rendered. |
alternates | Translations 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.
| Call | Result |
|---|---|
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"
| Call | Result |
|---|---|
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).
- It reads
titleanddate(both required) anddescription(optional) from each entry. - It needs
base_urlfor absolute links, and a dynamic route[collection].htmlfor item links. - Items are the newest
limitentries. The output depends only on your files:lastBuildDateis the newest item, not the clock. - With
[i18n], each locale gets/<locale>/rss.xml, but only when that locale has that collection's pages (a translation, orfallback = true).
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
- Islands are loaded by a small script. There is no server rendering of them and no bundler: Vite builds the modules.
- Syntax highlighting covers
bash,css,jsandts. WebP output is lossless. - No Markdown inside components.
- Output is static: no forms and no run-time data.
Links
- Source:
crates/cascivo-web - Components in Markdown: USING-CASCIVO-HTML.md
- Releasing: RELEASING.md
As Markdown: /docs/using-cascivo-web.md