GitHub Sync

Con DeveloperHub puedes configurar una sincronización bidireccional con un repositorio de GitHub. Esto te permite:

• Escribir tu documentación en DeveloperHub y mantener una copia permanente en GitHub.

• Editar tu documentación en GitHub si tu equipo prefiere trabajar en un editor de texto local, y que esos cambios se reflejen en DeveloperHub al hacer push.

• Permitir que los lectores sugieran ediciones desde GitHub, usando las herramientas de edición y comentarios propias de GitHub.

• Añadir tu propio flujo de trabajo de GitHub:

  • Revisar los cambios mediante pull requests.

  • Mantener borradores sin publicar en una rama aparte.

  • Ejecutar GitHub Actions para analizar (lint) o transformar la documentación antes de que se sincronice.

Configuración de GitHub Sync

La configuración se realiza tanto en GitHub como en DeveloperHub.

1. Crea el repositorio con el que quieres sincronizar y asegúrate de que tenga al menos un commit (para que tenga una rama). Basta con un commit inicial que añada un README.

2. En DeveloperHub, abre Project Settings → Integrations.

3. Haz clic en Connect junto a GitHub, completa la autorización en GitHub y concede acceso a los repositorios que quieres sincronizar.

Volverás a DeveloperHub. Abre el panel de ajustes Docs Sync (Project Settings → Developers → Docs Sync). Desde aquí configurarás y supervisarás la sincronización a partir de ahora. En la pestaña Sync, define:

• Repository: elige entre los repositorios a los que puede acceder la GitHub App de DeveloperHub.

• Branch: la rama en la que DeveloperHub hace commits y de la que extrae cambios.

• Base path (opcional): para monorepos, el directorio donde se encuentra tu documentación (por ejemplo, docs/files). Déjalo vacío para sincronizar desde la raíz del repositorio.

• First sync: la dirección de la primera sincronización. Elige Export para hacer commit de tus páginas existentes de DeveloperHub en el repositorio, o Import para traer los archivos del repositorio a DeveloperHub.

• Reader edits: activa Let readers suggest edits on GitHub para mostrar un enlace "Edit on GitHub" en cada página.

• Draft branch (opcional): refleja los borradores sin publicar en una rama aparte (consulta Draft branch).

Haz clic en Start sync para ejecutar la primera sincronización. Puede tardar unos minutos.

Qué se sincroniza

Se sincronizan todas las páginas publicadas. Las páginas que siguen en borrador y nunca se han publicado no se sincronizan, a menos que actives una rama de borradores.

DeveloperHub hace commit en el repositorio cuando:

• Cambia el contenido de una página publicada (esté o no listada).

• Cambian los ajustes de una página.

• Se crea, mueve, renombra o elimina una página.

• Se crea una sección de documentación, cambian sus ajustes o se elimina.

• Se crea una versión, cambian sus ajustes o se elimina.

• Cambia el orden o la agrupación de la navegación.

• Se añade o actualiza una referencia de API.

• Se crea, edita o elimina un changelog o una de sus publicaciones.

• Se crea, edita o archiva un bloque sincronizado.

• Cambian los ajustes del proyecto, incluidos el título, las variables y la personalización para lectores.

Cada vez que se crea o actualiza un archivo correspondiente en el repositorio, el contenido o los ajustes correspondientes se actualizan en DeveloperHub.

Estructura del repositorio

La idea central es que la ruta es la estructura y el nombre de archivo es el slug. La carpeta de una página determina su versión, su sección de documentación y sus páginas superiores; su nombre de archivo (sin .md) es su slug en la URL. El orden y la agrupación están en _nav.yaml, no en la estructura de carpetas.

A partir de la ruta base, el repositorio se organiza así:

• developerhub.yaml (raíz del repositorio): el title y el variables del proyecto, además de los bloques settings y navigation que contienen tu personalización para lectores. Todo lo demás en la raíz (tu README, LICENSE, .gitignore, etc.) se deja intacto.

• _theme/: los archivos de tu personalización para lectores, es decir, la hoja de estilos, el HTML personalizado, el logotipo y el favicon (consulta Reader Customisation).

• _synced-blocks/: tus bloques sincronizados, un archivo por bloque (consulta Synced Blocks).

• {version}/_settings.yaml: ajustes de la versión, además del orden de las secciones de documentación y las referencias.

• {version}/{documentation}/_settings.yaml: ajustes de la documentación.

• {version}/{documentation}/_nav.yaml: el orden de la barra lateral, categorías, etiquetas, separadores, enlaces externos y cualquier icono de esa documentación.

• {version}/refs/: especificaciones de referencias de API, un archivo por referencia.

• changelogs/: tus changelogs, una carpeta por changelog y un archivo por publicación. Los changelogs pertenecen al proyecto y no a una versión, por lo que esta carpeta está junto a las carpetas de versiones (consulta Changelogs).

• assets/: imágenes que la sincronización ha almacenado. En una página también puedes referenciar una imagen mediante una ruta relativa a un archivo que hayas incluido en un commit junto a ella.

El contenido de las páginas se escribe en Markdoc; los ajustes y la navegación, en YAML.

Changelogs

Los changelogs se sincronizan junto con tus páginas, de modo que puedes escribir una nota de versión en el repositorio y abrir un pull request como con cualquier otro cambio.

Cada changelog es una carpeta dentro de changelogs/, con el nombre de su ruta (el segmento que ven los lectores en su URL). Cada publicación es un único archivo, y su nombre de archivo sin .md es el slug de la publicación. El frontmatter de una publicación incluye tres campos, seguidos del cuerpo en Markdoc:

• title: el título de la publicación.

• date: la fecha que ven los lectores y por la que se ordenan las publicaciones. Basta con una fecha simple; añade una hora (2026-08-04 14:30:00) para ordenar varias publicaciones del mismo día.

• published: si la publicación está activa. Si lo omites, la publicación permanece sin publicar, de modo que subir un archivo nunca publica una entrada por accidente.

El _settings.yaml propio del changelog admite title, description y published. Su ruta es el nombre de la carpeta, así que cambia el nombre de la carpeta para modificarla. Un changelog sin publicaciones sigue siendo válido; su _settings.yaml es lo que lo mantiene en el repositorio.

Hay dos diferencias respecto a las páginas. Los enlaces en el cuerpo de una publicación usan rutas completas del sitio, como /support-center/getting-started, y no las rutas relativas .md que usan las páginas. Y las publicaciones no tienen estado de borrador, por lo que los archivos de changelog no se reflejan en una rama de borradores; edítalos en tu rama publicada.

Synced Blocks

Los bloques sincronizados están en _synced-blocks/, un archivo por bloque, en una carpeta plana. El nombre de archivo sin .md es el ID del bloque, el mismo ID que usas en una página, así que _synced-blocks/beta-feature.md es el bloque que insertas como {% synced id="beta-feature" /%}.

El frontmatter incluye el título, seguido del contenido del bloque en Markdoc:

El ID de un bloque debe empezar por una letra minúscula y usar solo letras minúsculas, números y guiones. Como el ID es el nombre de archivo, y el ID de un bloque no puede cambiar una vez creado, renombrar el archivo se interpreta como eliminar un bloque y crear otro, no como un cambio de nombre.

Los bloques sincronizados no tienen estado de borrador, así que un bloque que subes se publica de inmediato en todas las páginas que lo usan.

Personalización para lectores

El aspecto de tu documentación publicada también se sincroniza, repartido en dos lugares según sea un archivo o un valor.

Los archivos de texto libre y las imágenes están en _theme/:

• _theme/custom.css: tu CSS personalizado.

• _theme/head.html: tu HTML personalizado para el head de la página.

• _theme/footer.html: tu pie de página personalizado.

• _theme/logo.png, _theme/logo-dark.png y _theme/favicon.png: tu logotipo, tu logotipo para fondos oscuros y tu favicon, confirmados como archivos de imagen reales. Sirve cualquier extensión de imagen común, así que logo.svg se reconoce igual que logo.png.

