<!--
  Generated from docs/ — do not edit here; run `pnpm regen`.
  Canonical: https://cascivo.com/docs/using-cascivo-web.md
  registry v1.11.0 · generated 2026-11-21
-->

# 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](/docs/getting-started.md)) |
| One static HTML file (report, dashboard)   | `cascivo-html` ([USING-CASCIVO-HTML.md](/docs/using-cascivo-html.md))                  |
| A static site: pages, a blog, locales, RSS | `cascivo-web`                                                                          |

## Install

```sh
cargo install cascivo-web
```

Prebuilt binaries are attached to the GitHub release `cascivo-web@<version>`. See
[RELEASING.md](https://github.com/cascivo/cascivo/blob/main/docs/RELEASING.md). From a checkout: `cargo install --path crates/cascivo-web`.

## Quick start

```sh
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

```text
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

```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](#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.

```toml
# content/posts/_schema.toml
[fields]
title = { type = "string", required = true }
date = { type = "date", required = true }
description = { type = "string" }
tags = { type = "array" }
```

```md
+++
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](https://docs.rs/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.

```html
<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:

```toml
[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.

````md
::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](/docs/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.

```toml
# i18n/en.toml
[nav]
home = "Home"
hi = "Hello {name}"
```

```html
{{ 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>`:

```html
{% 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 `title` and `date` (both required) and `description` (optional) from each entry.
- It needs `base_url` for absolute links, and a dynamic route `[collection].html` for item links.
- Items are the newest `limit` entries. The output depends only on your files: `lastBuildDate` is
  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, or `fallback = 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`:

```jsonc
{
  "name": "my-site",
  "compatibility_date": "2026-11-01",
  "assets": { "directory": "./dist", "not_found_handling": "404-page" },
}
```

```sh
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

```text
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:

```text
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

```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`, `js` and `ts`. WebP output is lossless.
- No Markdown inside components.
- Output is static: no forms and no run-time data.

## Links

- Source: [`crates/cascivo-web`](https://github.com/cascivo/cascivo/tree/main/crates/cascivo-web)
- Components in Markdown: [USING-CASCIVO-HTML.md](/docs/using-cascivo-html.md)
- Releasing: [RELEASING.md](https://github.com/cascivo/cascivo/blob/main/docs/RELEASING.md)
