Skip to content

Instantly share code, notes, and snippets.

@sarah11918

sarah11918/sarah-sidebar.mdx

Created August 28, 2023 23:27
Show Gist options
  • Save sarah11918/3182d39b0344afda8178a815caa7f499 to your computer and use it in GitHub Desktop.
Save sarah11918/3182d39b0344afda8178a815caa7f499 to your computer and use it in GitHub Desktop.
Download ZIP
sidebar
Raw
sarah-sidebar.mdx
title description
Sidebar Customization
Learn how to customize the sidebar of your documentation.

import FileTree from '../../../components/file-tree.astro'; import SidebarPreview from '../../../components/sidebar-preview.astro';

A well-organized sidebar is key to a good documentation as it is one of the main ways users will navigate your site. Starlight provides a complete set of options to customize your sidebar layout and content.

Default sidebar

By default, Starlight will automatically generate a sidebar based on the filesystem structure of your documentation, using each file's title property as the sidebar entry.

For example, given the following file structure:

  • src/
    • content/
      • docs/
        • guides/
          • components.md
          • i18n.md
        • reference/
          • configuration.md

The following sidebar will be automatically generated:

<SidebarPreview config={[ { label: 'guides', items: [ { label: 'Components', link: '/guides/components/' }, { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, ], }, { label: 'reference', items: [ { label: 'Configuration Reference', link: '/reference/configuration/' }, ], }, ]} />

Learn more about autogenerated sidebars in the autogenerated groups section.

Basic configuration

To configure your sidebar links and groups of links (within a collapsible header), use the starlight.sidebar property in astro.config.mjs, located at the root of your project.

Links

A link to an internal or external page must be defined by a label and a link property.

starlight({
	sidebar: [
		// A link to the CSS & Styling guide.
		{ label: 'CSS & Styling', link: '/guides/css-and-tailwind/' },
		// An external link to the Astro website.
		{ label: 'Astro', link: 'https://astro.build/' },
	],
});

With the above configuration, the following sidebar will be generated:

<SidebarPreview config={[ { label: 'CSS & Styling', link: '/guides/css-and-tailwind/' }, { label: 'Astro', link: 'https://astro.build/' }, ]} />

Groups

Links can be grouped together under a heading. Groups can contain both links and other sub-groups.

A group is defined by a label string and an items array containing other links and/or groups.

starlight({
	sidebar: [
		// A group of links labelled "Guides".
		{
			label: 'Guides',
			items: [
				{ label: 'Components', link: '/guides/components/' },
				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
				// A nested group of links.
				{
					label: 'Styling',
					items: [
						{ label: 'CSS', link: '/guides/css-and-tailwind/' },
						{ label: 'Tailwind', link: '/guides/css-and-tailwind/' },
						{ label: 'Shiki', link: '/guides/css-and-tailwind/' },
					],
				},
			],
		},
	],
});

The above configuration will generate the following sidebar:

<SidebarPreview config={[ { label: 'Guides', items: [ { label: 'Components', link: '/guides/components/' }, { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, { label: 'Styling', items: [ { label: 'CSS', link: '/guides/css-and-tailwind/' }, { label: 'Tailwind', link: '/guides/css-and-tailwind/' }, { label: 'Shiki', link: '/guides/css-and-tailwind/' }, ], }, ], }, ]} />

By combining links and groups, you can create a wide variety of sidebars layouts.

Badges

Links can also include a badge property to display a badge next to the link label.

starlight({
	sidebar: [
		{
			label: 'Guides',
			items: [
				// A link with a "New" badge.
				{
					label: 'Components',
					link: '/guides/components/',
					badge: 'New',
				},
			],
		},
	],
});

The above configuration will generate the following sidebar:

<SidebarPreview config={[ { label: 'Guides', items: [ { label: 'Components', link: '/guides/components/', badge: { text: 'New', variant: 'default' }, }, ], }, ]} />

The badge property includes a text property (the content to display in the badge) and optionally a variant property (to define the type of badge shown).

badge.text - a string representing the content to display. (e.g. "New")

badge.variant - to override the default styling setting, set to one of the following properties for custom styling: note, tip, danger, caution or success.

starlight({
	sidebar: [
		{
			label: 'Guides',
			items: [
				// A link with a green "New" badge.
				{
					label: 'Components',
					link: '/guides/components/',
					badge: { text: 'Experimental', variant: 'caution' },
				},
			],
		},
	],
});

The above configuration will generate the following sidebar:

<SidebarPreview config={[ { label: 'Guides', items: [ { label: 'Components', link: '/guides/components/', badge: { text: 'Experimental', variant: 'caution' }, }, ], }, ]} />

Autogenerated groups

Any group (or sub-group) can be automatically generated, and will be sorted alphabetically by filename. This is helpful when you do not want to manually enter each sidebar item in a group.

To create an autogenerated group, set autogenerate to an object specifying the directory. For example, given the following file structure:

  • src/
    • content/
      • docs/
        • guides/
          • components.md
          • i18n.md
          • advanced/
            • project-structure.md

And the following configuration:

starlight({
	sidebar: [
		{
			label: 'Guides',
			// Autogenerate a group of links for the 'guides' directory.
			autogenerate: { directory: 'guides' },
		},
	],
});

The following sidebar will be generated:

<SidebarPreview config={[ { label: 'Guides', items: [ { label: 'Components', link: '/guides/components/' }, { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, { label: 'advanced', items: [ { label: 'Project Structure', link: '/guides/project-structure/' }, ], }, ], }, ]} />

Customizing autogenerated links in frontmatter

Use the sidebar frontmatter field to customize autogenerated links.

This field allows you to set a custom label or add a badge for a page link, to hide a link from the sidebar or to define a custom order for all page links.

---
title: My page
sidebar:
  # Set a custom label for the link
  label: Custom sidebar label
  # Show the link in the sidebar
  hidden: false
  # Set a custom order for the link (lower numbers are displayed higher up)
  order: 2
  # Add a badge to the link
  badge:
    text: Deprecated
    variant: caution
---

A sidebar including an autogenerated group for the guides directory containing a page with the above frontmatter will generate the following sidebar:

<SidebarPreview config={[ { label: 'Guides', items: [ { label: 'A page', link: '#' }, { label: 'Custom sidebar label', link: '#', badge: { text: 'Deprecated', variant: 'yellow' }, }, { label: 'Another page', link: '#' }, ], }, ]} />

:::note The sidebar frontmatter configuration is only used for autogenerated links and will be ignored for manually defined links. :::

Internationalization

Manually defined link and group labels can be translated using the translations property to define a set of labels for each supported language while the label property will act as the default locale.

starlight({
	sidebar: [
		{
			label: 'Guides',
			translations: { es: 'Guías' },
			items: [
				{
					label: 'Components',
					translations: { es: 'Componentes' },
					link: '/guides/components/',
				},
				{
					label: 'Internationalization (i18n)',
					translations: { es: 'Internacionalización (i18n)' },
					link: '/guides/i18n/',
				},
			],
		},
	],
});

Browsing the documentation in Spanish will generate the following sidebar:

<SidebarPreview config={[ { label: 'Guías', items: [ { label: 'Componentes', link: '/guides/components/' }, { label: 'Internacionalización (i18n)', link: '/guides/i18n/' }, ], }, ]} />

Collapsing groups

Groups of links can be collapsed by default by setting the collapsed property to true.

starlight({
	sidebar: [
		{
			label: 'Guides',
			// Collapse the group by default.
			collapsed: true,
			items: [
				{ label: 'Components', link: '/guides/components/' },
				{ label: 'Internationalization (i18n)', link: '/guides/i18n/' },
			],
		},
	],
});

The above configuration will generate the following sidebar:

<SidebarPreview config={[ { label: 'Guides', collapsed: true, items: [ { label: 'Components', link: '/guides/components/' }, { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, ], }, ]} />

Autogenerated groups respect the collapsed value of their parent group:

starlight({
	sidebar: [
		{
			label: 'Guides',
			// Collapse the group and its autogenerated subgroups by default.
			collapsed: true,
			autogenerate: { directory: 'guides' },
		},
	],
});

The sidebar generated by the above configuration will be:

<SidebarPreview config={[ { label: 'Guides', collapsed: true, items: [ { label: 'Components', link: '/guides/components/' }, { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, { label: 'advanced', collapsed: true, items: [ { label: 'Project Structure', link: '/guides/project-structure/' }, ], }, ], }, ]} />

This behavior can be overridden by defining the autogenerate.collapsed property.

starlight({
	sidebar: [
		{
			label: 'Guides',
			// Do not collapse the "Guides" group but collapse its
			// autogenerated subgroups.
			collapsed: false,
			autogenerate: { directory: 'guides', collapsed: true },
		},
	],
});

The generated sidebar will be:

<SidebarPreview config={[ { label: 'Guides', items: [ { label: 'Components', link: '/guides/components/' }, { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, { label: 'advanced', collapsed: true, items: [ { label: 'Project Structure', link: '/guides/project-structure/' }, ], }, ], }, ]} />

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment