Referencia de Variables de Entorno
Referencia de Variables de Entorno
docmd permite inyectar variables de entorno del sistema directamente en su documentación, facilitando la integración fluida con pipelines de CI/CD como GitHub Actions, GitLab CI, Vercel o Netlify.
Acceso mediante env.*
Cualquier variable de entorno disponible durante la compilación puede consultarse utilizando el prefijo env.:
Desplegado en entorno: **\{{ env.ENVIRONMENT || 'development' }}**.
ID de Compilación: `\{{ env.GITHUB_RUN_ID || 'local' }}`
Rama: `\{{ env.GITHUB_REF_NAME || 'main' }}`
Valores por Defecto (Fallbacks)
Dado que las variables de entorno pueden no estar presentes localmente, especifique siempre un fallback mediante ||:
Punto de conexión de pruebas:
`\{{ env.STAGING_GATEWAY_URL || "https://sandbox.gateway.io" }}`
Promoción Zero-Prefix vía DOCMD_VAR_*
Para evitar escribir el prefijo env. en documentos Markdown, las variables con prefijo DOCMD_VAR_ se promueven automáticamente al nivel superior:
# En su pipeline o archivo .env:
export DOCMD_VAR_API_HOST="https://api.production.internal"
export DOCMD_VAR_RELEASE_CHANNEL="beta"
En sus documentos Markdown:
El servidor es `\{{ API_HOST }}`.
Canal de publicación: **\{{ RELEASE_CHANNEL }}**.
Ambas variables también pueden seguir referenciándose mediante su nombre completo (\{{ DOCMD_VAR_API_HOST }}).
¡Nunca exponga claves secretas o contraseñas en variables de compilación! Todo lo resuelto durante docmd build queda visible en el código HTML generado. Para credenciales privadas de usuario, utilice la personalización en cliente (window.docmd.var.set).
Integración con Pipelines CI/CD
Siga estos pasos para suministrar metadatos dinámicos a su documentación:
- Declarar Variables en la Pipeline
Configure su pipeline para exportar las variables necesarias (por ejemplo, con prefijo
DOCMD_VAR_). - Ejecutar el Compilador
Ejecute
docmd build. El compilador lee automáticamenteprocess.env. - Publicar la Documentación
El directorio de salida contiene HTML estático con todos los valores integrados.
Ejemplos de Pipeline
name: Deploy Documentation
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- name: Compilar Documentación
run: npx @docmd/core build
env:
DOCMD_VAR_DEPLOYED_AT: ${{ github.event.head_commit.timestamp }}
DOCMD_VAR_BUILD_ID: ${{ github.run_id }}
DOCMD_VAR_COMMIT_SHA: ${{ github.sha }}
ENVIRONMENT: production
deploy_docs:
image: node:22
stage: deploy
script:
- npx @docmd/core build
variables:
DOCMD_VAR_DEPLOYED_AT: $CI_PIPELINE_CREATED_AT
DOCMD_VAR_BUILD_ID: $CI_PIPELINE_ID
ENVIRONMENT: production
artifacts:
paths:
- site/