Extend refrakt
This handbook is for developers extending refrakt — writing custom runes, building themes, shipping plugins, or hooking into the build pipeline. If you're here to author content with refrakt's existing runes, head to the Docs handbook instead.
What lives here
- Rune authoringMental model, content models, output contract, and canonical patterns for writing new runes.
- Plugin authoringPackage your runes, theme config, behaviors, and CLI commands as a
Plugin. Hook into the cross-page pipeline. - Theme authoringBuild a theme from scratch or extend Lumina: design tokens, BEM CSS, identity-transform config, and dimensions.
- PipelineCross-page register / aggregate / post-process hooks. Build site-wide indexes from page content.
- Content variablesThe author-facing variable surface:
$frontmatter,$page,$file, and the conventions that separate public variables from pipeline internals. - SecurityThreat model for runes that surface raw author HTML/CSS/JS, plus the
ResolvedSecurityPolicycontract. - ContributingHow this repo runs — branches, the plan workflow, releases, and where to file issues.
Before you start
A few things worth knowing before you write your first rune:
- Read Authoring overview first. It introduces
createContentModelSchema,createComponentRenderable, and the identity-transform engine. Everything else in Extend assumes that mental model. - Runes almost always belong in a plugin, not in the core rune library. See the community package rune checklist.
- The author-facing rune reference catalog is at
/runes. Both audiences use it for different reasons — authors copy snippets, developers verify their own rune output.
Useful CLI commands
Even if your day-to-day is writing TypeScript and CSS, a few CLI commands are worth knowing:
refrakt inspect <rune>— see the HTML the identity transform produces for any rune. Indispensable when wiring up BEM CSS or debugging modifier classes.refrakt contracts— generate the full structure contract (every BEM selector, data attribute, structural element) for the active rune set.refrakt reference dump— emit the full rune syntax reference for the active plugin set. Used to regenerateAGENTS.md.