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 }}.
Variables evaluadas en vivo en esta compilación

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: 42 o 2.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.
Estándar de Nombres: ¿Por qué no {{ 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.json o frontmatter) nunca deben llevar el prefijo docmd.. Si define "apiEndpoint": "https://api.example.com", use {{ apiEndpoint }} en Markdown y obténgala con window.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:

Canal de Resolución de Variables
graph TD subgraph Origen["1. Entradas y Definiciones"] B1["docmd.config.json<br/>Bloque <code>variables</code>"] B2["Git y Entorno<br/><code>env.*</code>, <code>DOCMD_VAR_*</code>, Git Root"] B3["Metadatos Integrados<br/><code>version</code>, <code>buildYear</code>, <code>page.slug</code>"] end subgraph Compilador["2. Resolución Estática en Compilación"] Origen --> VReg["VariableRegistry (@docmd/parser)"] VReg --> Interp["Interpolador Markdown y Config"] Interp --> HTML["HTML Estático (Cero JS Overhead)"] Interp --> Markers["Marcadores Dinámicos &lt;span data-docmd-var&gt;"] end subgraph Runtime["3. Tiempo de Ejecución Reactivo en Cliente"] Markers --> DRuntime["docmd-runtime.js (window.docmd)"] DRuntime --> DOM["Rehidratación en Vivo y Fragmentos"] DRuntime --> Events["Eventos y postMessage entre Marcos"] end
Variables Estáticas de Compilación

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).

Variables Reactivas de Cliente

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 ejecuta window.docmd.sync().
Compatibilidad Universal con Plantillas

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:

Variables Integradas

Variables de sistema para años, fechas, versiones y metadatos de Git.
Ver Guía

Variables de Configuración

Definición en docmd.config.json y uso en pies de página, banners y Markdown.
Ver Guía

Variables de Entorno

Integración con pipelines CI/CD y promoción zero-prefix vía DOCMD_VAR_*.
Ver Guía

Personalización en Cliente

SDK de cliente (window.docmd), sesiones reactivas y ejemplos de código interactivos.
Ver Guía