Starlight View Modes

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

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)