Writing Content ¶

Every page is a .crv file with optional YAML frontmatter followed by Carve content.

Frontmatter Reference ¶

Key	Type	Default	Effect
`title`	`string`	first H1 or path	Page title and search title.
`description`	`string`	site description	Meta description and social description.
`layout`	`string`	`'doc'`	Selects `doc`, `page`, `home`, `blog`, or a custom layout.
`hero`	object	none	Home layout hero data.
`features`	array	none	Home layout feature cards.
`head`	head tuple array	`[]`	Extra tags for this page.
`image`	`string`	none	Social image URL.
`ogImage`	`string`	none	Alias used when `image` is absent.
`redirectFrom`	`string \| string[]`	none	Old routes that redirect to this page.
`outline`	`false \| number \| [number, number] \| 'deep'`	site outline	Per-page outline level.
`aside`	`false`	visible	Hides the outline.
`sidebar`	`false`	visible when matched	Hides the sidebar.
`prev`	`false \| { text: string; link: string }`	computed	Footer previous link override.
`next`	`false \| { text: string; link: string }`	computed	Footer next link override.
`editLink`	`false`	visible when configured	Hides the edit link.
`lastUpdated`	`false`	visible when configured	Hides the timestamp.
`order`	`number`	title sort	Sort key for generated sidebars.
`draft`	`boolean`	`false`	Draft pages are excluded from public derived outputs.
`date`	`string`	required for blog posts	Blog and feed date.
`tags`	`string[]`	`[]`	Blog tag pages.
`excerpt`	`string`	description or first prose	Blog listing and feed summary.
`author`	`string \| string[]`	none	Blog post byline.
`virtual`	`boolean`	internal	Marks generated pages.

Includes ¶

Include directives are comments, so they render nothing after expansion:

include a snippet

%% @include: ./snippets/install.crv

This page includes one real line from a shared snippet:

Install with npm install --save-dev @markup-carve/carve-press.

You can include a range with {2,4}, an open range with {2,}, or a heading section with #heading-id.

Cross-References ¶

Use heading attributes on the line above the heading, then reference them with </#id>.

Cross-Reference Target ¶

This sentence links back to Cross-Reference Target. Reference links also work: Cross-Reference Target.

Link Validation ¶

CarvePress validates site-internal absolute links such as Code Blocks, nav entries, sidebar entries, and frontmatter prev or next links. Hash fragments are allowed, while missing route paths fail the build.

Redirects From Old Routes ¶

Use redirectFrom on the page that replaced an old URL:

frontmatter

redirectFrom:
  - /old-guide/
  - /install

Each source must start with /, must not contain .. segments, and must not collide with a real page or another redirect source. Draft pages do not emit their redirectFrom entries.

Substitutions ¶

Values that appear across many pages - a supported version, a package name - can live in the config instead of in forty files:

carve-press.config.ts

substitutions: {
  enginever: { value: '0.1.0', format: 'code' },
  minnode: '20',
}

Write the key wrapped in pipes and the build replaces it: this site is built with carve-js 0.1.0 and needs Node 20 or newer. A format of bold, italic, or code wraps the value; the default is plain text.

Substitution runs on the parsed document, not on the source text, so a token inside a fence or an inline code span stays literal - which is how this page can show |enginever| while explaining it. An unknown token is left alone and warned about once per build, because a typo should be visible without making every sentence containing a pipe fatal.

Edit this page

Last updated August 5, 2026