Git Sync

Git Sync conecta un sitio de docs con una carpeta de un repositorio de GitHub. Cada página publicada es un archivo Markdown, así que tus docs tienen pull requests, historial y revisión como el resto de tu código, y quien escribe puede seguir usando el editor.

Requiere el plan Pro y sólo lo configuran propietarios y administradores.

Conecta un repositorio

Abre Docs, luego la pestaña Git Sync, y pulsa Conectar GitHub.
Instala la app de GitHub de Jotly en tu cuenta u organización. Jotly confirma que de verdad tienes acceso a esa instalación antes de vincularla.
Elige el repositorio, la rama y la carpeta (docs por omisión; déjala vacía para usar la raíz del repositorio).
Pulsa Iniciar sincronización. Si la carpeta ya tiene archivos .md, Jotly los importa. Si está vacía, Jotly exporta tus páginas publicadas.

Desconectar detiene la sincronización y deja tus páginas y tus archivos exactamente donde están.

Estructura del repositorio

Cada página publicada es un archivo y el árbol de carpetas sigue el slug de la página. Sólo se leen los archivos .md y jotly.json; cualquier otra cosa de la carpeta se ignora.

docs/  jotly.json  introduccion.md  guias/    webhooks.md    llaves-api.md

La página guias/webhooks vive en docs/guias/webhooks.md. Los borradores no se exportan.

Frontmatter

Las claves que Jotly lee son title, description, icon y sidebarTitle (el nombre más corto que se muestra en el menú). Cualquier otra clave, como noindex, se conserva y se vuelve a escribir sin tocarla.

docs/guides/webhooks.md

---title: Webhooksdescription: Receive events in your own server.icon: webhooksidebarTitle: Webhooks---Jotly signs every event with an HMAC header...

Los componentes como avisos, pestañas, pasos y tarjetas se escriben como MDX dentro del .md, en el subconjunto estilo Mintlify. Los bloques condicionales se escriben como <Conditional rule='...'>.

El menú vive en jotly.json. navigation es una lista ordenada y cada elemento es exactamente uno de estos:

{ "page": "guias/webhooks" }: una página por su slug. Agrega "hidden": true para sacarla del menú sin dejar de servirla.
{ "group": "Guías", "items": [ ... ] }: un grupo, que se puede anidar y acepta icon, expanded y hidden.
{ "link": "Estado", "href": "https://status.acme.com" }: un enlace externo.
{ "tab": "API", "slug": "api", "items": [ ... ] }: una sección de primer nivel. Si hay una pestaña, todo el primer nivel debe ser pestañas.

docs/jotly.json

{  "version": 1,  "navigation": [    { "page": "introduction" },    {      "group": "Guides",      "items": [        { "page": "guides/webhooks" },        { "page": "guides/api-keys" }      ]    },    { "link": "Status", "href": "https://status.acme.com" }  ]}

Cómo funciona la sincronización

De Jotly al repositorio

Cada publicación, despublicación, borrado o movimiento hace un commit atómico en tu rama. El commit lo firma la app Jotly Docs Sync y lleva como coautor el nombre y el correo de quien hizo el cambio.

Del repositorio a Jotly

Un push a la rama manda un webhook firmado. Jotly importa los .md que cambiaron, crea o actualiza la página, la publica y guarda la versión anterior en el historial. Borrar un archivo despublica la página; nunca la borra. Un cambio en jotly.json reescribe la navegación.

Sincronizar ahora y conflictos

Sincronizar ahora funciona en las dos direcciones: trae lo que cambió en el repositorio desde la última sincronización y luego sube lo que cambió en Jotly. Tras un force-push reconcilia toda la carpeta. Una tarea cada hora hace lo mismo con cada conexión por si se perdió algún webhook.

Si una página cambió en los dos lados, gana el cambio más reciente y la otra versión queda en el historial de la página. La pestaña Git Sync muestra un resumen de la última sincronización y los conflictos.

Límites

Hasta 2,000 archivos .md por carpeta. Pasado ese número, la sincronización se detiene con un error claro.
Los archivos de más de 1 MB se omiten.
Si GitHub limita la sincronización, la pestaña muestra el error y la siguiente corrida lo reintenta.

El menú de la página puede mostrar Editar en GitHub, que abre el archivo de la página en tu repositorio.

Ver también Portal de docs