Sincronizar documentación desde Markdown

Usa Documentation → Sync docs para validar la documentación del repositorio y sincronizarla con las entradas de documentación del sitio de documentación dedicado.

Cómo abrirlo

Abre Documentation → Sync docs. La página muestra el directorio de origen de la documentación que va a analizar. Confirma ese directorio antes de ejecutar nada.

Necesitas permiso para editar y crear entradas de documentación y para gestionar sus categorías. La pantalla rechaza la operación cuando falta algún permiso requerido.

Requisitos previos

• El producto tiene un árbol docs numerado y seguro para el público.
• Cada tema contiene su documento índice.
• El manifiesto del producto usa la versión de esquema 1 y enumera cada nombre base de Markdown exactamente una vez.
• Los nombres base de directorios y de archivos Markdown no colisionan con los de otro producto mantenido.
• Los cambios de origen se han revisado antes de la sincronización, especialmente cuando afectan a documentos ya publicados.
• Mantén el Markdown de origen en inglés y configura los idiomas de destino en un único plugin multilingüe activo: Polylang o POM Translate.
• Los documentos largos pueden tardar varios minutos en traducirse. Mantén abierta la pestaña de sincronización y usa un tiempo de espera de la solicitud del hosting que admita la solicitud completa de documento de 330 segundos. Si una solicitud supera el tiempo de espera, espera a que termine cualquier sincronización activa y ejecuta la herramienta de nuevo; las traducciones completadas se reutilizan.
• Para Polylang, activa Documentation y sus categorías, configura un idioma de origen en inglés y usa Polylang Pro con slugs compartidos, enlaces permanentes limpios y URL específicas por idioma. La sincronización de traducciones requiere Polylang 3.7 o posterior.
• Con POM Translate, configura el inglés como idioma principal para que el documento canónico y sus URL representen el origen en inglés.
• La traducción automática debe configurarla el administrador del sitio. Usa DeepSeek y puede conllevar cargos del proveedor.

Qué hace

Por cada archivo Markdown que encuentra:

• Crea una entrada si ninguna coincide con él. Las entradas nuevas se crean como borradores, de modo que nada se publica sin la decisión de un editor.
• Actualiza una entrada existente cuando necesita el contenido canónico. Las entradas existentes conservan su estado actual: un documento publicado sigue publicado.
• Crea las categorías que reflejan la estructura de directorios y normaliza sus slugs.
• Aplica el orden del manifiesto a cada documento.
• Establece el título a partir del primer encabezado de nivel uno de Markdown y deriva el slug de la entrada del nombre del archivo de origen.
• Almacena un shortcode de renderizado de Markdown como contenido de la entrada, de modo que el archivo del repositorio siga siendo el cuerpo canónico.
• Traduce el documento completo a cada idioma activo distinto del inglés. Las traducciones que faltan se generan; las traducciones actuales se reutilizan; un origen en inglés modificado provoca una traducción nueva a partir del origen completo. Los nombres de imagen, el código, los destinos de Markdown y los slugs de URL se conservan.
• Crea entradas de idioma con Polylang, enlaza sus traducciones y asigna categorías traducidas. Cada entrada de idioma tiene el mismo slug y orden de lectura, con un idioma explícito en su shortcode. Con POM Translate, una única entrada canónica sirve a todos los idiomas. Su título visible y el título del documento usado por WordPress y Rank Math siguen el idioma seleccionado.

La sincronización no publica documentos nuevos, no elimina entradas cuyo origen desapareció y no decide si una entrada huérfana debe seguir siendo pública.

Los trabajos de traducción se ejecutan de forma secuencial, una solicitud al proveedor por documento e idioma de destino. Se admiten documentos de hasta 256 KB. Una respuesta fallida o no válida deja disponible la traducción anterior. Ejecuta la sincronización de nuevo para reanudar: las traducciones aceptadas se reutilizan aunque su entrada de idioma necesite reparación. Las asociaciones de Polylang interrumpidas se reparan usando las copias de idioma existentes; la sincronización no crea reemplazos para las copias que están en la papelera. Mantén abierta la pestaña del navegador; cerrarla detiene el resto de la cola. Una solicitud fallida puede haber incurrido igualmente en un cargo del proveedor.

Las categorías de Polylang existentes se pueden reutilizar cuando su idioma, slug y categoría superior coinciden con la jerarquía de documentación, aunque sus enlaces de traducción no se hayan configurado todavía. La sincronización enlaza esas categorías y actualiza sus nombres traducidos sin cambiar sus IDs ni sus slugs. Una categoría ya asociada a otro origen o a un grupo de traducción no relacionado requiere que un editor resuelva primero esa asociación.

El directorio de nivel superior pom-knowledge se excluye intencionadamente. Su Markdown de conocimiento empresarial no es documentación del producto, por lo que el análisis no entra en ese directorio, no lo valida como producto ni crea tareas de sincronización a partir de sus archivos.

Cómo ejecutarlo

1. Confirma el directorio de origen mostrado.
2. Selecciona Scan and sync docs.
3. Mantén la página abierta mientras Progress avanza por el análisis, el procesamiento de tareas y la comprobación de huérfanos.
4. Lee Tasks. Cada archivo informa pending, create, update, created, updated, already synchronized o failed. Un fallo muestra su motivo inmediatamente junto a la tarea; el resumen incluye enlaces de edición para las entradas sincronizadas.
5. Lee el Summary final y anota cualquier fallo o entrada sin origen.

Cómo leer el resumen

