Client Runtime & Personalisation
Client Runtime & Personalisation
docmd includes a lightweight, headless client runtime script, docmd-runtime.js, bundled automatically into every layout template (including the default template and custom themes like summer).
The runtime exposes the window.docmd browser API, allowing you to update variables dynamically based on user authentication, selected environments, or input forms without reloading the page.
Marking Variables as Dynamic
In your docmd.config.json, declare which variable keys are dynamic:
{
"variables": {
"dynamic": [
"user.name",
"user.apiKey",
"selectedProject",
"activeRegion"
]
}
}
When docmd compiles your pages, any variable marked as dynamic (or prefixed with user.) is wrapped in a reactive marker:
pk_test_sample
Browser JavaScript API: window.docmd
The client runtime provides a clean, ergonomic API:
window.docmd.var.set(key, val)
Updates variable values across the DOM, text nodes, and code snippets in real time.
window.docmd.var.get(key)
Retrieves the active value of any registered runtime variable.
window.docmd.var.list()
Returns an object containing all currently registered dynamic variables and values.
window.docmd.var.sync()
Re-scans and rehydrates newly injected HTML or dynamically loaded components.
Code Example: Updating Variables
// Set a single variable
window.docmd.var.set('user.apiKey', 'sk_live_99882244');
// Set multiple variables simultaneously
window.docmd.var.set({
'user.name': 'Sarah Connor',
'activeRegion': 'eu-central-1'
});
All <span data-docmd-var="..."> elements and code block tokens immediately update in the DOM.
Interactive Code Snippets Example
One of the most powerful uses of runtime personalisation is allowing readers to test API endpoints with their own keys:
### Authenticating with the API
Run the following command in your terminal:
```bash
curl -X GET https://api.acme.com/v1/profile \
-H "Authorization: Bearer {{ user.apiKey || 'YOUR_API_KEY' }}"
```
Live Interactive Variable Demonstration
Use the playground below to mutate user.apiKey in the browser runtime. When you run the code or modify the key, docmd-runtime immediately updates all variable references across the page:
The code block below dynamically re-renders in real time as variables update:
curl -X GET https://api.acme.com/v1/profile \
-H "Authorization: Bearer YOUR_API_KEY"
The docmd-runtime.js engine updates reactive DOM elements strictly via .textContent. Variable values are never interpreted as raw HTML or script, preventing DOM-based injection attacks even when variable values are sourced from dynamic user inputs.
Framework Integration
// Listen for user login and update documentation variables
function onUserLogin(session) {
window.docmd.var.set({
'user.name': session.fullName,
'user.apiKey': session.activeToken,
'user.orgId': session.organisationId
});
}
import { useEffect } from 'react';
export function DocsPersonaliser({ user }: { user: any }) {
useEffect(() => {
if (typeof window !== 'undefined' && (window as any).docmd) {
(window as any).docmd.var.set({
'user.name': user.name,
'user.apiKey': user.apiKey
});
}
}, [user]);
return null;
}
<script setup>
import { watchEffect } from 'vue';
const props = defineProps(['currentUser']);
watchEffect(() => {
if (typeof window !== 'undefined' && window.docmd) {
window.docmd.var.set({
'user.name': props.currentUser?.name,
'user.apiKey': props.currentUser?.token
});
}
});
</script>
Listening for Variable Changes
You can listen for changes emitted by the runtime event bus:
window.addEventListener('docmd:variable-change', (event) => {
const { key, value } = event.detail;
console.log(`Variable ${key} changed to:`, value);
});
Cross-Frame Synchronisation (iFrames & Portals)
If your documentation is embedded inside an application iframe, the parent portal can update documentation variables using postMessage:
// From the parent application window:
const docIframe = document.getElementById('docs-frame');
docIframe.contentWindow.postMessage({
type: 'docmd:set-variables',
variables: {
'user.name': 'Alex',
'user.apiKey': 'sk_live_449911'
}
}, '*');
The docmd-runtime.js listener receives the message and updates all page variables automatically.
docmd-runtime.js has zero UI dependencies. It operates entirely on data markers (data-docmd-var), making it safe to use alongside complex SPA routers, light/dark themes, and interactive plugins without causing DOM regressions.