Static HTML with cascivo-html
cascivo-html turns a short text file (.cv) into one HTML file styled by the real cascivo
CSS. Use it for reports, dashboards, landing pages and one-off documents. It needs no React, no
build step and no JavaScript runtime. An agent writes the .cv text, the tool checks it and
renders it.
It is a Rust library plus a command-line tool. The library has no dependencies. The same input always gives the same bytes.
When to use it
| You want | Use |
|---|---|
| A running React app | @cascivo/react or npx cascivo add (GETTING-STARTED.md) |
| An agent-built page from JSON | @cascivo/render with a ViewConfig |
| One static HTML file (report, dashboard, landing page, document) | cascivo-html |
| A UI as Markdown for an agent to read | @cascivo/text (MACHINE-MODE.md) |
Static output only: no forms, no live data, no event handlers you write yourself.
Install
cargo install cascivo-html-cli # installs the `cascivo-html` binary
cargo add cascivo-html # the library, for Rust programs
The fetch cargo feature (default on) lets the CLI download http(s) images. Turn it off with
--no-default-features if you do not want network code in the binary.
The .cv format
One node per line. A child is indented by two spaces. Use spaces only; tabs are an error.
@title "Sales"
@brand #5b5bd6 r8 gap4 dark
page-header "Sales" "Q3 overview"
cols 3
stat Revenue "$48k" "+12%"
stat Users 1204
stat Churn "2.1%"
card "Trend"
line 3 5 8 13 9 14
- A string is a bare word, or
"text in quotes". A trailing quoted string is the node's text. - A prop is
key=value(gap=4,variant=primary). A bare word that is an enum value or a boolean prop name is a flag:button Save primary. - Chart and table data is written inline:
bar Q1:12 Q2:18,line 3 5 8,table Name,Age | Ann,31 | Bob,42(the first row is the header; props go before the rows). 3x card "x"repeats a node. A line that starts with#is a comment.- Aliases:
cols=columns,rowandcol=flex,h1toh3=heading,p=text.
The format has 51 elements: layout, display, feedback, navigation and seven SVG charts (bar,
line, area, pie, scatter, spark, gauge). Do not guess names or props. Run
cascivo-html guide for the list and cascivo-html guide <name> for every prop of one component.
Brand a page
@brand sets the look in one line. Every key is optional.
| Key | Meaning |
|---|---|
#hex | primary color |
accent=#hex | accent color |
theme=<name> | one of the twelve cascivo themes |
light, dark, auto | color mode |
r8 | corner radius in px |
gap4 | default space step |
density=compact|normal|comfy | spacing density |
font=Inter, mono=… | font families |
For a reusable brand, put the same keys in a file, one per line, and use @brand-file brand.cv
in the page or --brand brand.cv on the command line. Brand files are read only from the input
file's folder.
Images and SVG
image logo.png "Acme logo" w=64 h=64
svg icons/chart.svg "Revenue chart icon" w=48 fit=contain
svg "<svg viewBox='0 0 8 8'><circle cx='4' cy='4' r='3' fill='currentColor'/></svg>" "Dot"
imageembeds the file as a base64data:URI.svgputs sanitized markup in the page, socurrentColorfollows the theme. The sanitizer rejects<script>,<foreignObject>,on*handlers, externalhrefs,@import, DOCTYPE and entities.- Paths are relative to the
.cvfile (the current folder for stdin). Add more folders with--assets <dir>(repeatable)...and paths outside those folders are refused. http(s)sources stay plain links. Pass--fetchto download and embed them.- A file larger than 2 MiB is refused. Change the limit with
--max-asset <bytes>. - Give alt text. An
svgwith no alt text is hidden from assistive technology.
The CLI
cascivo-html guide [component] # the agent cheat sheet, or one component
cascivo-html check [in.cv|-] [--brand f] [--target t] # validate only
cascivo-html render [in.cv|-] [-o out.html] [--brand f] [--target t] [--assets dir] [--fetch] [--max-asset n]
- or no input reads stdin. Without -o, the HTML goes to stdout. Exit codes: 0 ok, 1
invalid .cv, 2 usage or I/O error. Errors are file:line:col: message with the expected
signature or a did-you-mean.
The loop for an agent: read guide, write page.cv, run check until it exits 0, then
render page.cv -o page.html. The skill cascivo-html wraps
this loop.
Render for Blitz
Blitz is a native HTML/CSS engine with no JavaScript. Pass
--target blitz (library: Options { target: Target::Blitz, .. }) to lower the output for it.
The default, browser, changes nothing.
| Blitz gap | What --target blitz does |
|---|---|
@container never matches | Rewrites it to the same @media query on the viewport. Right for page-level layouts; a narrow container in a wide window still follows the window. scroll-state() containers are dropped. |
:focus-visible never matches | Rewrites it to :focus. Pointer focus shows the ring too. |
SVG ignores CSS fill, stroke, transform, var() and oklch() | Moves them to presentation attributes with rgb() values from the page theme and brand (meter, progress-circle and every chart). |
No <script> | Does not emit the table-sort script. [data-sortable] stays for a host handler. |
overflow:auto needs no change: Blitz treats it as scroll. :has() needs the engine pref
layout.css.has-selector.enabled; the host sets it.
cascivo-html check --target blitz page.cv prints what still degrades as
file:line:col: warning: component: message on stderr. Warnings do not change the exit code.
The same lint is cascivo_html::lint(src, Target::Blitz). The pieces are public too:
lower_css(&css) and lower_svg(&html, &css).
The library
use cascivo_html::{render, Options};
let html = render("card \"Hi\"\n", &Options::default())?;
render,parse,check,lint, andGUIDE/guide_for(name)for the cheat sheet text.- The library does no file I/O. Give it files through
Options::assets(a list of(path, bytes)),Options::asset_resolverandOptions::brand_resolver. The CLI does this for you. Options::max_asset_bytessets the size limit;Options::embed_urlssendshttp(s)sources to your resolver.
Full API: docs.rs/cascivo-html.
Links
- Crate: crates.io/crates/cascivo-html and crates.io/crates/cascivo-html-cli
- Source and examples:
crates/cascivo-html - Releasing (changesets for crates): RELEASING.md
As Markdown: /docs/using-cascivo-html.md