Un archivo ausente significa "usar el valor predeterminado", por lo que un proyecto con el logotipo predeterminado no tiene ningún archivo logo. Eliminar uno de estos archivos borra esa personalización por completo, a diferencia de una eliminación en otras partes de la sincronización (consulta When You Delete Files).

Los ajustes que son valores y no archivos están en developerhub.yaml, bajo dos bloques:

• settings: opciones de tema como el modo oscuro, el selector de tema, tus colores y la fuente.

• navigation: los enlaces de la navegación superior (hasta cuatro), si se abren en una pestaña nueva y tus grupos de navegación. Un grupo enumera por slug las secciones de documentación y referencias de API que contiene, y un changelog por su ruta. Su icon es opcional, y omitir la clave borra un icono establecido en el editor.

Un valor que no podemos interpretar, como un color que no es un color, se restablece a su valor predeterminado y se notifica como advertencia en lugar de almacenarse.

Edición con agentes de IA

Si editas el repositorio con un agente de programación con IA (en tu IDE o en un flujo de docs-as-code), instala las Agent Skills de DeveloperHub para que escriba Markdoc correcto y la estructura de repositorio adecuada.

En Claude Code, instálalas como un plugin, que es el único canal que se actualiza solo:

Para Cursor, Codex y otros agentes, usa la CLI skills:

El paquete incluye dos skills: write-markdoc para la sintaxis de Markdoc dentro de una página, y organize-docs-repo para la estructura del repositorio (navegación, ajustes, imágenes, referencias y changelogs). Juntas hacen que las ediciones de un agente no pierdan información, de modo que se sincronizan de vuelta sin cambios innecesarios ni contenido perdido.

Comprobaciones de pull requests

En los repositorios sincronizados mediante la GitHub App, DeveloperHub comprueba cada pull request cuya base sea tu rama sincronizada. La comprobación es una simulación de solo lectura de la sincronización: informa de lo que ocurriría y nunca escribe nada.

• Los enlaces o imágenes relativos rotos, y los ajustes, la navegación, las especificaciones de referencias o el frontmatter de publicaciones de changelog no válidos, hacen fallar la comprobación.

• Todo lo demás se notifica como advertencia.

Tres cosas la mantienen en verde:

• Mantén un movimiento y una reescritura de contenido en commits separados. Hacer ambos a la vez puede impedir el emparejamiento de renombrados, de modo que la página se trataría como una eliminación más una página nueva, y su historial y comentarios no la acompañarían.

• El análisis de enlaces solo cubre los archivos modificados. Mover o eliminar una página no señala los enlaces a ella desde páginas que no has tocado, así que compruébalos tú mismo.

• Las referencias y las secciones de documentación comparten un espacio de slugs por versión, por lo que una referencia no puede usar el slug de una sección de documentación, ni viceversa.

Rama de borradores

De forma predeterminada solo se sincronizan las páginas publicadas, y lo hacen en la rama que elegiste durante la configuración. Opcionalmente puedes reflejar las ediciones de borrador sin publicar en una rama aparte, para que redactores y usuarios de Git colaboren en los borradores antes de publicarlos.

En el panel Docs Sync, en la pestaña Sync, activa Sync draft edits to a branch y define un Draft branch name (el valor predeterminado es developerhub-drafts).

La rama de borradores es solo de contenido: incluye el contenido de las páginas, no la estructura. El trabajo estructural (añadir, mover y renombrar páginas, la navegación y los ajustes, incluido el frontmatter de las páginas) corresponde a la rama publicada. Un cambio estructural hecho en la rama de borradores se aplaza, no se aplica.

Permitir que los lectores editen en GitHub

Activa Let readers suggest edits on GitHub en el panel Docs Sync para mostrar un enlace Edit on GitHub en cada página. El enlace abre el archivo fuente de la página en tu rama sincronizada, donde un lector puede proponer un cambio mediante el flujo normal de edición y pull request de GitHub.

Historial de la página y actividad de sincronización

