Mirror of
feat: new blog, additional content in Starlight table of contents (#158)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
authored by
Felix Schneider
coderabbitai[bot]
and committed by
GitHub
b98508da
5bc85672
+241
public/blog/starlight-customize-toc-additional-content.jpg
public/blog/starlight-customize-toc-additional-content.jpg
This is a binary file and will not be displayed.
+232
src/content/docs/blog/starlight-customize-toc-additional-content.mdx
+232
src/content/docs/blog/starlight-customize-toc-additional-content.mdx
···
1
+
---
2
+
title: Add Additional Content to Starlight's Table of Contents
3
+
description: Learn how to append additional content like credits, ads or additional information below to list of headings in your right Starlight sidebar.
4
+
date: 2025-11-23
5
+
tags:
6
+
- Starlight
7
+
- Education
8
+
authors:
9
+
- trueberryless
10
+
cover:
11
+
alt: A wooden table featuring a decorative flower vase at its center, adding a touch of elegance to the setting.
12
+
image: ../../../../public/blog/starlight-customize-toc-additional-content.jpg
13
+
---
14
+
15
+
import { Steps } from '@astrojs/starlight/components';
16
+
17
+
This guide shows how you can append additional content like credits, ads or additional information below to list of headings in your right [Starlight](https://starlight.astro.build) sidebar.
18
+
19
+
{/* excerpt */}
20
+
21
+
## Append content
22
+
23
+
Starlight's table of contents can be modified by [overriding](https://starlight.astro.build/guides/overriding-components/) the [`TableOfContents.astro` component](https://starlight.astro.build/reference/overrides/#tableofcontents). Follow these steps to append a small Astro component after the existing table of contents:
24
+
25
+
<Steps>
26
+
27
+
1. Create a small `Card.astro` component that will be displayed after the table of contents. If you want to follow common conventions, it is recommended to create a new `src/components/` folder where you can place all your components:
28
+
29
+
```astro collapse={11-36} "not-content"
30
+
---
31
+
// src/components/Card.astro
32
+
33
+
---
34
+
35
+
<aside class="not-content starlight-table-of-contents-aside">
36
+
<h2>Some card!</h2>
37
+
<p>With some text 🙌</p>
38
+
</aside>
39
+
40
+
<style>
41
+
.starlight-table-of-contents-aside {
42
+
position: relative;
43
+
background-color: var(--sl-color-gray-6);
44
+
padding: 1rem;
45
+
border-radius: 0.5rem;
46
+
border: 1px solid var(--sl-color-text-accent);
47
+
box-shadow: var(--sl-shadow-md);
48
+
overflow-y: hidden;
49
+
}
50
+
.starlight-table-of-contents-aside h2 {
51
+
color: var(--sl-color-white);
52
+
font-size: var(--sl-text-h5);
53
+
font-weight: 600;
54
+
text-decoration: none !important;
55
+
line-height: var(--sl-line-height-headings);
56
+
margin-bottom: 0.5rem;
57
+
}
58
+
.starlight-table-of-contents-aside p {
59
+
font-size: var(--sl-text-xs);
60
+
line-height: normal;
61
+
text-decoration: none !important;
62
+
color: var(--sl-color-gray-3);
63
+
overflow-wrap: anywhere;
64
+
}
65
+
</style>
66
+
```
67
+
68
+
Note the usage of the `"not-content"` class feature [provided by Starlight](https://starlight.astro.build/components/using-components/#compatibility-with-starlights-styles) to make sure that Starlight's styles for elements do not apply here as it is a custom component.
69
+
70
+
2. <span id="step-2" />
71
+
72
+
Create the `TableOfContents.astro` component, which will be used as the replacement of Starlight's default table of contents component:
73
+
74
+
```astro "<Default><slot /></Default>" "<Card />"
75
+
---
76
+
// src/components/TableOfContents.astro
77
+
import Default from "@astrojs/starlight/components/TableOfContents.astro";
78
+
import Card from "./Card.astro";
79
+
---
80
+
81
+
<Default><slot /></Default>
82
+
<div class="starlight-table-of-contents-wrapper-container">
83
+
<Card />
84
+
</div>
85
+
86
+
<style>
87
+
.starlight-table-of-contents-wrapper-container {
88
+
margin-top: 1rem;
89
+
}
90
+
</style>
91
+
```
92
+
93
+
As you can see, the default table of contents are displayed by importing the component from Starlight and using it _before_ our card. See the ["Prepend content" section](#prepend-content) to display the card above the table of contents.
94
+
95
+
3. Last but not least, do not forget to set the component override in your Astro config:
96
+
97
+
```ts collapse={1-4,11-24} ins={25-27}
98
+
// astro.config.mjs
99
+
// @ts-check
100
+
import { defineConfig } from 'astro/config';
101
+
import starlight from '@astrojs/starlight';
102
+
103
+
// https://astro.build/config
104
+
export default defineConfig({
105
+
integrations: [
106
+
starlight({
107
+
title: 'My Docs',
108
+
social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
109
+
sidebar: [
110
+
{
111
+
label: 'Guides',
112
+
items: [
113
+
// Each item here is one entry in the navigation menu.
114
+
{ label: 'Example Guide', slug: 'guides/example' },
115
+
],
116
+
},
117
+
{
118
+
label: 'Reference',
119
+
autogenerate: { directory: 'reference' },
120
+
},
121
+
],
122
+
components: {
123
+
TableOfContents: "./src/components/TableOfContents.astro"
124
+
}
125
+
}),
126
+
],
127
+
});
128
+
```
129
+
130
+
</Steps>
131
+
132
+
## Prepend content
133
+
134
+
If you would prefer the table of contents _after_ your component, you need to swap the order of the elements from [Step 2 above](#step-2) and assign `margin-bottom` instead:
135
+
136
+
```astro ins={10} ins="margin-bottom: 1rem;"
137
+
---
138
+
// src/components/TableOfContents.astro
139
+
import Default from "@astrojs/starlight/components/TableOfContents.astro";
140
+
import Card from "./Card.astro";
141
+
---
142
+
143
+
<div class="starlight-table-of-contents-wrapper-container">
144
+
<Card />
145
+
</div>
146
+
<Default><slot /></Default>
147
+
148
+
<style>
149
+
.starlight-table-of-contents-wrapper-container {
150
+
margin-bottom: 1rem;
151
+
}
152
+
</style>
153
+
```
154
+
155
+
The rest of the 3 steps are the same, so do not forget to complete them all!
156
+
157
+
## Place content at bottom
158
+
159
+
If you want to have more spacing between your new shiny content and the table of contents, you can use some CSS tricks to achieve this. Add these global styles to the bottom of your `TableOfContents.astro` component to introduce two new flexboxes which will transform your card to the bottom:
160
+
161
+
```astro collapse={1-17}
162
+
---
163
+
// src/components/TableOfContents.astro
164
+
import Default from "@astrojs/starlight/components/TableOfContents.astro";
165
+
import Card from "./Card.astro";
166
+
---
167
+
168
+
<Default><slot /></Default>
169
+
<div class="starlight-table-of-contents-wrapper-container">
170
+
<Card />
171
+
</div>
172
+
173
+
<style>
174
+
.starlight-table-of-contents-wrapper-container {
175
+
margin-top: 1rem;
176
+
}
177
+
</style>
178
+
179
+
<style is:global>
180
+
@media (min-width: 72rem) {
181
+
.right-sidebar-panel {
182
+
min-height: 100%;
183
+
display: flex;
184
+
flex-direction: column;
185
+
}
186
+
.right-sidebar-panel > .sl-container {
187
+
display: flex;
188
+
flex-direction: column;
189
+
justify-content: space-between;
190
+
flex: 1;
191
+
}
192
+
}
193
+
</style>
194
+
```
195
+
196
+
## Mobile support
197
+
198
+
The `TableOfContents.astro` is only rendered when the right sidebar is visible. This is not the case on mobile devices, where the [`MobileTableOfContents.astro` component](https://starlight.astro.build/reference/overrides/#mobiletableofcontents) will be rendered.
199
+
200
+
However, if you want to show your additional content on mobile devices, it is recommended to override the [`Pagination.astro` component](https://starlight.astro.build/reference/overrides/#pagination) as adding content to the mobile view of the right sidebar would look out of place.
201
+
202
+
Here is a quick demonstration of how your custom `Pagination.astro` override could look like:
203
+
204
+
```astro
205
+
---
206
+
// src/components/Pagination.astro
207
+
import Default from "@astrojs/starlight/components/Pagination.astro";
208
+
import Card from "./Card.astro";
209
+
---
210
+
211
+
<Default><slot /></Default>
212
+
<div class="starlight-pagination-mobile-content">
213
+
<Card />
214
+
</div>
215
+
216
+
<style>
217
+
.starlight-pagination-mobile-content {
218
+
display: block;
219
+
}
220
+
@media (min-width: 72rem) {
221
+
.starlight-pagination-mobile-content {
222
+
display: none;
223
+
}
224
+
}
225
+
</style>
226
+
```
227
+
228
+
Note that the card will have much more width when displayed under the pagination than in the table of contents. So make sure to use responsive design inside your additional content.
229
+
230
+
## Source code
231
+
232
+
You can also find the complete source code for all three variants on [GitHub](https://github.com/trueberryless/starlight-customize-toc-additional-content) or open the project directly in [StackBlitz](https://stackblitz.com/github/trueberryless/starlight-customize-toc-additional-content).
+9
src/content/docs/credits.mdx
+9
src/content/docs/credits.mdx
···
343
343
usedOnUrl="/"
344
344
/>
345
345
<ImageCredit
346
+
image="/public/blog/starlight-customize-toc-additional-content.jpg"
347
+
title="Green Plant On Blue Ceramic Pot On Brown Wooden Table"
348
+
author="Veronika FitArt"
349
+
authorUrl="https://unsplash.com/@veronikafitart"
350
+
sourceUrl="https://unsplash.com/photos/green-plant-on-blue-ceramic-pot-on-brown-wooden-table-bUmtYSRQpHs"
351
+
usedOn="Add Additional Content to Starlight's Table of Contents"
352
+
usedOnUrl="/blog/starlight-customize-toc-additional-content"
353
+
/>
354
+
<ImageCredit
346
355
image="/public/blog/authors/hideoo.jpg"
347
356
title="Latte Art in Brown Cup in Macro Photography"
348
357
author="Jonas Jacobsson"