Skip to content
AMN Docs

Starlight View Modes

Starlight View Modes

Starlight View Modes — Zen Mode et Présentation Mode

Version : starlight-view-modes@0.15.3 Starlight : @astrojs/starlight@0.42.4 Intégré le : 2026-10-13 Doc officielle : https://starlight-view-modes.netlify.app

1. Objectif

Permettre deux modes de lecture alternatifs pour la documentation :

  • Zen Mode — lecture sans distractions (header et sidebar masqués)
  • Présentation Mode — transformation des pages en slides reveal.js

Chaque mode est accessible via des boutons dans le header ou des raccourcis clavier, sans outil externe.

2. Installation

Terminal window
pnpm add starlight-view-modes

3. Configuration dans astro.config.mjs

Le plugin s’ajoute dans le tableau plugins de starlight({}), avant starlightSidebarTopics.

import starlightViewModes from 'starlight-view-modes';


starlight({
  plugins: [
    starlightViewModes({
      zenModeSettings: {
        displayOptions: {
          showHeader: false,           // cache le header en Zen Mode
          showSidebar: false,          // cache le sidebar
          showTableOfContents: true,   // garde la table des matières
          showFooter: true,            // garde le footer
        },
        keyboardShortcut: 'Ctrl+Shift+Z',
      },
      presentationModeSettings: {
        enabled: true,
        transition: 'slide',           // none|fade|slide|convex|concave|zoom
        animation: 'fade-in',          // style d'animation des fragments
        splitHeadingLevel: 3,          // H3 = nouvelle slide
        keyboardShortcut: 'Ctrl+Shift+P',
      },
    }),
    // starlightSidebarTopics(...) vient après
  ],
})

4. Routes injectées

Le plugin injecte deux patterns de routes statiques (prerender) :

Mode Pattern de route Exemple
Zen Mode /zen-mode/[...path] /zen-mode/docs/
Présentation /presentation-mode/[...path] /presentation-mode/docs/

Important : Ces routes doivent être ajoutées à exclude de starlightSidebarTopics pour éviter une erreur au build. Voir la doc du plugin sidebar-topics.

5. Composants overridés automatiquement

Le plugin remplace automatiquement 4 composants Starlight :

Composant Raison
SocialIcons Ajoute les boutons de switch Zen/Présentation dans le header
PageTitle Ajoute le switcher sous le titre de la page
Search Adapte la recherche selon le mode actif
TableOfContents Ajoute la section “View Modes” dans le ToC

Compatibilité avec d’autres overrides

Si le projet override déjà SocialIcons (ex: bouton auth), il y a un conflit. Dans ce projet, le bouton auth a été déplacé dans le sidebar pour libérer SocialIcons au profit du plugin.

Voir SidebarWithAuth.astro pour l’implémentation.

6. Comportement par mode

Zen Mode (/zen-mode/[...path])

  • Header masqué
  • Sidebar masqué
  • Table des matières visible
  • Footer visible
  • URL miroir de la page normale (ex: /docs/foo/ → /zen-mode/docs/foo/)
  • Raccourci : Ctrl+Shift+Z

Présentation Mode (/presentation-mode/[...path])

  • Powered by reveal.js
  • Chaque H3 (splitHeadingLevel: 3) crée une nouvelle slide
  • Transition entre slides : slide
  • Animation des fragments : fade-in
  • URL miroir (ex: /docs/foo/ → /presentation-mode/docs/foo/)
  • Raccourci : Ctrl+Shift+P

7. Options de configuration complètes

zenModeSettings

Option Type Défaut Description
enabled boolean true Active/désactive le Zen Mode
displayOptions.showHeader boolean false Affiche le header en zen mode
displayOptions.showSidebar boolean false Affiche le sidebar
displayOptions.showTableOfContents boolean true Affiche le ToC
displayOptions.showFooter boolean true Affiche le footer
keyboardShortcut string|string[] [] Raccourci(s) clavier
exclude string[] [] Pages exclues du Zen Mode

presentationModeSettings

Option Type Défaut Description
enabled boolean true Active/désactive le mode
transition string 'slide' none|fade|slide|convex|concave|zoom
animation string|false false Style des fragments reveal.js
splitHeadingLevel number 3 Niveau de titre = nouvelle slide (2–6)
slideNumber boolean true Affiche le numéro de slide
keyboardShortcut string|string[] [] Raccourci(s) clavier
exclude string[] [] Pages exclues du mode

8. Ordre des plugins

starlightViewModes doit être déclaré avant starlightSidebarTopics :

plugins: [
  starlightViewModes({...}),   // 1er
  starlightSidebarTopics([...]), // 2ème
]

Raison : starlightSidebarTopics override Sidebar et doit pouvoir chaîner sur la configuration déjà mise en place par starlightViewModes.

9. Tests de validation

  • Boutons Zen Mode et Présentation Mode visibles dans le header
  • Ctrl+Shift+Z bascule sur /zen-mode/[page-courante]
  • Ctrl+Shift+P bascule sur /presentation-mode/[page-courante]
  • En Zen Mode : header et sidebar masqués, ToC et footer visibles
  • En Présentation Mode : slides générées, navigation par flèches
  • Les routes /zen-mode/** ne provoquent pas d’erreur topic not found
  • La section “View Modes” apparaît dans la table des matières (ToC)
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare