Aller au contenu
Deep Thoughts

Add Additional Content to Starlight's Table of Contents

Cette traduction a été générée par une IA générative à l'aide de la traduction continue Action. →

Ce contenu n’est pas encore disponible dans votre langue.

A wooden table featuring a decorative flower vase at its center, adding a touch of elegance to the setting.
• 3 min de lecture • 500 mots
Felix Schneider
Felix Schneider
trueberryless

This guide shows how you can append additional content like credits, ads or additional information below to list of headings in your right iconStarlight sidebar.

Append content

Starlight’s table of contents can be modified by overriding the TableOfContents.astro component. Follow these steps to append a small Astro component after the existing table of contents:

  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:

    src/components/Card.astro
    ---
    ---
    

    <aside class="not-content starlight-table-of-contents-aside">
        <h2>Some card!</h2>
        <p>With some text 🙌</p>
    </aside>
    

    26 collapsed lines
    <style>
        .starlight-table-of-contents-aside {
            position: relative;
            background-color: var(--sl-color-gray-6);
            padding: 1rem;
            border-radius: 0.5rem;
            border: 1px solid var(--sl-color-text-accent);
            box-shadow: var(--sl-shadow-md);
            overflow-y: hidden;
        }
        .starlight-table-of-contents-aside h2 {
            color: var(--sl-color-white);
            font-size: var(--sl-text-h5);
            font-weight: 600;
            text-decoration: none !important;
            line-height: var(--sl-line-height-headings);
            margin-bottom: 0.5rem;
        }
        .starlight-table-of-contents-aside p {
            font-size: var(--sl-text-xs);
            line-height: normal;
            text-decoration: none !important;
            color: var(--sl-color-gray-3);
            overflow-wrap: anywhere;
        }
    </style>

    Note the usage of the "not-content" class feature provided by Starlight to make sure that Starlight’s styles for elements do not apply here as it is a custom component.

  2. Create the TableOfContents.astro component, which will be used as the replacement of Starlight’s default table of contents component:

    src/components/TableOfContents.astro
    ---
    import Default from "@astrojs/starlight/components/TableOfContents.astro";
    import Card from "./Card.astro";
    ---
    

    <Default><slot /></Default>
    <div class="starlight-table-of-contents-wrapper-container">
        <Card />
    </div>
    

    <style>
        .starlight-table-of-contents-wrapper-container {
            margin-top: 1rem;
        }
    </style>

    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 to display the card above the table of contents.

  3. Last but not least, do not forget to set the component override in your Astro config:

    astro.config.mjs
    3 collapsed lines
    // @ts-check
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    

    // https://astro.build/config
    export default defineConfig({
      integrations: [
        starlight({
          title: 'My Docs',
    14 collapsed lines
          social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
          sidebar: [
            {
              label: 'Guides',
              items: [
                // Each item here is one entry in the navigation menu.
                { label: 'Example Guide', slug: 'guides/example' },
              ],
            },
            {
              label: 'Reference',
              autogenerate: { directory: 'reference' },
            },
          ],
          components: {
            TableOfContents: "./src/components/TableOfContents.astro"
          }
        }),
      ],
    });

Prepend content

If you would prefer the table of contents after your component, you need to swap the order of the elements from Step 2 above and assign margin-bottom instead:

src/components/TableOfContents.astro
---
import Default from "@astrojs/starlight/components/TableOfContents.astro";
import Card from "./Card.astro";
---


<div class="starlight-table-of-contents-wrapper-container">
    <Card />
</div>
<Default><slot /></Default>


<style>
    .starlight-table-of-contents-wrapper-container {
        margin-bottom: 1rem;
    }
</style>

The rest of the 3 steps are the same, so do not forget to complete them all!

Place content at bottom

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:

src/components/TableOfContents.astro
16 collapsed lines
---
import Default from "@astrojs/starlight/components/TableOfContents.astro";
import Card from "./Card.astro";
---


<Default><slot /></Default>
<div class="starlight-table-of-contents-wrapper-container">
    <Card />
</div>


<style>
    .starlight-table-of-contents-wrapper-container {
        margin-top: 1rem;
    }
</style>


<style is:global>
    @media (min-width: 72rem) {
        .right-sidebar-panel {
            min-height: 100%;
            display: flex;
            flex-direction: column;
        }
        .right-sidebar-panel > .sl-container {
            display: flex;
            flex-direction: column;
            justify-content: space-between;
            flex: 1;
        }
    }
</style>

Mobile support

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 will be rendered.

However, if you want to show your additional content on mobile devices, it is recommended to override the Pagination.astro component as adding content to the mobile view of the right sidebar would look out of place.

Here is a quick demonstration of how your custom Pagination.astro override could look like:

src/components/Pagination.astro
---
import Default from "@astrojs/starlight/components/Pagination.astro";
import Card from "./Card.astro";
---


<Default><slot /></Default>
<div class="starlight-pagination-mobile-content">
    <Card />
</div>


<style>
    .starlight-pagination-mobile-content {
        display: block;
    }
    @media (min-width: 72rem) {
        .starlight-pagination-mobile-content {
            display: none;
        }
    }
</style>

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.

Source code

You can also find the complete source code for all three variants on GitHubGitHub or open the project directly in iconStackBlitz.

Étiquettes :