Docs as code significa escribir documentación con las mismas herramientas y el mismo flujo que el software: archivos de texto plano, control de versiones, revisiones y automatización. Markdown en un repositorio Git es la forma más común de hacerlo.
Por qué lo hacen los equipos
- Revisiones. Los cambios de documentación pasan por pull requests, como el código.
- Historial. Cada cambio tiene autor, fecha y motivo.
- Cercanía. La documentación vive junto al código que describe, así que cambian juntos.
- Automatización. La validación y la publicación ocurren sin que nadie presione publicar.
El flujo
- Escribe o edita Markdown en tu editor.
- Abre un pull request.
- CI valida el contenido.
- Al hacer merge, CI lo publica.
Con Sentilis, los pasos 3 y 4 son dos ejecuciones del mismo comando del CLI.
Validar sin publicar
--dry-run revisa cada entrada de la carpeta sin subir nada. Es una buena verificación para pull requests:
sentilis sync ./docs --dry-runPublicar en el merge, todo o nada
--strict aborta toda la ejecución si alguna entrada tiene un problema de validación, así un archivo con errores hace fallar el pipeline en lugar de publicar medio cambio:
sentilis sync ./docs --strictAutentícate primero con sentilis auth login y el token de tu perfil. En CI, guarda el token como secreto y no en el repositorio.
Estructura del repositorio
repo/
├── src/
└── docs/
└── press/
└── guia-de-usuario/
├── index.md
├── instalacion.md
├── configuracion.md
└── attachments/guia-de-usuario/ es una entrada: index.md es la página principal y los demás archivos son sus secciones. Agrega más entradas a su lado para otros temas.
Sobre los borradores
Marca las páginas con status: draft mientras están en progreso. Se pueden hacer merge sin que aparezcan en el sitio, y publicarse después cambiando el estado a published.
Siguientes pasos
- Configura el pipeline con GitHub Actions.
- Aprende el resto del CLI en publicar desde la línea de comandos.