Mirror of
feat: new blog replacing starlight-toc-overview-customizer plugin (#156)
authored by
Felix Schneider
and committed by
GitHub
7c739621
8b37f12f
+160
public/blog/starlight-customize-toc-overview-title.jpg
public/blog/starlight-customize-toc-overview-title.jpg
This is a binary file and will not be displayed.
+151
src/content/docs/blog/starlight-customize-toc-overview-title.mdx
+151
src/content/docs/blog/starlight-customize-toc-overview-title.mdx
···
1
+
---
2
+
title: Customize the "Overview" title of your Starlight Table of Contents
3
+
description: Learn how you can customize the first heading in the right sidebar of every Starlight page globally and individually.
4
+
date: 2025-11-22
5
+
tags:
6
+
- Starlight
7
+
- Education
8
+
authors:
9
+
- trueberryless
10
+
cover:
11
+
alt: A wooden desk featuring a small green plant positioned on its surface.
12
+
image: ../../../../public/blog/starlight-customize-toc-overview-title.jpg
13
+
---
14
+
15
+
import { Steps } from '@astrojs/starlight/components';
16
+
17
+
This guide shows how you can customize the first heading in the right sidebar (table of contents) of every [Starlight](https://starlight.astro.build) page globally and individually.
18
+
19
+
{/* excerpt */}
20
+
21
+
Each Starlight page contains a table of contents on the right side (except if [disabled](https://starlight.astro.build/reference/frontmatter/#tableofcontents)). To be able to link to the top of the page, the first entry of this sidebar has the title "Overview" (as you can also see on this page's sidebar), which can be customized [globally](#global-definition) and even on a [per-page basis](#frontmatter-override).
22
+
23
+
## Global definition
24
+
25
+
If you want to set the title of the first table of contents entry once for all pages, you can follow these steps to achieve this for monolingual and multilingual sites:
26
+
27
+
<Steps>
28
+
29
+
1. Create [route middleware](https://starlight.astro.build/guides/route-data/#how-to-customize-route-data) to customize the data shown by Starlight.
30
+
31
+
2. Use this example code to configure the "Overview" title:
32
+
33
+
```ts ""Back to top""
34
+
// src/routeData.ts
35
+
import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
36
+
37
+
export const onRequest = defineRouteMiddleware((context) => {
38
+
const { starlightRoute } = context.locals;
39
+
40
+
const overviewItem = starlightRoute.toc?.items[0];
41
+
if (overviewItem) overviewItem.text = "Back to top";
42
+
});
43
+
```
44
+
45
+
3. If your site is [multilingual](https://starlight.astro.build/guides/i18n/), you can also assign different titles depending on the locale:
46
+
47
+
```ts ins="translations[locale ?? defaultLang]" ins={3-13,17}
48
+
// src/routeData.ts
49
+
import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
50
+
import starlightConfig from "virtual:starlight/user-config";
51
+
52
+
const defaultLang =
53
+
starlightConfig.defaultLocale.lang ??
54
+
starlightConfig.defaultLocale.locale ??
55
+
"en";
56
+
57
+
const translations: Record<string, string> = {
58
+
en: "Back to top",
59
+
de: "Zurück nach oben",
60
+
};
61
+
62
+
export const onRequest = defineRouteMiddleware((context) => {
63
+
const { starlightRoute } = context.locals;
64
+
const { locale } = starlightRoute;
65
+
66
+
const overviewItem = starlightRoute.toc?.items[0];
67
+
if (overviewItem) overviewItem.text = translations[locale ?? defaultLang];
68
+
});
69
+
```
70
+
71
+
72
+
</Steps>
73
+
74
+
## Frontmatter override
75
+
76
+
In order to set the first table of contents heading to something different on individual pages, follow the steps below:
77
+
78
+
<Steps>
79
+
80
+
1. [Extend your frontmatter schema](https://starlight.astro.build/reference/frontmatter/#customize-frontmatter-schema) in `src/content.config.ts`:
81
+
82
+
```ts del={8} ins={5,9-16}
83
+
// src/content.config.ts
84
+
import { defineCollection } from 'astro:content';
85
+
import { docsLoader } from '@astrojs/starlight/loaders';
86
+
import { docsSchema } from '@astrojs/starlight/schema';
87
+
import { z } from "astro/zod";
88
+
89
+
export const collections = {
90
+
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
91
+
docs: defineCollection({
92
+
loader: docsLoader(),
93
+
schema: docsSchema({
94
+
extend: z.object({
95
+
overviewTitle: z.string().optional(),
96
+
}),
97
+
}),
98
+
}),
99
+
};
100
+
```
101
+
102
+
2. This allows you to use the `overviewTitle` in your middleware like that:
103
+
104
+
```ts ins={6} ins=/(?<=\= )individualOverviewTitle/
105
+
// src/routeData.ts
106
+
import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
107
+
108
+
export const onRequest = defineRouteMiddleware((context) => {
109
+
const { starlightRoute } = context.locals;
110
+
const individualOverviewTitle = starlightRoute.entry.data.overviewTitle;
111
+
112
+
const overviewItem = starlightRoute.toc?.items[0];
113
+
if (overviewItem)
114
+
overviewItem.text = individualOverviewTitle ?? "Back to top";
115
+
});
116
+
```
117
+
118
+
</Steps>
119
+
120
+
For the sake of completeness, here is a multilingual middleware that supports overriding on individual pages:
121
+
122
+
```ts
123
+
// src/routeData.ts
124
+
import { defineRouteMiddleware } from "@astrojs/starlight/route-data";
125
+
import starlightConfig from "virtual:starlight/user-config";
126
+
127
+
const defaultLang =
128
+
starlightConfig.defaultLocale.lang ??
129
+
starlightConfig.defaultLocale.locale ??
130
+
"en";
131
+
132
+
const translations: Record<string, string> = {
133
+
en: "Back to top",
134
+
de: "Zurück nach oben",
135
+
};
136
+
137
+
export const onRequest = defineRouteMiddleware((context) => {
138
+
const { starlightRoute } = context.locals;
139
+
const { locale } = starlightRoute;
140
+
const individualOverviewTitle = starlightRoute.entry.data.overviewTitle;
141
+
142
+
const overviewItem = starlightRoute.toc?.items[0];
143
+
if (overviewItem)
144
+
overviewItem.text =
145
+
individualOverviewTitle ?? translations[locale ?? defaultLang];
146
+
});
147
+
```
148
+
149
+
## Source code
150
+
151
+
You can also find the complete source code for all four variants on [GitHub](https://github.com/trueberryless/starlight-customize-toc-overview-title) or open the project directly in [StackBlitz](https://stackblitz.com/github/trueberryless/starlight-customize-toc-overview-title).
+9
src/content/docs/credits.mdx
+9
src/content/docs/credits.mdx
···
280
280
usedOnUrl="/blog/tags/mindspace"
281
281
/>
282
282
<ImageCredit
283
+
image="/public/blog/starlight-customize-toc-overview-title.jpg"
284
+
title="Brown Pine Cone on Table"
285
+
author="Mahbod Akhzami"
286
+
authorUrl="https://unsplash.com/@mahbodakhzami"
287
+
sourceUrl="https://unsplash.com/photos/brown-pine-cone-on-table-jc9dkaaEYr4"
288
+
usedOn='Customize the "Overview" title of your Starlight Table of Contents'
289
+
usedOnUrl="/blog/starlight-customize-toc-overview-title"
290
+
/>
291
+
<ImageCredit
283
292
image="/public/blog/terraform-variables-resolution.jpg"
284
293
title="Brown Wooden Building under White Clouds During Daytime"
285
294
author="@invadingkingdom"