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 wantUse
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

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.

KeyMeaning
#hexprimary color
accent=#hexaccent color
theme=<name>one of the twelve cascivo themes
light, dark, autocolor mode
r8corner radius in px
gap4default space step
density=compact|normal|comfyspacing 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"

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 gapWhat --target blitz does
@container never matchesRewrites 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 matchesRewrites 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())?;

Full API: docs.rs/cascivo-html.

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

← All guides