Skip to content
AMN Docs

Plan d'intégration — Starlight Scroll to Top

Plan d'intégration — Starlight Scroll to Top

Plan détaillé pour l'intégration du plugin starlight-scroll-to-top pour la navigation retour en haut de page

Plan d’Intégration — Plugin starlight-scroll-to-top

Document de Référence : GettingStarted/40-plan-starlight-scroll-to-top-integration.md
Source Clonée : ~/astro/starlight-scroll-to-top (packages/starlight-scroll-to-top@2.0.0)
Version cible : starlight-scroll-to-top@2.0.0
Compatibilité : @astrojs/starlight@0.42.4 (peerDependency : >=0.41.0)
Méthodologie : Cycle DOC → SPEC → CODE → TEST → INTÉG

1. Synthèse de l’Investigation

L’analyse du code source cloné dans ~/astro/starlight-scroll-to-top démontre :

1.1 Architecture du Plugin1/2

  • Mécanisme d’injection : Le plugin n’écrase aucun composant Starlight. Il s’appuie sur le hook astro:config:setup d’Astro avec injectScript('page', ...) pour injecter un script client optimisé par Vite.
  • Cycle de vie SPA / View Transitions : Le script écoute DOMContentLoaded, astro:page-load et astro:before-preparation pour nettoyer et réinitialiser les écouteurs de défilement proprement lors des navigations sans rechargement.

1.1 Architecture du Plugin2/2

  • Indicateur de progression (Progress Ring) : Support d’un anneau circulaire SVG autour du bouton (showProgressRing: true) qui se remplit au fur et à mesure du scroll, stylable via les variables CSS Starlight (ex: var(--sl-color-accent)).
  • Internationalisation (I18N) : Support natif multilingue pour les infobulles (détecte la langue courante via <html lang="..."> avec repli hiérarchique : fr ➔ en ➔ défaut).
  • Dépendances : 0 dépendance runtime tierce (deps: none).

1.2 Matrice de Compatibilité avec l’existant

Plugin existant Composants touchés Conflit potentiel avec starlight-scroll-to-top
starlight-sidebar-topics Surcharge Sidebar ❌ Aucun conflit (scroll-to-top utilise injectScript)
starlight-view-modes Surcharge SocialIcons, PageTitle, etc. ❌ Aucun conflit
starlight-giscus Surcharge Pagination ❌ Aucun conflit
starlight-page-actions Actions de page (header/title) ❌ Aucun conflit
starlight-docsearch Barre de recherche ❌ Aucun conflit

2. Cycle DOC → SPEC → CODE → TEST → INTÉG

Phase 1 : DOC (Documentation préliminaire)

  • Vérifier la compatibilité des options Starlight CSS (--sl-color-accent, etc.).
  • Valider le comportement sur mobile, desktop et avec zoom élevé (>300% le script masque automatiquement le bouton pour préserver l’ergonomie).

Phase 2 : SPEC (Spécification de l’intégration)1/2

  • Ordre des plugins dans apps/web/astro.config.mjs :
    1. starlightViewModes(...)
    2. starlightSidebarTopics(...)
    3. starlightGiscus(...)
    4. starlightScrollToTop(...)
    5. starlightPageActions(...)
    6. starlightDocSearch(...)

Phase 2 : SPEC (Spécification de l’intégration)2/2

  • Options recommandées :
    • position: 'right'
    • threshold: 300 (s’affiche après 300px de scroll)
    • smoothScroll: true
    • showTooltip: true
    • tooltipText: { 'fr': 'Retour en haut', 'en': 'Scroll to top' }
    • showProgressRing: true
    • progressRingColor: 'var(--sl-color-accent)'
    • borderRadius: '50' (bouton rond moderne)
    • showOnHomepage: false (masqué sur la landing page)

Phase 3 : CODE (Implémentation)

  1. Installation du paquet :
    Terminal window
    pnpm --filter amn-astro add starlight-scroll-to-top@2.0.0
  2. Mise à jour de la configuration Starlight :
    • Fichier : apps/web/astro.config.mjs
    • Import de starlightScrollToTop from 'starlight-scroll-to-top'
    • Déclaration dans plugins: [...] avec les options spécifiées.

Phase 4 : TEST (Validation locale)

  1. Validation statique et typage :
    Terminal window
    pnpm --filter amn-astro run typecheck # (astro check)
  2. Build de production Cloudflare :
    Terminal window
    pnpm --filter amn-astro run build
  3. Validation visuelle & fonctionnelle :
    • Accéder à une page longue (ex: http://localhost:8787/gettingstarted/01-setup-local/).
    • Scroller de plus de 300px : le bouton apparaît avec une animation fluide.
    • Vérifier le remplissage de l’anneau de progression SVG au scroll.
    • Survoler le bouton : tooltip affichant « Retour en haut ».
    • Cliquer sur le bouton : remontée fluide (smooth scroll) vers le haut de la page.
    • Naviguer vers une autre page (Astro View Transitions) : vérifier que le composant est réinitialisé sans duplication de bouton dans le DOM.

Phase 5 : INTÉG (Capitalisation & Documentation)

  • Rédiger la documentation d’intégration dédiée :
    docs/L2_Presentation/astro/starlight/Starlight-Plugin-Scroll-To-Top.md
  • Mettre à jour test-docs/starlight-site-update.md (marquer le point 6 comme complété).

3. Matrice de Risques & Atténuations

Risque Impact Solution / Atténuation
Chevauchement avec Giscus ou ToC Bouton recouvrant du texte Positionnement absolu/fixé (bottom: 2rem, right: 2rem) avec marge CSS automatique gérée par le plugin.
Navigation SPA (View Transitions) Boutons dupliqués dans le DOM Le plugin implémente nativement astro:before-preparation et supprime l’ancien élément avant de réinjecter.
Incohérence graphique en mode sombre/clair Anneau mal contrasté Utilisation de var(--sl-color-accent) assurant un contraste adapté au thème actif Starlight.

4. Prochaine étape

Attendre la confirmation pour lancer l’installation du paquet (pnpm add starlight-scroll-to-top) et réaliser la configuration dans astro.config.mjs.

Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare