Publicar artículos desde otro proyecto

Publicar artículos desde otro proyecto

Este playbook define el flujo para que un feature o proceso desarrollado en cualquier repositorio genere un artículo Markdown y lo publique en la base de conocimiento de Hábitat Digital sin copiar archivos manualmente.

La arquitectura separa responsabilidades:

• Repositorio del proyecto: produce y mantiene la documentación junto al código y la operación que describe.
• Repositorio de conocimiento: revisa, organiza, compila y publica el artículo en el sitio oficial.
• Equipo responsable: valida que el contenido sea correcto antes de exponerlo a usuarios.

El resultado esperado no es un commit directo a producción. Es una solicitud de cambio trazable hacia la rama desarrollo del repositorio de documentación. Después se sigue el flujo normal desarrollo → staging → produccion.

Cuándo usarlo

Usa este flujo cuando un cambio en otro proyecto modifica o crea:

• Un procedimiento operativo.
• Un manual de uso de un feature.
• Una guía de configuración para usuarios autorizados.
• Una FAQ o una corrección de contenido vinculada a una entrega.

No lo uses para publicar secretos, credenciales, datos personales, logs internos, decisiones de pricing o documentación que todavía no haya sido validada por el dueño funcional.

Modelo de publicación

Repositorio del proyecto
        │
        │  genera o mantiene un .md
        ▼
GitHub Action de publicación
        │
        │  copia el artículo y abre un Pull Request
        ▼
Repositorio habitat_docs / desarrollo
        │
        ├─ validación automática: npm run build
        ├─ revisión funcional y editorial
        ▼
staging → revisión visual → produccion → sitio publicado

La automatización propone el cambio; no lo aprueba ni lo publica directamente. Así se conserva el control editorial y la trazabilidad del cambio.

Contrato mínimo del artículo

Cada archivo debe ser Markdown (.md) o MDX (.mdx) y contener un frontmatter válido de Starlight:

---
title: Nombre claro del artículo
description: Qué resuelve y para quién.
---

## Objetivo

Explica el resultado que obtiene la persona usuaria.

## Requisitos previos

- Permiso o rol requerido.
- Configuración o información necesaria.

## Procedimiento

1. Realiza la primera acción.
2. Confirma el resultado.
3. Completa el flujo.

## Resultado esperado

Describe cómo saber que el proceso terminó correctamente.

## Consideraciones

Incluye límites, casos frecuentes y enlaces relacionados.

Reglas de contenido

• Un archivo representa un artículo y una ruta.
• El contenido explica qué debe hacer el usuario, no cómo está implementado el código.
• Los pasos deben ser verificables y estar escritos en orden.
• Las afirmaciones sensibles a versión deben indicar la versión o fecha de revisión.
• Las capturas deben vivir en public/ y tener texto alternativo.
• No se inventan permisos, pantallas, módulos, métricas ni resultados.
• Si el feature aún no está validado, el artículo no se publica: se corrige el origen o se marca explícitamente como borrador.

Configuración única por repositorio de proyecto

1. Crear el token de publicación

En GitHub, crea un token de máquina o una GitHub App con el alcance mínimo necesario para:

• Leer el repositorio del proyecto.
• Escribir una rama y crear un Pull Request en HabitatDigitalCo/habitat_docs.

Guárdalo como secreto del repositorio de proyecto llamado HABITAT_DOCS_TOKEN. Nunca lo escribas en el Markdown, en el workflow ni en los logs.

Recomendación: usar una GitHub App o un fine-grained token limitado exclusivamente al repositorio de documentación. El token debe poder crear ramas y Pull Requests, pero no debe tener permisos administrativos.

2. Copiar la plantilla

Copia plantillas/publicacion-documentacion/publicar-articulo.yml a:

.github/workflows/publicar-articulo.yml

Ajusta únicamente las variables del bloque env:

Variable	Ejemplo	Uso
ARTICLE_PATH	docs/features/mi-feature.md	Archivo generado en el repositorio de proyecto.
DOCS_REPO	HabitatDigitalCo/habitat_docs	Repositorio destino.
DOCS_BRANCH	desarrollo	Rama que recibe la propuesta.
DOCS_DESTINATION	src/content/docs/operacion/mi-feature.md	Ruta final dentro de la base de conocimiento.

La plantilla se ejecuta manualmente (workflow_dispatch) para evitar que cada commit técnico publique documentación sin intención. Más adelante puede conectarse a una etiqueta, release o evento de entrega si el equipo lo decide.

3. Definir el archivo fuente

Mantén el Markdown cerca del código o proceso que documenta. Ejemplo:

docs/features/mi-feature.md

El workflow no genera contenido con IA ni transforma silenciosamente el artículo: toma el archivo versionado, lo copia a la ruta destino y abre un Pull Request.

Operación paso a paso

