CLI ¶

Commands ¶

Flags ¶

Build Cache ¶

build stores each page’s render in node_modules/.cache/carve-press/render-cache.json and reuses it while the page, its includes, the images it sizes and the site configuration are unchanged. The build prints how many pages it rendered and how many came from the cache. See Configuration for what invalidates it. --no-cache renders everything.

Checking a Site ¶

check renders every page, lints it and its includes, and validates links, nav, sidebars, prev/next overrides and the route manifest, exactly as build does. The output goes to a temporary directory that is removed afterwards, so outDir and routes.json are left untouched. Any failure exits with a non-zero status, which makes it a pull-request gate:

npx carve-press check

Formatting Sources ¶

fmt rewrites .crv files with the Carve engine’s canonical writer. With no paths it formats every .crv under srcDir, including snippets that srcExclude keeps out of routing; hidden directories and node_modules are skipped. Pass files or directories to format only those.

--check writes nothing: it prints each file that is not canonical and exits 1 if there is any. --align-tables pads every table column to a common width, measured by display width. It is opt-in, so use the same flag in --check and in the formatting run, or the two disagree.

A file the writer cannot format is reported with the reason and the command exits 2.

Importing a Site ¶

import moves an existing Markdown or HTML site to Carve. Point it at a file or a directory:

carve-press import old-docs --report import-report.json

Each .md, .markdown, .html or .htm file becomes a .crv page at the same relative path under --out, which defaults to the configured srcDir. Other files, such as images next to the pages, are copied into the configured publicDir (public without a config) at the same relative path, because the build publishes that directory. Importing a folder in place works too: carve-press import docs writes docs/guide.crv next to docs/guide.md, and .crv files already in the source are left alone. Hidden directories (.vitepress, .git), node_modules and the configured outDir are skipped, and an existing file in the target is never overwritten unless --force is given.

Markdown goes through the engine’s Markdown importer, which keeps YAML frontmatter. For HTML, the first <main>, else <article>, else <body> is taken as the page content, so site navigation and footers stay behind; a page without an H1 gets its <title> as the frontmatter title.

The terminal report lists every finding that lost or degraded content, with its file and line: elements the HTML importer dropped, Markdown constructs it could only approximate, links that still name a source file such as ../index.md, and relative images. CarvePress routes have no extension, so those links need pointing at the route, and each relative-image finding names the root-relative path to write instead. The --report file carries every finding, informational ones too. After an import, run carve-press check to see what the build would still reject.

Examples ¶

carve-press build
carve-press build --no-cache
carve-press check
carve-press fmt --check --align-tables
carve-press fmt docs/guide --align-tables
carve-press import old-docs --out docs --report import-report.json
carve-press routes --root .
carve-press dev --host 0.0.0.0 --port 5173
carve-press serve --port 4173
carve-press init --force
carve-press new guide/install --title "Install"

Unknown commands print usage and exit with a non-zero status. User-facing build errors are formatted without raw stack traces.