Synchronisation de la documentation Markdown vers le CMS

Ce document est un manuel opérationnel destiné aux flux de travail IA/opérateur de confiance qui synchronisent les fichiers de documentation Markdown modifiés du dossier docs/ du dépôt vers des pages de documentation WebBlocks CMS liées à leur source. Il s'agit d'indications produit purement documentaires. Il n'ajoute ni moteur de synchronisation à l'exécution, ni endpoint, ni migration, ni commande Artisan, ni script, ni job, ni file d'attente, ni table de base de données, ni processus de publication, ni connexion à une cible en production.

Les fichiers Markdown sous docs/ restent la source de vérité de la documentation technique de WebBlocks CMS. Les pages de documentation du CMS sont des dérivés générés, en brouillon ou publiés, de ces fichiers Markdown. Ce flux de travail existe pour que les modifications de documentation réalisées lors du développement normal du produit puissent être répercutées dans un site de documentation du CMS sans traiter la page du CMS comme la copie faisant autorité.

Il s'agit d'un flux de travail IA/opérateur, et non d'une synchronisation automatique à l'exécution. Le CMS ne doit ni surveiller le dépôt, ni récupérer des fichiers Markdown, ni modifier du contenu de lui-même. Un opérateur ou un outil IA de confiance planifie, valide et, éventuellement, applique des mises à jour sûres en brouillon via l'Internal Content API.

Le modèle doit fonctionner pour n'importe quelle installation du CMS ou site de documentation cible. La documentation et les rapports doivent rester génériques et ne doivent contenir ni nom réel de site cible, ni domaine réel, ni jeton d'API réel, ni chemin absolu local, ni journal brut, ni valeur d'environnement.

Les futurs opérateurs doivent pouvoir utiliser des prompts concis tels que :

À partir de ces commandes courtes, l'IA/l'opérateur doit déduire le flux de travail standard :

• utiliser les fichiers Markdown sous docs/ comme ensemble de sources candidates
• préférer les fichiers modifiés à une analyse complète de l'arborescence docs
• lire le front matter cms_sync et les métadonnées de source
• découvrir l'API du CMS cible depuis GET /webadmin/api
• n'utiliser que des contrats de contenu et des handles de bloc découverts
• faire correspondre les pages du CMS liées à leur source par identité de source avant le chemin
• produire un plan et un rapport de validation par fichier
• n'appliquer que lorsque la commande autorise explicitement un apply sûr en brouillon ou que l'utilisateur approuve le plan exact
• ne jamais publier sauf si l'utilisateur le demande explicitement et que le jeton dispose de content.publish

Update employé seul signifie planifier, valider et appliquer des modifications sûres en brouillon uniquement lorsque l'instruction de l'utilisateur autorise clairement l'apply. Cela n'implique ni publication, ni modification de la navigation, ni écrasement de page en ligne, ni import de médias, ni automatisation du navigateur.

Utilisez cet ordre pour décider quels fichiers Markdown sont candidats :

1. Si l'utilisateur fournit une liste de fichiers explicite, utilisez cette liste.
2. Sinon, utilisez les fichiers Markdown modifiés du dépôt sous docs/.
3. Incluez les fichiers .md ajoutés, modifiés et renommés.
4. Excluez les fichiers de changelog de version archivés sous docs/releases/, sauf demande explicite.
5. Excluez les documents internes d'IA, de journal de travail, d'audit ou de planification privée lorsqu'ils sont hors de la documentation publique ou marqués comme internes.
6. Excluez les fichiers dépourvus de métadonnées cms_sync, sauf si le flux de travail est explicitement en mode planification ou adoption.
7. N'effectuez une réanalyse complète de docs/ que lorsque l'utilisateur le demande explicitement.

La détection des fichiers modifiés n'est qu'une étape de sélection des sources. Elle ne doit pas modifier l'état de Git, indexer des fichiers, créer des artefacts de version ni déduire une installation du CMS cible à partir des dépôts distants.

Les fichiers Markdown adhèrent via le front matter :

cms_site, ci-dessus, est un handle de site cible donné en exemple, et non un domaine ou un nom d'installation réels. cms_source_id est l'identité de source stable. Si un fichier est déplacé, l'identité de source peut rester inchangée, de sorte que la page cible puisse toujours être appariée en toute sécurité.

Règles des métadonnées :

• cms_source_id est l'identité de source stable.
• cms_path est le chemin canonique de Page Translation, par exemple /docs/internal-content-api ; ne préfixez pas les nouvelles pages de documentation par /p.
• cms_layout vaut docs par défaut lorsqu'il est absent.
• cms_locale vaut en par défaut lorsqu'il est absent.
• cms_title vaut par défaut le premier H1 ou un titre dérivé du nom du fichier lorsqu'il est absent.
• le hachage de source est un hachage SHA-256 du contenu Markdown source, utilisé pour détecter les modifications.
• l'absence de métadonnées cms_sync signifie que le fichier est ignoré par le mode de mise à jour normal et peut être signalé pour la planification de l'adoption.

