Configuration

The Starlight View Modes plugin can be configured inside the astro.config.mjs configuration file of your project:

import starlight from "@astrojs/starlight";
import { defineConfig } from "astro/config";
import starlightViewModes from "starlight-view-modes";

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightViewModes({
          // Configuration options go here.
        }),
      ],
      title: "My Docs",
    }),
  ],
});

Configuration options

The Starlight View Modes plugin accepts the following configuration options:

`zenModeSettings`

Type: object
Default: {}

Here you can find all options regarding Zen Mode.

`enabled`

Type: boolean
Default: true

Whether the Zen Mode Feature overall should be enabled or disabled. Disabling this option is useful if a Zen Mode doesn’t make much sense on your website.

`displayOptions`

Type:

{
  showHeader: boolean,
  showSidebar: boolean,
  showTableOfContents: boolean,
  showFooter: boolean
}

Default:

{
  showHeader: false,
  showSidebar: false,
  showTableOfContents: true,
  showFooter: true
}

The page elements displayed in Zen Mode, also described in Hidden elements.

`showHeader`

Type: boolean
Default: false

Whether the header should be displayed when Zen mode is activated.

We recommend enabling this option if you want to give your users the opportunity to search whilst in Zen mode.

`showSidebar`

Type: boolean
Default: false

Whether the sidebar should be displayed when Zen mode is activated.

We don’t recommend enabling this option, but if you want, feel free – xD.

`showTableOfContents`

Type: boolean
Default: true

Whether the table of contents should be displayed when Zen mode is activated.

We recommend enabling this option if the user should be able to navigate around on the current page.

We recommend disabling this option if you either want your users to have the full Zen mode experience, or if there are many anchor links on the page so that navigation isn’t limited to the footer links.

`showFooter`

Type: boolean
Default: true

Whether the footer should be displayed when Zen mode is activated. Disabling this option can mean that the user always has to leave Zen mode if they want to go to the next or previous page because there are links to these pages in the footer.

`exclude`

Type: string[]
Default: []

A list of pages or glob patterns that cannot be switched to Zen mode.

If your site is multilingual, your glob patterns do not need to start with the locale prefix.
E.g. ["resources/**/*"] instead of ["en/resources/**/*"] will also work for all locales. A page cannot be excluded in only one language.

`keyboardShortcut`

Type: string | string[]

A list of keyboard shortcuts that will enable the user to enter and exit the Zen Mode. Keyboard shortcuts are disabled by default.

A basic shortcut consists of one or more modifier keys followed by a regular key, all connected with + signs. The Starlight View Modes plugin accepts the following modifier keys: Ctrl, Shift, Alt.

On macOS, Ctrl matches both the Control and the Command keys. As an example, this website uses the following keyboard shortcut configuration, so you can press Ctrl+Shift+Z (Cmd+Shift+Z on macOS) to toggle Zen mode:

starlightViewModes({
  zenModeSettings: {
    keyboardShortcut: ["Ctrl+Shift+Z"],
  },
}),

`presentationModeSettings`

Type: object
Default: {}

Here you can find all options regarding Presentation Mode.

`enabled`

Type: boolean
Default: true

Whether the Presentation Mode feature overall should be enabled or disabled.

`exclude`

Type: string[]
Default: []

A list of pages or glob patterns that cannot be presented.

`keyboardShortcut`

Type: string | string[]

A list of keyboard shortcuts that will enable the user to start and stop presenting the current page. Keyboard shortcuts are disabled by default.

This website uses the following configuration, so you can press Ctrl+Shift+Y (Cmd+Shift+Y on macOS) to present the current page:

starlightViewModes({
  presentationModeSettings: {
    keyboardShortcut: ["Ctrl+Shift+Y"],
  },
}),

`presentSidebarGroups`

Type: boolean
Default: false

Whether the pages of a top-level sidebar group are presented as a single presentation. When enabled, slides are numbered across all pages of the group, and going past the last or first slide of a page continues with the next or previous page of the group.

`splitHeadingLevel`

Type: 2 | 3 | 4 | 5 | 6
Default: 3

The deepest heading level starting a new slide, as described in How pages become slides. The content of deeper headings stays on the slide of their section when it fits, and otherwise continues on slides placed vertically below the section.

For example, set this option to 2 to also keep the content of h3 headings on the slide of their parent section when possible, or to 4 to start a new slide for each h4 heading.

`transition`

The transition used when moving between slides.

`animation`

The reveal.js fragment style used to reveal list items one by one. When false, list items are displayed right away unless they follow a pause, which fades in the content following it in the next step.

`slideNumber`

Type: boolean
Default: true

Whether the current slide number and the total number of slides should be displayed during a presentation.