Fase A — Preparar

1. Actualiza el artículo en el repositorio del proyecto.
2. Comprueba que el frontmatter tenga title y description.
3. Confirma que el artículo no contenga secretos ni datos de prueba.
4. Verifica que la ruta destino no sobrescriba otro artículo por accidente.
5. Ejecuta el preview local del proyecto si el artículo depende de capturas o comportamiento de la aplicación.

Criterio de salida: el archivo fuente describe una versión funcional y está listo para revisión.

Fase B — Emitir la propuesta

1. Abre Actions → Publicar artículo en la base de conocimiento.
2. Ejecuta el workflow sobre la rama que contiene el cambio validado.
3. Revisa los valores de ruta y destino antes de confirmar.
4. Espera a que la acción cree una rama y un Pull Request en habitat_docs.

Criterio de salida: existe un Pull Request con el artículo en desarrollo y un enlace al cambio de origen.

Fase C — Revisar en el repositorio de conocimiento

1. Revisa título, descripción, jerarquía, enlaces y terminología.
2. Confirma que la ruta encaja en la navegación existente.
3. Revisa las capturas en tamaño escritorio y móvil.
4. Lee el artículo como usuario final: debe poder completar el proceso sin conocer el repositorio fuente.
5. Solicita ajustes al equipo dueño del proyecto cuando la operación no esté suficientemente validada.
6. Fusiona únicamente cuando la compilación automática sea correcta y la revisión funcional esté aprobada.

Criterio de salida: el Pull Request fue aprobado y fusionado a desarrollo.

Fase D — Promover y publicar

1. Promueve desarrollo a staging mediante Pull Request.
2. Revisa el preview de staging: navegación, búsqueda, enlaces, imágenes y responsive.
3. Promueve staging a produccion mediante Pull Request.
4. Confirma el despliegue y abre la URL pública del artículo.
5. Registra en el ticket, release o proyecto de origen el enlace al artículo publicado.

Criterio de salida: la URL publicada responde correctamente y el cambio queda vinculado al feature o proceso que lo originó.

Política de cambios posteriores

• Corrección editorial menor: edita el artículo directamente en habitat_docs si no cambia el comportamiento del producto.
• Cambio de comportamiento: actualiza primero el artículo fuente del repositorio de proyecto y vuelve a emitir una propuesta.
• Cambio urgente: sigue el procedimiento de corrección urgente del repositorio de documentación y sincroniza después las ramas.
• Artículo obsoleto: no lo borres sin revisar enlaces entrantes; marca la sustitución y retira la navegación cuando corresponda.

La fuente de verdad del comportamiento es el proyecto que lo implementa; la fuente de verdad de la publicación es habitat_docs.

Responsabilidades y handoff

Momento	Responsable	Evidencia
Artículo técnicamente correcto	Equipo del proyecto	Commit o release de origen.
Artículo útil y terminológicamente consistente	Dueño de documentación / Producto	Pull Request revisado.
Validación de navegación y build	Repositorio de conocimiento	Checks verdes.
Aprobación de publicación	Responsable funcional	Aprobación en Pull Request.
Publicación	Flujo de ramas y Cloudflare	URL de staging y producción.

Diagnóstico de fallas

Síntoma	Causa probable	Acción
El workflow no encuentra el archivo	ARTICLE_PATH apunta a otra rama o ruta	Verifica la ruta relativa y ejecuta el workflow desde la rama correcta.
No puede clonar habitat_docs	Token ausente, vencido o sin acceso	Revisa HABITAT_DOCS_TOKEN y sus permisos mínimos. No pegues el token en un issue.
El Pull Request falla en build	Frontmatter, slug, sidebar o enlace inválido	Abre el log del check y corrige en la rama del Pull Request.
El artículo existe pero no aparece en el menú	La ruta no está incluida en el sidebar o no usa una carpeta autogenerada	Ajusta astro.config.mjs mediante un cambio revisado.
La página se ve bien en local pero no en staging	Recurso no copiado, ruta absoluta o diferencia de build	Revisa public/, las URLs generadas y el preview desplegado.
Se publicó contenido incorrecto	El origen estaba desactualizado o se eligió mal la ruta destino	Revierte o corrige mediante Pull Request y registra el incidente.

Lista de verificación

• El artículo está en .md o .mdx y tiene frontmatter válido.
• El comportamiento descrito fue validado por el equipo dueño.
• No hay secretos, datos personales ni logs internos.
• La ruta destino fue revisada.
• HABITAT_DOCS_TOKEN existe y tiene alcance mínimo.
• El workflow generó un Pull Request, no un commit directo a producción.
• El build automático pasó.
• La revisión funcional y editorial fue aprobada.
• Staging fue revisado visualmente.
• Producción responde y el enlace quedó registrado en el proyecto de origen.