Skip to content
AMN Docs

Starlight Scroll to Top

Starlight Scroll to Top

Intégration du plugin starlight-scroll-to-top pour la navigation rapide et retour en haut de page

Version : starlight-scroll-to-top@2.0.0
Starlight : @astrojs/starlight@0.42.4
Intégré le : 2026-10-13
Doc officielle : https://frostybee.github.io/starlight-scroll-to-top/
Repo cloné : ~/astro/starlight-scroll-to-top

1. Objectif

Fournir aux utilisateurs un bouton flottant discret et fluide permettant de remonter instantanément en haut des pages de documentation techniques denses.

Le bouton intègre un anneau circulaire de progression (Progress Ring) qui indique visuellement l’état d’avancement de la lecture dans le document.

2. Installation

Dans le workspace apps/web :

Terminal window
pnpm add starlight-scroll-to-top

3. Configuration dans astro.config.mjs

Le plugin est ajouté dans le tableau plugins de la configuration Starlight :

apps/web/astro.config.mjs
import starlightScrollToTop from 'starlight-scroll-to-top';


export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightViewModes({...}),
        starlightSidebarTopics([...], {...}),
        starlightGiscus({...}),
        starlightScrollToTop({
          position: 'right',
          tooltipText: {
            'fr': 'Retour en haut',
            'en': 'Scroll to top',
          },
          showTooltip: true,
          smoothScroll: true,
          threshold: 300,
          showProgressRing: true,
          progressRingColor: 'var(--sl-color-accent)',
          borderRadius: '50',
          showOnHomepage: false,
        }),
        starlightPageActions(),
        starlightDocSearch({...}),
      ],
    }),
  ],
});

Options retenues1/2

Option Valeur Description
position 'right' Positionnement du bouton en bas à droite de l’écran
tooltipText { 'fr': 'Retour en haut', 'en': 'Scroll to top' } Texte de l’infobulle adapté selon la langue active du document
showTooltip true Affiche l’infobulle au survol de la souris
smoothScroll true Défilement animé fluide vers le haut
threshold 300 Distance de défilement (en pixels) avant l’apparition du bouton

Options retenues2/2

Option Valeur Description
showProgressRing true Active l’anneau SVG de progression de lecture
progressRingColor 'var(--sl-color-accent)' Couleur de l’anneau synchronisée sur la couleur d’accent du thème Starlight
borderRadius '50' Bouton circulaire moderne (50%)
showOnHomepage false Masqué automatiquement sur la page d’accueil

4. Architecture & Mécanisme d’Injection

4.1 Zéro Conflit de Composants Starlight

Contrairement aux plugins qui surchargent des composants (Sidebar, Pagination, etc.), starlight-scroll-to-top :

  • N’écrase aucun composant Starlight.
  • Injecte directement un script client optimisé par Vite via le hook injectScript('page', ...) de l’intégration Astro.

4.2 Support du Cycle de Vie SPA / View Transitions

Le script client gère les événements suivants :

  • DOMContentLoaded et astro:page-load : initialisation après le chargement du DOM.
  • astro:before-preparation : nettoyage systématique des anciens nœuds DOM et écouteurs d’événements pour éviter les doublons lors des navigations sans rechargement.
  • resize : masquage automatique si le zoom navigateur dépasse 300% afin de préserver l’ergonomie mobile.

5. Tests de Validation1/2

  • Compilation TypeScript (pnpm run typecheck / astro check) : 0 erreurs, 0 warnings
  • Build de production Cloudflare (pnpm run build) : Succès (code 0)

5. Tests de Validation2/2

  • Dans le navigateur (http://localhost:8787/gettingstarted/01-setup-local/) :
    • Défiler de 300px vers le bas : le bouton apparaît en bas à droite.
    • L’anneau de progression SVG se remplit proportionnellement au défilement.
    • Le survol affiche l’infobulle « Retour en haut ».
    • Le clic fait remonter la page de façon fluide.
    • Les changements de page (View Transitions) nettoient et réinitialisent le bouton proprement.
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare