Configuration Reference

Scavold has two configuration surfaces: .vitepress/config.js (build tool integration) and .cratly.config.yaml (site specification). They serve different concerns and intentionally do not overlap.

---

.vitepress/config.js — augmentConfig()

import { defineConfig } from "vitepress";
import { augmentConfig } from "scavold/config";

export default defineConfig( await augmentConfig( rawConfig, options ) );

augmentConfig(rawConfig, options?) extends a standard VitePress user config with all Scavold features. It reads .cratly.config.yaml at the project root, derives srcDir, vite.publicDir, and other paths from it, and registers the image processing plugin and Markdown container extensions.

Required Vite option

Scavold's theme entry uses import.meta.glob, a Vite-specific transform. Because the package lives in node_modules, you must tell Vite to process it as source rather than as a pre-built external:

vite: {
    ssr: {
        noExternal: [ "scavold" ],
    },
},

Include this in the rawConfig object passed to augmentConfig. It is spread through and preserved in the final config.

rawConfig — Scavold-specific keys

These keys are recognised in addition to all standard VitePress config options:

Key	Type	Description
mediaDir	string	Path to the media folder relative to the project root. Overrides media_folder from .cratly.config.yaml. Useful when you want to specify a path in code rather than in the YAML.

All other folder paths (srcDir, vite.publicDir) are derived automatically from .cratly.config.yaml. Do not set them manually unless you need to override the defaults.

options — integration overrides

The second argument controls how Scavold maps container names to components.

await augmentConfig( rawConfig, {
    containers: {
        section: "MySiteSection",   // override the built-in section component
        hero:    "MySiteHero",      // component for a site-specific container
    },
} )

The containers map keys are container names from .cratly.config.yaml (or the seven built-in sectioning names). Values are the Vue component names to use. When absent, Scavold derives the component name as Scavold{Name} automatically.

---

.cratly.config.yaml

The .cratly.config.yaml file at the project root is a framework-agnostic site specification. It describes the site — where content lives, how images are processed, what frontmatter fields exist — not how to build it. Scavold reads it at build time; the cratly online editor reads it to configure its UI.

Top-level structure

version: 0

pages_folder: pages
media_folder: media
static_folder: public

image_widths: [320, 640, 960, 1280, 1920]
image_sizes: "100vw"

containers:
  hero:
    label: "Hero section"

frontmatter_fields:
  image:
    type: media-file
    inherits: true

version

Type: number — currently 0

Tracks the version of this specification. Set this to the latest version available, which is currently 0. Version 0 is pre-stable; breaking changes may occur.

pages_folder

Type: string

Path to the folder containing all Markdown page files, relative to the project root. Scavold sets VitePress's srcDir to this value.

media_folder

Type: string

Path to the folder containing source images and videos, relative to the project root. Scavold resolves image paths in Markdown against this folder.

static_folder

Type: string

Path to the folder served as the VitePress public directory (equivalent to vite.publicDir). Generated responsive image variants are written to {static_folder}/media/.

image_widths

Type: number[] — default [320, 640, 960, 1280, 1920]

Pixel widths for which Scavold generates responsive image variants. Sharp produces one WebP and one original-format file per width per source image.

image_sizes

Type: string — default "100vw"

Default CSS sizes descriptor applied to all responsive images that have no per-image override. Set this to the most common layout width on your site (e.g. the prose column width for a text-heavy site).

Per-image overrides are set via the Markdown image title field:

![Alt text](/photo.jpg "sizes=(min-width: 60rem) 50vw, 100vw")

containers

Type: object

Declares named Markdown container blocks beyond the seven built-in sectioning elements (section, aside, article, header, footer, nav, main).

Each entry can be a shorthand string (component name) or an object with editor metadata:

containers:

  # shorthand: maps :::hero to <MySiteHero>
  hero: MySiteHero

  # full declaration: maps :::callout to <ScavoldCallout> (default naming)
  callout:
    label: "Callout box"
    flags:
      - warning
      - info

  # with key–value arguments
  teaser:
    label: "Teaser card"
    kv:
      - background    # mapped as data-background attribute
      - link          # mapped as data-link attribute

The component name defaults to Scavold{Name} when not specified in the shorthand or via a component key in the object form.

Container flags listed under flags become boolean props / class names. Key–value pairs listed under kv become data-* attributes and can be consumed via useContainer().

Container arguments in Markdown follow the pattern key=value (quoted values supported) or plain words for flags:

::: teaser background=/media/hero.jpg link=/products/
Content here.
:::

frontmatter_fields

Type: object

Declares custom frontmatter fields so that editors know how to present them and adapters know how to process them.

frontmatter_fields:
  image:
    type: media-file
    inherits: true
    label: "Page image"
    hint: "Used at the top of the page and in social previews."

Fields not declared here are valid frontmatter — they are passed through without any special handling.

Entry properties

Key	Required	Type	Description
type	yes	string	Determines editor widget and adapter processing. See types below.
inherits	no	boolean	When true, adapters walk the page hierarchy upward to find a value when the field is absent on the current page.
label	no	string	Human-readable label shown in editors.
hint	no	string	Short explanatory text shown below the input in editors.

Field types

Value	Editor widget	Adapter behaviour
text	Single-line text input	Passed through as-is
textarea	Multi-line text input	Passed through as-is
boolean	Toggle / checkbox	Coerced to boolean
number	Numeric input	Coerced to number
media-file	Media folder file picker	Path resolved against media_folder
page-ref	Page tree picker	Path resolved against pages_folder

Extensibility

Tool-specific extension keys should be namespaced to avoid clashes:

_scavold:
  some_option: value

Compliant tools must ignore keys they do not recognise. The version key will be incremented when breaking changes are introduced.