14 - Starlight Branding, Copy Button, and Docs Sync

Audience : Développeurs
Durée estimée : 15-20 minutes
Prérequis : 13 - Phase0 Starlight Docs Auth Test terminé

---

1. Vue d’ensemble

Cette session a ajouté les fonctionnalités de branding Starlight et de synchronisation des docs :

• Changement du titre du site de “Documentation” à “amn Docs”
• Ajout du plugin starlight-page-actions pour le bouton “Copy article”
• Configuration des fonctionnalités natives Starlight (logo, favicon, social, editLink, lastUpdated, pagination, tableOfContents)
• Création d’un workflow de synchronisation bidirectionnelle des docs
• Correction des problèmes de duplication des titres

---

2. Modifications effectuées

2.1. Branding Starlight

Fichier modifié : apps/web/astro.config.mjs

starlight({
  title: 'amn Docs',  // Changé de 'Documentation'
  logo: {
    src: './src/assets/logo.svg',
  },
  favicon: '/favicon.svg',
  social: [
    { icon: 'github', href: 'https://github.com/audyssee/PP', label: 'GitHub' },
  ],
  editLink: {
    baseUrl: 'https://github.com/audyssee/PP/edit/main/apps/web/src/content/docs/',
  },
  lastUpdated: true,
  pagination: true,
  tableOfContents: {
    minHeadingLevel: 2,
    maxHeadingLevel: 3,
  },
})

2.2. Plugin Copy Article

Installation :

pnpm --filter ./apps/web add starlight-page-actions

Configuration :

import starlightPageActions from 'starlight-page-actions';

starlight({
  plugins: [
    starlightPageActions({
      openActions: {
        enabled: false,  // Désactiver ouverture dans les IA
      },
      shareActions: {
        enabled: false,  // Désactiver partage social
      },
    }),
  ],
})

2.3. Synchronisation des Docs

Script créé : sync-docs.sh

Ce script synchronise de manière bidirectionnelle :

• docs/ ↔ apps/web/src/content/docs/docs/
• GettingStarted/ ↔ apps/web/src/content/docs/getting-started/

Filtres d’exclusion :

• docs/PM/ et docs/SOP/ sont exclus
• Dans GettingStarted/, seuls les fichiers numérotés 01-99.md et index.md sont synchronisés
• Les fichiers temporaires (.DONE.md, .TODO.md, test_*.md, etc.) sont exclus

Commandes disponibles :

# Synchroniser source → Starlight
./sync-docs.sh source-to-starlight
# ou
task sync-docs

# Synchroniser Starlight → source
./sync-docs.sh starlight-to-source
# ou
task sync-docs:reverse

# Synchronisation bidirectionnelle
./sync-docs.sh bidirectional
# ou
task sync-docs:bidirectional

2.4. Workflow GitHub Actions

Fichier modifié : .github/workflows/deploy-dev.yml

Ajout d’un step de synchronisation avant le build :

- name: Sync docs to Starlight
  run: ./sync-docs.sh source-to-starlight
- name: Commit synced docs
  run: |
    git config --local user.email "github-actions[bot]@users.noreply.github.com"
    git config --local user.name "github-actions[bot]"
    git add apps/web/src/content/docs/
    git diff --staged --quiet || git commit -m "chore: sync docs from source to starlight [skip ci]"

2.5. Correction des titres dupliqués

Les fichiers markdown avaient à la fois un titre dans le frontmatter ET un titre H1 dans le contenu, ce qui créait une duplication.

Solution : Suppression de tous les titres H1 des fichiers markdown (137 fichiers modifiés automatiquement)

2.6. Assets créés

• apps/web/src/assets/logo.svg - Logo placeholder avec “AMN”
• apps/web/src/assets/favicon.svg - Favicon placeholder avec “A”
• apps/web/public/favicon.svg - Copie pour le favicon web

---

3. Test des modifications

3.1. Test local du plugin Copy Article

1. Démarrer le serveur de développement :

   task dev

2. Naviguer vers une page de documentation (ex: http://localhost:4321/getting-started/01-setup-local)

3. Vérifier :

   • ✅ Le bouton “Copy Markdown” est visible
   • ✅ Le bouton copie le contenu complet de l’article
   • ✅ Le bouton affiche “Copied!” après la copie

3.2. Test de la synchronisation des docs

# Test de synchronisation source → Starlight
task sync-docs

# Vérifier que les fichiers sont synchronisés
ls apps/web/src/content/docs/docs/
ls apps/web/src/content/docs/getting-started/

# Vérifier que les fichiers temporaires sont exclus
# (doit ne pas contenir test_*.md, *.DONE.md, etc.)

3.3. Test du workflow GitHub Actions

Le workflow sera testé automatiquement lors du prochain push sur main.

---

4. Structure de travail des docs

4.1. Source de vérité

• docs/ : Documentation technique (L1, L2, L3)
• GettingStarted/ : Guides de démarrage (uniquement fichiers numérotés 01-99.md)

4.2. Destination Starlight

• apps/web/src/content/docs/docs/ : Docs techniques pour Starlight
• apps/web/src/content/docs/getting-started/ : Guides de démarrage pour Starlight

4.3. Workflow recommandé

1. Éditer les docs dans docs/ ou GettingStarted/
2. Synchroniser vers Starlight : task sync-docs
3. Tester localement : task dev
4. Committer les changements
5. Push vers main (déploiement automatique avec sync)

---

5. Dépannage

5.1. Problème : Le bouton Copy ne s’affiche pas

Cause probable : Le plugin n’est pas installé ou mal configuré

Solution :

pnpm --filter ./apps/web add starlight-page-actions

Vérifier la configuration dans apps/web/astro.config.mjs

5.2. Problème : Les titres sont toujours dupliqués

Cause probable : Certains fichiers ont encore des H1

Solution :

# Vérifier manuellement les fichiers
grep -r "^# " apps/web/src/content/docs/

Supprimer manuellement les H1 restants

5.3. Problème : La synchronisation ne fonctionne pas

Cause probable : Permissions ou chemins incorrects

Solution :

# Vérifier que le script est exécutable
chmod +x sync-docs.sh

# Vérifier les chemins
ls -la docs/
ls -la GettingStarted/
ls -la apps/web/src/content/docs/

---

6. Prochaines étapes

• Tester le bouton Copy Article avec le serveur de développement
• Tester la synchronisation bidirectionnelle
• Vérifier que le workflow GitHub Actions passe correctement
• Mettre à jour les assets logo et favicon avec les vrais fichiers
• Tester toutes les fonctionnalités Starlight configurées