Visión General de Variables y Tiempo de Ejecución Dinámico
Visión General de Variables y Tiempo de Ejecución Dinámico
docmd incorpora un potente Motor de Variables y Personalización que combina la interpolación estática en tiempo de compilación con la personalización reactiva en el cliente.
En lugar de definir nombres de empresas, claves de API, años de copyright o versiones manualmente en decenas de archivos Markdown, puede emplear variables dinámicas mediante expresiones limpias de plantilla.
¡Bienvenido a la documentación de **{{ site.title }}** v{{ docmd.version }}!
Copyright actual: © {{ docmd.buildYear }}.
Los siguientes valores han sido resueltos en tiempo real por el compilador docmd durante esta compilación:
- Título del sitio: docmd docs
- Versión del compilador: v0.10.1
- Año de compilación: © 2026
- Rama Git actual: main
- Commit Git actual: f8f75b6
- Slug de página actual:
variables/overview
Sintaxis de Plantillas
El motor utiliza una sintaxis estándar basada en llaves:
{{ variableName }}
Valores Predeterminados (Fallbacks)
Si una variable no siempre está definida (como en entornos de desarrollo local o configuraciones opcionales), proporcione un valor predeterminado usando el operador ||:
Conéctese a nuestro servidor en `{{ server.endpoint || "https://api.example.com" }}`.
¡Bienvenido de nuevo, {{ user.name || 'Invitado' }}!
Compilado para la versión {{ targetVersion || 2.0 }}.
Los fallbacks pueden ser:
- Cadenas entre comillas simples:
'ejemplo' - Cadenas entre comillas dobles:
"ejemplo" - Números:
42o2.0 - Identificadores:
default
Tolerancia a Espacios en Blanco
Las expresiones toleran espacios alrededor de los nombres y operadores:
{{ myVar }}
{{ env.PORT || "8080" }}
Sintaxis Markdown vs. Mapeo con la API JavaScript
Cada variable disponible en sus plantillas Markdown se corresponde 1:1 con el SDK de JavaScript en el navegador (window.docmd.var.get()):
| Tipo de Variable | Plantilla Markdown | API JavaScript Cliente | Regla de Espacio de Nombres |
|---|---|---|---|
| Variable de Usuario / Proyecto | {{ apiEndpoint }} |
window.docmd.var.get("apiEndpoint") |
Definida en docmd.config.json o frontmatter. Sin prefijo docmd.. |
| Variable de Usuario Anidada | {{ cloud.apiEndpoint }} |
window.docmd.var.get("cloud.apiEndpoint") |
Objeto JSON anidado en la configuración. Notación de punto. |
| Versión del Compilador | {{ docmd.version }} |
window.docmd.var.get("docmd.version") |
Espacio de nombres reservado docmd. para metadatos del motor. |
| Año de Compilación | {{ docmd.buildYear }} |
window.docmd.var.get("docmd.buildYear") |
Espacio de nombres reservado docmd.. |
| Metadatos Git | {{ docmd.gitCommit }} |
window.docmd.var.get("docmd.gitCommit") |
Espacio de nombres reservado docmd. o git.. |
| Metadatos del Sitio | {{ site.title }} |
window.docmd.var.get("site.title") |
Espacio de nombres reservado site. de la configuración. |
| Sesión de Usuario Dinámica | {{ user.apiKey }} |
window.docmd.var.get("user.apiKey") |
Con prefijo user. o declarada en dynamic. Reactiva en el DOM. |
{{ docmd.apiEndpoint }}?- El espacio de nombres
docmd.(docmd.version,docmd.buildYear,docmd.gitCommit, etc.) está estrictamente reservado para los metadatos internos del compilador docmd. - Las variables definidas por el usuario (de
docmd.config.jsono frontmatter) nunca deben llevar el prefijodocmd.. Si define"apiEndpoint": "https://api.example.com", use{{ apiEndpoint }}en Markdown y obténgala conwindow.docmd.var.get("apiEndpoint")en JavaScript.
Ciclo de Vida: Compilación vs. Tiempo de Ejecución
docmd divide de forma limpia el ciclo de vida de las variables en dos etapas complementarias:
Se compilan directamente en el HTML final durante docmd build. Tienen cero impacto en la ejecución de JavaScript en el navegador y evitan saltos de diseño (CLS).
Los datos de sesión de usuario (como claves de API o nombres de usuario) son sincronizados en vivo por docmd-runtime.js. Al escribir o cambiar de sesión, los bloques de código se actualizan al instante.
Variables Estáticas en Compilación
Los valores determinados al compilar se insertan directamente en el código estático, sin requerir procesamiento adicional para el lector.
Variables Dinámicas Reactivas
Las variables declaradas como dinámicas o que contienen datos de sesión (como user.name o user.apiKey) se encapsulan en marcadores DOM reactivos:
Invitado
En el navegador, docmd-runtime.js puebla y sincroniza estos valores en toda la página y en transiciones SPA sin recargas.
Arquitectura: Separación entre Motor e Interfaz
Para garantizar la máxima velocidad y estabilidad, docmd separa limpiamente la interfaz visual del motor dinámico:
docmd-runtime.js: El motor dinámico headless incluido en todas las plantillas (default,summer, etc.). Gestiona registros, suscripciones y eventos sin interferir con estilos ni animaciones.docmd-main.js: El script de interfaz responsable del cambio de tema, menús y transiciones SPA. Tras cada cambio de página ejecutawindow.docmd.sync().
Al incluirse docmd-runtime.js en todas las plantillas, cualquier tema personalizado o plugin de diseño hereda soporte dinámico automáticamente.
Próximos Pasos
Consulte las guías completas para cada tema: