14 - Starlight Branding, Copy Button, and Docs Sync

Documentation technique

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 Article1/2

Installation :

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

Configuration :

2.2. Plugin Copy Article2/2

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 Docs1/3

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/

2.3. Synchronisation des Docs2/3

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 :

2.3. Synchronisation des Docs3/3

# 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

Démarrer le serveur de développement :
Terminal window
```
task dev
```
Naviguer vers une page de documentation (ex: http://localhost:4321/getting-started/01-setup-local)
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é

Éditer les docs dans docs/ ou GettingStarted/
Synchroniser vers Starlight : task sync-docs
Tester localement : task dev
Committer les changements
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