L'adoption initiale peut être menée comme une étape d'amorçage des métadonnées purement documentaire, avant toute découverte du CMS en production ou tentative d'apply. Cette étape doit ajouter un front matter générique et sûr aux fichiers Markdown de documentation publique sélectionnés, afin que les plans ultérieurs puissent identifier les ids de source, les chemins, les langues (locales), les layouts et les titres sans deviner. Une passe d'adoption complète de docs/ doit tout de même exclure les changelogs de version archivés sous docs/releases/, sauf si un opérateur de confiance approuve explicitement ces pages d'archive.

Une page du CMS liée à sa source doit conserver les métadonnées de source dans les réglages de la page. Les réglages de page suffisent au flux de travail documenté ; une table de correspondance des sources distincte ne pourra être envisagée plus tard que si le reporting, la correspondance entre langues, l'audit ou des opérations à grande échelle l'exigent.

Structure recommandée des réglages de page :

Le chemin de source est descriptif. L'identité stable est source_id et le détecteur de changement est source_sha256. L'Internal Content API n'accepte cet objet que via le réglage de page autorisé source_sync, le conserve après l'apply et renvoie les mêmes champs sûrs dans les réponses de liste et de détail des pages pour l'appariement. N'y stockez ni jetons, ni valeurs d'environnement, ni chemins absolus locaux, ni chemins serveur, ni autres secrets.

L'ordre d'appariement doit être déterministe :

1. Cherchez une page du CMS dont le source_sync.source_id correspond, ou dotée de métadonnées cms_source_id équivalentes.
2. Si vous la trouvez, comparez source_sha256.
3. S'il n'existe aucune correspondance par id de source, cherchez une page au chemin canonique cms_path.
4. Si le chemin existe sans métadonnées de source correspondantes, signalez un cas d'adoption ou de revue de conflit.
5. Si le chemin appartient à un autre source_id, signalez un conflit et arrêtez-vous pour ce fichier.
6. Si aucune page n'existe à ce chemin, planifiez create_draft_page avec page.path défini sur le chemin canonique cms_path.

N'utilisez pas la comparaison de contenu comme mécanisme d'appariement principal. Appariez d'abord par identité de source stable, puis par chemin uniquement pour l'adoption ou la revue de conflit.

Pour la documentation Markdown modifiée, appliquez ces valeurs par défaut :

• Si le hachage de source est inchangé dans les métadonnées du CMS, ignorez le fichier.
• S'il n'existe aucune page du CMS correspondante, planifiez create_draft_page.
• S'il existe une page en brouillon correspondante, planifiez replace_existing_draft_page pour les slots gérés appartenant à la page.
• S'il n'existe qu'une page publiée correspondante, ne la remplacez pas directement, sauf si le flux de travail dispose d'un chemin documenté sûr de brouillon ou de préproduction et que l'utilisateur approuve explicitement ce chemin.
• Le slot géré par défaut est main.
• Préservez l'en-tête, le pied de page, les slots désactivés et les affectations de Shared Slot.
• Ne remplacez pas un slot servi par un Shared Slot.
• Planifiez la navigation séparément et n'appliquez pas de modifications de navigation par défaut.
• La publication ne fait jamais partie de content apply par défaut.

Le flux de travail doit régénérer les slots gérés appartenant à la page à partir de la source Markdown, plutôt que de tenter de préserver des modifications manuelles du CMS dans ces slots. Les pages de documentation liées à leur source sont des dérivés reproductibles ; le Markdown reste la référence.

Construisez du contenu structuré en n'utilisant que des handles découverts sur l'installation cible. Ne devinez jamais un handle de bloc ni une orthographe voisine.

Règles de correspondance pratiques :

• H1 correspond au titre de la page et/ou à un bloc content_header lorsque ce handle est disponible.
• H2 et H3 correspondent à des blocs header, avec des ancres là où elles sont prises en charge.
• Les paragraphes correspondent à rich-text.
• Un texte court et non formaté peut utiliser plain_text uniquement lorsque cela convient mieux que le texte enrichi.
• Les listes correspondent à un bloc de liste lorsque le contrat de contenu courant en propose un ; sinon, conservez-les dans rich-text.
• Les tableaux correspondent à un bloc table lorsque c'est possible.
• Les blocs de code délimités correspondent à un bloc code.
• Les citations correspondent à des blocs quote ou de type alert/encadré selon le sens et les contrats découverts.
• Les liens Markdown ordinaires restent des liens rich-text.
• Les liens de type CTA ne peuvent devenir des button_link que lorsqu'ils sont délibérément orientés action.
• Le HTML brut est à éviter ; html n'est qu'un recours relu, réservé aux cas où les blocs structurés ne peuvent pas représenter le contenu.
• Les images et les médias ne doivent être ni téléchargés ni importés. Émettez un avertissement, sauf si le flux de travail cible prend explicitement en charge les références à des médias existants.