Cuando llega una edición desde GitHub, el historial de ediciones de la página registra el mensaje del commit y enlaza el SHA del commit, de modo que puedes abrir el commit exacto en GitHub.

La pestaña Activity del panel Docs Sync tiene un feed Sync activity que muestra las ejecuciones de conciliación recientes: la dirección de cada ejecución (DeveloperHub → Repo o Repo → DeveloperHub), qué cambió (por ejemplo "3 pages" o "1 API reference"), su commit y cuándo se ejecutó. Un indicador de estado en la parte superior muestra si el proyecto está In sync, tiene Changes pending o aún no se ha sincronizado.

Cuando eliminas archivos

Eliminar un archivo del repositorio no borra de forma definitiva el contenido asociado.

• El archivo .md de una página: la página se oculta de tu navegación, pero conserva su contenido, sus comentarios y su historial.

• Una versión, sección de documentación o referencia de API: se retira de tu sitio publicado y del editor.

• Una publicación del changelog: la publicación deja de estar publicada.

Restaura el archivo o directorio en el repositorio en un plazo de 30 días y el contenido vuelve donde estaba, con todo lo que tenía. Pasado ese plazo, la eliminación es definitiva y lo que estaba asociado a esas páginas, incluidos los comentarios y los comentarios de los lectores, se va con ellas.

Tu última versión y la única sección de documentación de una versión nunca se eliminan. Eliminar una de esas carpetas se notifica como advertencia y no ocurre nada más.

Cuando se bloquea un cambio

Si un cambio que llega desde el repositorio eliminaría la mayor parte de tu documentación, DeveloperHub lo rechaza en lugar de aplicarlo. No se elimina ni se modifica nada. La ejecución aparece en el feed Sync activity como Change blocked, nothing was changed, con el motivo, y el indicador de estado en la parte superior del panel muestra Sync paused. También enviamos un correo a quien hizo el push del commit, o al propietario del proyecto si esa persona no tiene una cuenta de DeveloperHub en el proyecto.

Un cambio se bloquea cuando:

• Falta developerhub.yaml en la raíz del repositorio, o el repositorio no contiene ninguna documentación. Normalmente significa que la rama o el repositorio apuntan a un lugar no previsto, o que se revirtió la exportación inicial.

• El cambio eliminaría todas las versiones.

• El cambio eliminaría la mayoría de tus páginas.

La sincronización permanece en pausa en ese commit hasta que se corrija el repositorio, de modo que un push posterior no pueda colarse mientras el problema siga ahí. Haz push de una corrección a la rama sincronizada y la siguiente sincronización se ejecutará con normalidad, o abre la pestaña Activity del panel Docs Sync y haz clic en Check the repository again para probarlo en el momento.

Si la eliminación era realmente intencionada, haz clic en Apply the change anyway en ese panel y confirma con Yes, apply it. Lo que se elimine esperará entonces los mismos 30 días que cualquier otra eliminación. La opción existe para un cambio que elimina versiones o páginas; un bloqueo por falta de developerhub.yaml requiere en cambio contactar con soporte.

La sincronización también puede pausarse porque la copia que tiene DeveloperHub de la lista de archivos de tu repositorio ha dejado de coincidir con el repositorio. No hay nada que corregir por tu parte y volver a hacer push no lo solucionará: haz clic en Repair and resume sync en el mismo panel.

Desconectar GitHub Sync

Para dejar de sincronizar, abre Project Settings → Developers → Integrations y usa Disconnect GitHub en la tarjeta de GitHub. Los archivos de tu repositorio se mantienen; solo se elimina la conexión.

Al desconectar también se desvinculan los repositorios de código que leía el agente de IA (consulta Documentación autoactualizable), por lo que tendrás que vincularlos de nuevo si te vuelves a conectar.

También puedes eliminar la aplicación DeveloperHub - Sync desde tus ajustes de GitHub (en los ajustes de aplicaciones de GitHub de tu cuenta personal o de tu organización). Una vez eliminada, la conexión se libera automáticamente en DeveloperHub.