Variables & Dynamic Runtime Overview
Variables & Dynamic Runtime
docmd features a high-performance Variables and Personalisation Engine that unifies static build-time interpolation with client-side reactive personalisation.
Instead of hardcoding company names, API URLs, release years, or versions across dozens of markdown files, you can reference dynamic variables using clean template expressions.
Welcome to the documentation for **\{{ site.title }}** v\{{ docmd.version }}!
Current copyright: © \{{ docmd.buildYear }}.
The following values are resolved live by the docmd compiler during this documentation build:
- Site Title: {{ site.title }}
- Compiler Version: v{{ docmd.version }}
- Build Year: © {{ docmd.buildYear }}
- Current Git Branch: {{ docmd.gitBranch || “main” }}
- Current Git Commit: {{ docmd.gitCommit || “HEAD” }}
- Current Page Slug:
{{ page.slug }}
Template Syntax
The Variables Engine uses curly-brace syntax:
\{{ variableName }}
Fallback Defaults
If a variable might not always be defined (such as in local preview environments or optional configurations), provide a fallback default using the || operator:
Connect to our server at `\{{ server.endpoint || "https://api.example.com" }}`.
Welcome back, \{{ user.name || 'Guest' }}!
Built for version \{{ targetVersion || 2.0 }}.
The fallback can be:
- Single-quoted string:
'example' - Double-quoted string:
"example" - Number:
42or2.0 - Identifier:
default
Whitespace Tolerant
Expressions tolerate spaces around variable names and fallback operators:
\{{ myVar }}
\{{ env.PORT || "8080" }}
Variable Lifecycles: Build-time vs. Runtime
docmd cleanly separates the variable lifecycle into two distinct stages:
Static variables are compiled directly into HTML during docmd build. They incur zero client-side JavaScript execution, zero network requests, and zero Cumulative Layout Shift (CLS).
Dynamic session variables (such as API keys and usernames) are hydrated live by docmd-runtime.js. When updated via JavaScript or user input, all matching tokens on the page react instantly.
Static Build-Time Variables
Variables resolved during docmd build are compiled directly into static HTML. There is zero client-side JavaScript overhead or layout shift for these values.
Reactive Dynamic Variables
Variables marked as dynamic or containing user session attributes (such as user.name or user.apiKey) are wrapped in non-intrusive DOM markers:
<span data-docmd-var="user.name" class="docmd-var">Guest</span>
At runtime, docmd-runtime.js automatically populates and synchronises these values across the page, code snippets, and SPA navigation transitions without reloading.
Architecture: Engine vs. UI Separation
To guarantee maximum speed and stability, docmd maintains a strict boundary between UI presentation and the headless dynamic runtime:
docmd-runtime.js: Headless dynamic engine loaded across all templates (default,summer, etc.). It manages variable registries, subscriptions, client storage, and cross-window events. It never interferes with DOM animations or styling.docmd-main.js: The UI presentation script responsible for theme switches, mobile menus, SPA navigation, and DOM interactions. Upon each SPA page transition, it triggerswindow.docmd.sync()to ensure dynamic variables remain fully hydrated.
Because docmd-runtime.js is bundled in every template, any custom theme or third-party layout plugin automatically inherits variable support and dynamic personalisation out of the box.
Next Steps
Explore the complete guide across all variable topics:
Built-in system variables for build years, dates, versions, and Git metadata.
Read Guide
Declaring variables in docmd.config.json and using variables inside footer, banners, and docs.
Read Guide
CI/CD environment variables and DOCMD_VAR_* zero-prefix promotion.
Read Guide
Client-side runtime SDK (window.docmd), reactive sessions, and interactive code blocks.
Read Guide
