Snippets and variables

Repeated prose drifts: the install block gets fixed in one place and goes stale in four others. Readsmith resolves both mechanisms at build time, so shared content stays in one file and every page that uses it ships the current version as static HTML.

Variables

Declare values in docs.yaml:

variables:
  version: 0.1.0
  product: Readsmith

Reference them in prose: these docs run on Readsmith 0.13.0, and that number came from the block above.

The syntax differs by file type, because MDX treats braces as expressions:

Two more facts:

• A page's own frontmatter keys join the scope and win over docs.yaml on collision, so a page can override version locally.
• Text inside code spans and fenced blocks is never interpolated. {{version}} in a code example renders literally, which is how this page shows you the syntax at all.
• An unknown variable becomes a build warning (missing-variable), not silent empty output you discover in production.

Snippets

Put shared files in the reserved snippets/ directory at your content root. Files there are includable content, never pages of their own:

docs/
├── snippets/
│   └── storage-root.md
└── self-host/
    └── deploy.mdx

Include one with the Snippet component, in .md or .mdx alike:

<Snippet file="storage-root.md" />

This site uses that exact snippet inside the deployment guide's warning callout. Here is the same inclusion, live:

Snippets take props

Any extra attribute becomes a variable inside the included file:

<Snippet file="greeting.md" name="Rex" />

where snippets/greeting.md writes {{name}}. Props win over globals inside the snippet's scope.

Snippets nest, and the build guards the two ways that goes wrong: a cycle or excessive nesting is reported as a diagnostic instead of looping, and a file that matches nothing is a build warning pointing at the page that asked for it.