Template Markdown: estructura y placeholders
Cómo escribir un template Markdown robusto para documentación generada.
Estructura recomendada
Un template Markdown de Capydox suele partir de este esquema:
- Título principal
- Tabla de contenidos
- Introducción
- Sección de endpoints
- Conclusión
Ejemplo base:
# {{collectionName}} - Documentación API{{tableOfContents}}{{introduction}}{{endpoints}}{{conclusion}}
Placeholders más usados
{{collectionName}}: nombre de la colección.{{collectionDescription}}: descripción de la colección.{{generatedDate}}: fecha de generación.{{version}}: versión detectada.{{baseUrl}}: URL base.{{tableOfContents}}: índice generado.{{introduction}}: bloque introductorio.{{endpoints}}: detalle completo de endpoints.{{conclusion}}: cierre del documento.
Buenas prácticas
- Usa títulos y subtítulos claros (
#,##,###). - Mantén una jerarquía estable para facilitar lectura y exportación PDF.
- Evita duplicar secciones generadas automáticamente si ya usas placeholders.
- Si usas branding, colócalo entre introducción y endpoints para mantener consistencia.
Errores comunes
- Olvidar
{{endpoints}}, lo que deja la documentación sin operaciones. - Sobrecargar el template con estilos inline en markdown (mejor usar CSS Styles).
- Mezclar contenido demasiado específico del proyecto cuando el template se reutilizará.
Relacionado: CSS Styles para templates, Alcances y template base de organización.