Sincronización con GitHub
Esta es una función beta. Agradecemos sus comentarios.
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 separada.
Ejecutar GitHub Actions para validar o transformar la documentación antes de sincronizarla.

Configuración de GitHub Sync
La configuración se realiza tanto en GitHub como en DeveloperHub.
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.En DeveloperHub, abre Project Settings → Integrations.
Haz clic en Connect junto a GitHub, completa la autorización en GitHub y concede acceso a los repositorios que quieres sincronizar.
Si tienes varios proyectos, elige todos los repositorios con los que quieres sincronizar.
Volverás a DeveloperHub. Abre el panel de configuración 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 separada (consulta Draft branch).
Haz clic en Start sync para ejecutar la primera sincronización. Puede tardar unos minutos.
En una primera sincronización de tipo Export, se sobrescriben los archivos del repositorio que estén en las mismas rutas que los archivos exportados.
Cambiar la ruta base redefine qué parte del repositorio se refleja, por lo que DeveloperHub restablece el estado de sincronización y vuelve a ejecutar la sincronización inicial.
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, salvo que actives una draft branch.
DeveloperHub hace commit en el repositorio cada vez que:
Cambia el contenido de una página publicada (esté listada o no).
Cambia la configuración de una página.
Se crea, mueve, renombra o elimina una página.
Se crea una sección de documentación, cambia su configuración o se elimina.
Se crea una versión, cambia su configuración 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 entradas.
Se crea, edita o archiva un bloque sincronizado.
Cambia la configuración 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 la configuración equivalente se actualiza en DeveloperHub.
Si se produce un error al sincronizar cambios de GitHub a DeveloperHub, enviamos un correo a la persona que hizo push del commit.
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 de URL. El orden y la agrupación se definen en _nav.yaml, no en la estructura de carpetas.
Desde la ruta base, el repositorio se organiza así:
developerhub.yaml (raíz del repositorio): el
titley elvariablesdel proyecto, además de los bloquessettingsynavigationque contienen tu personalización para lectores. Todo lo demás en la raíz (tuREADME,LICENSE,.gitignore, etc.) no se modifica._theme/: los archivos de tu personalización para lectores: 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: configuración de la versión, además del orden de las secciones de documentación y referencias.
{version}/{documentation}/_settings.yaml: configuración 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 entrada. 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 subido junto a ella.
El contenido de las páginas se escribe en Markdoc; la configuración y la navegación están en YAML.
Para consultar las reglas completas (cómo añadir, mover, anidar, agrupar, reordenar u ocultar páginas, versiones y referencias; las claves exactas de configuración; y los problemas de la conversión de ida y vuelta), usa la Agent Skill organize-docs-repo, o léela en GitHub.
Changelogs
Los changelogs se sincronizan junto con tus páginas, por lo que puedes escribir una nota de versión en el repositorio y abrir una 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 entrada es un único archivo, y su nombre sin .md es el slug de la entrada. El frontmatter de una entrada incluye tres campos, seguidos del cuerpo en Markdoc:
title: el título de la entrada.
date: la fecha que ven los lectores y por la que se ordenan las entradas. Basta con una fecha simple; añade una hora (
2026-08-04 14:30:00) para ordenar varias entradas del mismo día.published: si la entrada está publicada. Si lo omites, la entrada queda sin publicar, así 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 renombra la carpeta para cambiarla. Un changelog sin entradas sigue siendo válido; su _settings.yaml es lo que lo mantiene en el repositorio.
changelogs en la ruta base está reservado, por lo que una versión no puede usarlo como slug. Si tu proyecto ya se sincroniza, tus changelogs existentes se confirman en el repositorio en la siguiente sincronización.
Hay dos diferencias con las páginas. Los enlaces en el cuerpo de una entrada usan rutas completas del sitio, como /support-center/getting-started, no las rutas relativas .md que usan las páginas. Y las entradas no tienen estado de borrador, por lo que los archivos de changelog no se reflejan en una draft branch; 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 contiene el título, seguido del contenido del bloque en Markdoc:
El ID de un bloque debe empezar con 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.
Un bloque con variables las enumera en su frontmatter bajo variables, cada nombre con su valor predeterminado. En el contenido, escribe {% $name %} en texto y %name% en un bloque de código:
Escribe cada valor entre comillas, como '2.10', para que YAML lo lea como texto y no como número. Un valor es una línea de texto, así que un salto de línea en él se convierte en un espacio.
Una página define sus propios valores en la etiqueta synced, cada uno entre comillas. Cualquier variable que omita, o que defina con un valor vacío, muestra el valor predeterminado del bloque:
El nombre de una variable no se puede cambiar en el editor, así que cambiar un nombre en variables se interpreta como eliminar una variable y añadir otra. Los valores de las páginas para el nombre anterior dejan de mostrarse.
Los bloques sincronizados no tienen estado de borrador, así que un bloque que subes queda activo de inmediato en todas las páginas que lo usan.
Eliminar un archivo de _synced-blocks/ archiva el bloque en lugar de borrarlo, igual que al archivar en el editor. Las páginas que lo insertan siguen mostrándolo; simplemente deja de ofrecerse cuando tus compañeros eligen un bloque para reutilizar. Si vuelves a añadir el archivo, se restaura.
Reader Customisation
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: tus etiquetas HEAD personalizadas.
_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, subidos como archivos de imagen reales. Sirve cualquier extensión de imagen común, así que
logo.svgse reconoce igual quelogo.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 interruptor 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
icones opcional, y omitir la clave borra un icono definido 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 informa como advertencia en lugar de almacenarse.
Las carpetas en la ruta base cuyo nombre empieza con un guion bajo están reservadas para DeveloperHub, al igual que changelogs. Una versión no puede usar un slug que empiece con un guion bajo.
Vista previa en tu editor
Instala la extensión DeveloperHub Preview en VS Code o en un IDE de JetBrains para ver cada página como la verán tus lectores, junto al archivo, mientras escribes.
Edición con agentes de IA
Si editas el repositorio con un agente de programación de IA (en tu IDE o en un pipeline de docs-as-code), instala las Agent Skills de DeveloperHub para que escriba Markdoc correcto y la estructura de repositorio correcta.
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 write-markdoc para la sintaxis de Markdoc dentro de una página, y organize-docs-repo para la estructura del repositorio (navegación, configuración, imágenes, referencias, changelogs y el aspecto de tu sitio). Juntas mantienen las ediciones de un agente sin pérdidas, de modo que se sincronizan de vuelta sin cambios espurios ni contenido perdido. Una tercera skill, migrate-docs, traslada tu documentación desde otra herramienta a una carpeta que puedes importar de esta manera.
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 la configuración, navegación, especificaciones de referencia o frontmatter de entradas de changelog no válidos, hacen fallar la comprobación.
Todo lo demás se informa como advertencia.
Tres cosas la mantienen en verde:
Mantén un movimiento y una reescritura de contenido en commits separados. Hacer ambas cosas 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 seguirí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 tocaste, así que revísalos tú mismo.
Las referencias y las secciones de documentación comparten un único espacio de nombres de slugs por versión, por lo que una referencia no puede usar el slug de una sección de documentación, ni al revés.
Rama de borrador
De forma predeterminada, solo se sincronizan las páginas publicadas, y lo hacen con la rama que elegiste durante la configuración. Opcionalmente, puedes replicar las ediciones de borrador sin publicar en una rama aparte, para que los redactores y los usuarios de Git colaboren en los borradores antes de que se publiquen.
En el panel Docs Sync, en la pestaña Sync, activa Sync draft edits to a branch y establece un Draft branch name (el valor predeterminado es developerhub-drafts).
La rama de borrador 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 realizado en la rama de borrador 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 requests de GitHub.
Historial de páginas 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 elimina de forma definitiva el contenido asociado.
El archivo
.mdde una página: la página se oculta de tu navegación, pero conserva su contenido, comentarios e historial.Una versión, sección de documentación o referencia de API: deja de estar en tu sitio publicado y en el 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 a su lugar, con todo lo que tenía. Pasado ese plazo, la eliminación es definitiva y lo asociado a esas páginas, incluidos los comentarios y el feedback de los lectores, desaparece con ellas.
Tu última versión y la única sección de documentación de una versión nunca se eliminan. Borrar una de esas carpetas se notifica como una advertencia y no ocurre nada más.
Cuando se bloquea un cambio
Si un cambio que llega desde el repositorio eliminara 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.yamlen 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 deseado, 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 ese 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á 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 propia que tiene DeveloperHub de la lista de archivos de tu repositorio ha dejado de coincidir con el repositorio. No hay nada que arreglar por tu parte y volver a hacer push no lo resolverá: haz clic en Repair and resume sync en ese 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 conservan; 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 en los 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 por parte de DeveloperHub.
Por el momento no. GitHub es el único proveedor de Git con el que sincronizamos actualmente. Si necesitas GitLab, contáctanos y cuéntanoslo.
Need help? Visit our community forums or contact us.