🌟 The Starlight Plugin

The Starlight Plugin from the Bag of Tricks adds view transitions to your Starlight site, bringing smooth animations and a touch of magic to every page change. If you only want standard cross-fade view transitions, do not install the plugin but do this.

See what the plugin did↗ to the Starlight Starter!

Installation
Curious About the Details?
How to Expect Content without the Plugin
Simple alternative: Just Whole-Viewport Cross-Fade

Installation

Add view transitions to your existing Starlight site in two simple steps:

1. Install astro-vtbot from npm

1
cd .../my-starlight-project
2
npm install -D astro-vtbot

2. Add the plugin to your astro.config file.

1
import { defineConfig } from 'astro/config';
2
import { viewTransitions } from "astro-vtbot/starlight-view-transitions";
3

4
export default defineConfig({
5
  integrations: [
6
    starlight({
7
      plugins: [viewTransitions()],
8
      ...
9
    ...})]
10
})

Optional Steps

You can customize the plugin with additional behavior. These steps are all optional:

enable the renderBlocking field in the frontmatter.
have an automatic fallback at the end of the markdown content if renderBlocking isn’t specified.
set config strings for the included scripts

Option 1: Enable the `renderBlocking` field for use in the frontmatter

The Starlight Plugin provides an easy way to define expect links using a frontmatter filed called renderBlocking. If you do not use this option, you can alternatively use Starlight’s head fields to define such links.

If you want to use the renderBlocking attribute in the markdown frontmatter to tell the browser to wait for a fragment identifier “below the fold”, you need to extend Starlight’s content config.

1
import { defineCollection, z } from 'astro:content';
2
import { docsLoader } from '@astrojs/starlight/loaders';
3
import { docsSchema } from '@astrojs/starlight/schema';
4

5
export const collections = {
6
  docs: defineCollection({
7
    loader: docsLoader(),
8
    schema: docsSchema(
9
      {extend: z.object({renderBlocking: z.string().optional()})}
10
    )
11
  }),
12
};

After that, you can set the renderBlocking attribute in your frontmatter

1
renderBlocking: my-below-the-fold-heading

and the Starlight plugin will automatically add

1
<link rel="expect" href="#my-below-the-fold-heading" blocking="render" />

to the <head> of your page.

Option 2: Automatically wait for the whole markdown section (if `renderBlocking` isn’t defined)

If this option is enabled, the Starlight Plugin will automatically add the end-of-markdown id…at the end of the markdown. If you do note enable the renderBlocking option above or do not define a renderBlocking id on a page, the plugin will automatically insert a render blocking link for you.

1
<link rel="expect" href="#end-of-markdown" blocking="render" />

So view transitions will not start until the whole content of your page is loaded. This can be convenient for small pages, but might also come with some performance penalties for larger content.

To enable this option, import and include the remarkEndOfMarkdown plugin:

1
import { defineConfig } from 'astro/config';
2
import { viewTransitions, remarkEndOfMarkdown } from "astro-vtbot/starlight-view-transitions";
3

4
export default defineConfig({
5
  markdown: { remarkPlugins: [remarkEndOfMarkdown] }
6
  integrations: [
7
    starlight({
8
      plugins: [viewTransitions()],
9
      ...
10
    ...})],
11
})

Option 3: Set config strings for included scripts

Under the hood, the Starlight Plugin installs some of the @vtbag scripts. Those can be configured by setting fields of the plugin’s options object:

Option	Package	Script	Script Option
allPages	turn-signal	index,debug,direction	data-selector↗
directionTypes	turn-signal	index,debug,directions	data-direction-types↗
directionAttribute	turn-signal	index,debug,directions	data-direction-attribute↗
declarativeNames	utensil-drawer	declarative-names	data-vtbag-decl↗
camShaftNames	cam-shaft	index	data-view-transition-names↗

For example, if you want to assign view transition names to all <h2> headings you would instruct the declarative-names script like so:

1
starlight({
2
  plugins: [viewTransitions({ declarativeNames: "h2 = heading2-" })],
3
  ...
4
...})

Curious About the Details?

Want to see all the magic this plugin brings? Head over to vtbag.dev for the fifth episode of Fun With View Transitions: Adding View Transitions to Your Starlight Site↗.

How to Expect Content without the Plugin

Of course you can alternatively create the head entry independent of vtbot by using Starlight’s frontmatter head field

1
head:
2
  - tag: link
3
    attrs:
4
      rel: "expect"
5
      href: "#my-below-the-fold-heading"
6
      blocking: "render"

or Starlight’s global head option:

1
import viewTransitions from 'astro-vtbot/starlight-view-transitions'
2
export default defineConfig({
3
  integrations: [
4
    starlight({
5
      plugins: [viewTransitions()],
6
      head: [{
7
        tag: "link",
8
        attrs: {
9
          rel: "expect",
10
          href: "#below-the-fold",
11
          blocking: "render"
12
        }
13
      }]
14
      ...
15
    ...})]})

The global head option works particularly well if you define an id for the main content area or an element below the markdown content. To do this, you have to override Starlight components↗ to set the id, for example:

1
---
2
import Default from "@astrojs/starlight/components/MarkdownContent.astro";
3
---
4
<Default><slot /></Default>
5
<div id="vtbag-below-the-fold" />

Simple alternative: Just Whole-Viewport Cross-Fade

If you just want a whole-viewport cross-fade effect on your Starlight site and none of the spiffy thrills of the plugin, you can alternatively add the following CSS to a custom CSS↗ file and be all set.

1
@media (prefers-reduced-motion: no-preference) {
2
  @view-transition {
3
    navigation: auto;
4
  }
5
}