Contenedores Interactivos Personalizados
Contenedores Interactivos Personalizados
Standard Markdown es excelente para el formato básico de texto, pero la documentación técnica requiere componentes estructurales. docmd extiende Markdown con una suite de contenedores isomórficos.
Estándar de Sintaxis de Contenedores
¿Migrando desde otros motores de documentación?
docmd admite alias de sintaxis de VitePress y Docusaurus directamente. Contenedores como :::tip, :::warning, :::note, :::details y :::caution funcionan sin modificaciones.
Referencia de Sintaxis Unificada
Todos los contenedores utilizan una sintaxis de bloques uniforme con etiquetas explícitas de apertura y cierre, comentarios en línea y atributos de clave-valor universales:
::: containerType title:"Título de Encabezado" icon:rocket # Encabezado con comentario
::: subContainer title:"Título de Elemento" icon:code-2 # Elemento subcontenedor explícito
Esta es el área principal de contenido.
Admite **Markdown**, imágenes y anidamiento profundo de componentes.
::: /subContainer # Cierre explícito de subcontenedor
::: /containerType # Cierre explícito del contenedor principal
| Componente | Palabra Clave | Caso de Uso Principal |
|---|---|---|
| Avisos / Callouts | callout |
Alertas semánticas para consejos, advertencias y avisos críticos. |
| Tarjetas / Cards | card |
Contenedores estructurales enmarcados para rejillas de funciones. |
| Rejillas / Grids | grids |
Grupos flexbox multicolumna de ajuste automático. |
| Pestañas / Tabs | tabs |
Paneles intercambiables interactivos con elementos explícitos ::: tab. |
| Pasos / Steps | steps |
Líneas de tiempo numeradas visuales con elementos explícitos ::: step. |
| Plegables / Collapsibles | collapsible |
Desplegables de acordeón interactivos para preguntas frecuentes. |
| Botones / Buttons | button |
Enlaces de navegación con llamadas a la acción destacadas de autocierre. |
| Etiquetas / Tags | tag |
Insignias de colores de autocierre para etiquetas de versión. |
| Secciones Destacadas / Hero | hero |
Encabezados de páginas de destino con soporte dividido y ::: slide. |
| Incrustaciones / Embeds | embed |
Incrustaciones para video, redes sociales y medios interactivos con embed-lite. |
| Registros de Cambios / Changelogs | changelog |
Historiales de versiones basados en líneas de tiempo con elementos explícitos ::: log. |
| Diagramas Mermaid | mermaid |
Diagramas de flujo, secuencia y mapas de arquitectura con controles por diagrama. |
| Contenedores Anidados | - | Patrones de composición recursiva para diseños complejos. |
Análisis Universal de Atributos y Clave-Valor (Universal Attribute & Key-Value Parsing)
Todos los encabezados de contenedores admiten parámetros posicionales, atributos clave-valor con nombre y comentarios en línea (# comentario):
::: button title:"Documentación" url:"/docs/getting-started" icon:book color:#3b82f6 # Atributos con nombre
::: card title:"Visión General de Arquitectura" icon:cpu # Título e icono
::: callout warning title:"Política de Seguridad" # Título y comentario
- Fallback Posicional: Las cadenas entre comillas (
"Mi Título") se asignan automáticamente atitleourlsegún el tipo de contenedor. - Sobrescrituras con Nombre:
title:"...",url:"...",icon:...,color:#...permiten especificar atributos en cualquier orden. - Comentarios en Línea:
# comentarioal final de la línea del encabezado se elimina antes del análisis.
Beneficios Estratégicos de los Contenedores
Los contenedores proporcionan algo más que un acabado visual; entregan Señales Semánticas de alta fidelidad al compilador docmd y a los agentes de IA:
- Mapeo de Contexto de IA: Marcar un bloque como
callout warninginstruye explícitamente a los LLM para priorizar esa advertencia durante el razonamiento. - Integridad Estructural: La combinación de
cardsygridspermite crear páginas de destino complejas directamente en Markdown sin código HTML innecesario. - Mantenibilidad del Código Fuente: Elimina la fragmentación de HTML sin procesar, manteniendo sus archivos
.mdlimpios, legibles y analizables por máquinas.
Composición Recursiva y Cierres Explícitos (Recursive Composition & Explicit Closers)
::: card title:"Visión General de Arquitectura" # Tarjeta principal
::: callout info title:"E/S Asíncrona" # Aviso interno
Este módulo utiliza una canalización de E/S no bloqueante asíncrona.
::: /callout # Cierra el aviso interno
::: button title:"Explorar Motor Central" url:"/#architecture"
::: /card # Cierra la tarjeta principal