La última es la línea más útil de la pantalla. Encuentra documentos que quedaron atrás después de que un archivo se renombrara o eliminara: la forma silenciosa en que un sitio de documentación acumula páginas que nadie mantiene.

Cuando no hay ninguno, lo indica.

Fallos

Una tarea fallida se explica por sí misma. Los casos habituales incluyen:

• La ruta de Markdown no es válida — el archivo está fuera del directorio de origen de la documentación.
• Otro archivo Markdown se resuelve a la misma identidad — dos archivos producirían la misma entrada y categoría. Resuelve la colisión de nombre base o de ruta en el origen.
• Falló la validación del manifiesto — el manifiesto falta, está mal formado, incompleto, duplicado o enumera un archivo en el directorio equivocado. Corrígelo antes de volver a intentarlo.
• Falta un marcador protegido, está repetido o es desconocido, o se reordenaron código y enlaces — la respuesta fue rechazada. La traducción anterior sigue disponible; reintenta la sincronización.
• La traducción cambió la estructura de Markdown — compara el énfasis, las celdas de tabla, las listas y el formato del código con el origen en inglés. El error identifica el primer elemento renderizado que difiere. Los nombres de elementos coincidentes pueden indicar atributos técnicos o contenido de código modificados.
• El origen cambió durante la traducción — ejecuta la sincronización de nuevo para traducir el origen completo más reciente.
• No se pudo conservar un slug traducido — revisa la configuración de idioma y la entrada o categoría en conflicto. La sincronización no asigna silenciosamente un slug diferente.
• Otro elemento usa la misma URL traducida — resuelve la URL en conflicto en POM Translate y sincroniza de nuevo. El documento conserva su slug original y su traducción aceptada se reutiliza.
• Varias copias de idioma pertenecen a un mismo origen — revisa y corrige las asociaciones duplicadas de Polylang antes de reintentar.
• Una categoría existente pertenece a otro origen o grupo de traducción — revisa sus asociaciones de idioma y traducción. La sincronización no desvinculará una categoría no relacionada para reutilizar su slug.
• Un documento está en la papelera — restáuralo antes de sincronizar su origen o traducción.

Después de sincronizar

1. Revisa cada borrador nuevo. Los documentos nuevos no se publican por ti.
2. Revisa las entradas publicadas afectadas. Su estado se conserva, por lo que un cambio sincronizado puede ser público de inmediato.
3. Comprueba "Posts without a Markdown source" y decide por separado si restaurar el archivo, pasar la entrada a borrador o moverla a la papelera.
4. Comprueba el orden de lectura y la navegación en el sitio público. Provienen de la jerarquía de origen y del manifiesto.

Editar el contenido de origen y las traducciones

El contenido de un documento sincronizado proviene de su archivo Markdown. Editarlo en el editor de WordPress funciona hasta la siguiente sincronización, que lo sobrescribe.

Cambia el Markdown en inglés y sincroniza de nuevo. Para corregir una traducción, abre su entrada de documentación, expande Document translations, edita el título traducido o el Markdown completo y guarda la entrada. Las mismas traducciones están disponibles al editar la entrada de origen canónica.

Mantén sin cambios el código, los destinos de enlace y la estructura de Markdown. Las ediciones se validan antes de guardarse. El panel conserva la traducción aceptada anterior para copiarla y recuperarla. Las correcciones manuales siguen en uso mientras el origen en inglés no cambie; cambiar el origen las reemplaza deliberadamente con una traducción nueva durante la sincronización.

Mantén el nombre de marca literal POM Theme y el mismo número de referencias. Su posición alrededor del código en línea puede seguir la gramática natural del idioma de destino; el código, los enlaces y las rutas de interfaz deben conservar su orden original.

Si una edición se rechaza o entra en conflicto con una traducción más reciente, el panel conserva una copia de recuperación privada de tus ediciones enviadas durante 24 horas. Cópiala y revísala antes de reintentar; la traducción aceptada sigue apareciendo a los lectores.

Después de cambiar de Polylang a POM Translate, configura las configuraciones regionales de destino coincidentes y sincroniza de nuevo. Las traducciones almacenadas se reutilizan, los shortcodes canónicos pasan a ser automáticos y las antiguas copias de Polylang se conservan para revisión editorial mientras las consultas públicas de documentación y los sitemaps de Rank Math usan entradas canónicas. Revisa las URL de idioma, el estado de publicación, la navegación y los enlaces antes de hacer público el cambio.

Resultado esperado

Cada archivo de origen válido se crea, se actualiza o se informa como ya sincronizado; ninguna tarea queda fallida; y cada entrada sin origen se lista para la decisión de un editor. Las entradas nuevas permanecen como borradores hasta que se publiquen explícitamente.

El orden proviene del manifiesto

El manifiesto de cada producto enumera sus documentos en orden de lectura, y la sincronización aplica ese orden. Reordenar a mano un documento sincronizado en el Docs library se deshace la próxima vez que sincronices.

Solución de problemas

• No tienes permiso para sincronizar: solicita los permisos necesarios de entradas y categorías de documentación; no compartas una cuenta de administrador.
• Una entrada no cambia: comprueba si la tarea indica Already synchronized y verifica que hayas editado el archivo de origen en el directorio de origen mostrado.
• Un archivo renombrado deja dos entradas: la sincronización no elimina la entrada antigua. Revísala en Posts without a Markdown source.
• Los cambios de orden no aparecen: confirma que el array del manifiesto cambió, sincroniza de nuevo y limpia cualquier caché de página relevante.