Mirror of
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

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

This is a binary file and will not be displayed.

+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
··· 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"