Préférez une structure de documentation lisible à un unique gros bloc rich-text. Une page de documentation normale utilise généralement content_header ou le contenu de titre dérivé du H1, suivi de titres, de texte enrichi, de listes, de tableaux et de blocs de code à l'intérieur du slot géré main.

Le flux de travail est API-first :

1. Commencez par GET /webadmin/api.
2. Utilisez les liens renvoyés pour OpenAPI, le guide IA, le contrat de contenu, les types de blocs, les pages, la navigation et les Shared Slots.
3. Vérifiez que le jeton dispose des capacités nécessaires au mode demandé.
4. Lisez les pages existantes et leurs métadonnées de source via l'API.
5. Construisez les plans de page en n'utilisant que des handles découverts.
6. Exécutez POST /webadmin/api/content/validate avant l'apply.
7. N'appliquez qu'après une approbation explicite ou lorsque l'instruction de l'utilisateur autorise explicitement un apply sûr en brouillon.
8. Ne publiez jamais sauf si l'utilisateur le demande explicitement et que le jeton dispose de content.publish.
9. N'utilisez jamais l'automatisation du navigateur lorsque l'API est disponible.

Les erreurs de l'API sont un retour sur le flux de travail. Traitez les réponses JSON 401, 403 et 422 comme des signaux d'arrêt ou de révision, suivez les liens de découverte/documentation et rapportez un statut résumé et sûr, sans afficher de secrets.

Lorsque plusieurs documents modifiés sont candidats :

• traitez chaque document source comme une mise à jour de page planifiée indépendante
• validez tous les plans de page candidats avant d'appliquer un lot, sauf si l'opérateur choisit explicitement un apply fichier par fichier
• laissez le conflit d'un fichier n'arrêter que ce fichier, sans masquer les plans réussis des autres
• rapportez séparément les fichiers ignorés, planifiés, validés, appliqués, en échec et en conflit
• n'apportez pas de modifications à la navigation au seul motif que plusieurs documents ont changé
• conservez la planification de la navigation comme un plan explicite distinct

L'apply par lots doit rester conservateur. Si l'utilisateur a demandé un apply sûr en brouillon, n'appliquez que les éléments validés compatibles avec le brouillon et laissez les conflits ou les cas à relire non appliqués.

Arrêtez-vous avant l'apply lorsque :

• le jeton d'API est absent, invalide ou révoqué
• la découverte de l'API échoue
• OpenAPI, le contrat de contenu ou les types de blocs ne peuvent pas être lus
• les handles de bloc requis ne sont pas disponibles
• cms_path entre en conflit avec un autre cms_source_id
• la page cible est publiée et aucun chemin de remplacement sûr en brouillon n'est disponible
• le plan remplacerait un slot servi par un Shared Slot
• la validation échoue
• l'utilisateur n'a pas approuvé l'apply et l'instruction était une simulation ou une planification seule

Arrêtez-vous également avant toute publication, sauf si l'utilisateur la demande explicitement, que le plan a déjà été validé/appliqué en toute sécurité et que le jeton dispose de content.publish.

Pour les lots, regroupez les mêmes champs dans les sections skipped, planned, validated, applied, failed, conflict et needs review.

Planification seule :

Validation seule :

Valider et appliquer des mises à jour sûres en brouillon :

Planification avec réanalyse complète :

Planification de la navigation seule :

Les pages de documentation liées à leur source doivent être marquées dans le CMS comme gérées par la source. Un futur écran d'édition pourra avertir les éditeurs : "Cette page est synchronisée depuis une source Markdown. Modifiez plutôt le fichier source."

Les modifications manuelles effectuées dans le CMS sur les pages de documentation liées à leur source ne sont pas conservées lors de la régénération suivante des slots gérés à partir de la source. Les affectations d'en-tête/pied de page et de Shared Slot sont, elles, préservées, car il ne s'agit pas de contenu Markdown géré appartenant à la page.

La documentation et les rapports d'opérateur ne doivent contenir ni jetons, ni secrets, ni chemins absolus locaux, ni journaux bruts, ni valeurs d'environnement, ni noms réels de sites cibles, ni domaines réels.