Variables and precedence

Writing•4 min read|||

DocsLit resolves placeholders like {{NAME}} at compile time in prose.

Resolution order

From lowest to highest priority:

  1. global attributes in docslit.json
  2. page frontmatter attributes
  3. page-local <wc-var name="X" value="Y" />

If the same key is defined more than once, the later layer overrides the earlier one.

Global variables

Define shared attributes in docslit.json:

{ "name": "My Docs", "attributes": { "PRODUCT": "DocsLit", "API_BASE": "https://api.example.com" } }

Page-level overrides

Override on a page with frontmatter:

--- title: Enterprise guide attributes: PRODUCT: DocsLit Enterprise ---

Or override locally in page body:

<wc-var name="PRODUCT" value="DocsLit Cloud" />

Built-in version variables

DocsLit injects these variables on every page:

  • {{DOCSLIT_VERSION}} — current docs version
  • {{DOCSLIT_BRANCH}} — source branch for that version

For versioned docs, these values follow the active version/branch. For unversioned docs, they fall back to unversioned and working-tree.

You are reading version **{{DOCSLIT_VERSION}}** from branch `{{DOCSLIT_BRANCH}}`.

Notes

  • variable keys should use UPPER_SNAKE_CASE
  • placeholders inside fenced code blocks are not substituted
  • use {{NAME}} when you want to show a placeholder literally in prose
  • use <wc-var name="X" value="Y" /> to show literal component syntax
  • use Reusable content for include-specific rules