Skip to content

Commit

Permalink
Prioritise slug over link
Browse files Browse the repository at this point in the history
  • Loading branch information
@delucis
delucis committed Jul 3, 2024
1 parent 0eb43b6 commit 7921d51
Showing 1 changed file with 44 additions and 50 deletions.
94 changes: 44 additions & 50 deletions docs/src/content/docs/guides/sidebar.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,39 +49,14 @@ Learn more about autogenerated sidebars in the [autogenerated groups](#autogener

## Add links and link groups

To configure your sidebar [links](#links) and [groups of links](#groups) (within a collapsible header), use the [`starlight.sidebar`](/reference/configuration/#sidebar) property in `astro.config.mjs`.
To configure your sidebar links and groups of links (within a collapsible header), use the [`starlight.sidebar`](/reference/configuration/#sidebar) property in `astro.config.mjs`.

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

### Links

Add a link to an internal or external page using an object with `label` and `link` properties.

```js "label:" "link:"
starlight({
sidebar: [
// A link to the Ganymede moon page.
{ label: 'Ganymede', link: '/moons/ganymede/' },
// An external link to the NASA website.
{ label: 'NASA', link: 'https://www.nasa.gov/' },
],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
config={[
{ label: 'Ganymede', link: '' },
{ label: 'NASA', link: 'https://www.nasa.gov/' },
]}
/>

### Internal links

Add a link to an internal page using an object with the `slug` property.
The title will automatically be inferred from the frontmatter of the content.
In multilingual sites, translated content will be used automatically.
Add a link to an internal docs page using an object with the `slug` property.
The linked page’s title will be used as the label by default and in multilingual sites, translated content will be used automatically.

```js "slug:"
starlight({
Expand All @@ -101,11 +76,11 @@ The configuration above generates the following sidebar:
]}
/>

If you need to override the page’s frontmatter values, use explicit `label`, [`translations`](#internationalization), and [`attrs`](#custom-html-attributes) properties.
To override the values inferred from a linked page’s frontmatter, you can add `label`, [`translations`](#internationalization), and [`attrs`](#custom-html-attributes) properties.

See [“Customizing autogenerated links”](#customizing-autogenerated-links-in-frontmatter) for more details about controlling the sidebar appearance from page frontmatter.

#### Shorthand internal links
#### Shorthand for internal links

Internal links can also be specified by providing only a string for the page slug as a shorthand.

Expand All @@ -117,6 +92,30 @@ starlight({
});
```

### Other links

Add a link to an external or non-docs page using an object with `label` and `link` properties.

```js "label:" "link:"
starlight({
sidebar: [
// A link to a non-docs page on this site.
{ label: 'Meteor Store', link: '/shop/' },
// An external link to the NASA website.
{ label: 'NASA', link: 'https://www.nasa.gov/' },
],
});
```

The configuration above generates the following sidebar:

<SidebarPreview
config={[
{ label: 'Meteor Store', link: '' },
{ label: 'NASA', link: 'https://www.nasa.gov/' },
]}
/>

### Groups

You can add structure to your sidebar by grouping related links together under a collapsible heading.
Expand All @@ -133,15 +132,15 @@ starlight({
{
label: 'Constellations',
items: [
{ label: 'Carina', link: '/constellations/carina/' },
{ label: 'Centaurus', link: '/constellations/centaurus/' },
'constellations/carina',
'constellations/centaurus',
// A nested group of links for seasonal constellations.
{
label: 'Seasonal',
items: [
{ label: 'Andromeda', link: '/constellations/andromeda/' },
{ label: 'Orion', link: '/constellations/orion/' },
{ label: 'Ursa Minor', link: '/constellations/ursa-minor/' },
'constellations/andromeda',
'constellations/orion',
'constellations/ursa-minor',
],
},
],
Expand Down Expand Up @@ -226,7 +225,7 @@ The following sidebar will be generated:
]}
/>

#### Customizing autogenerated links in frontmatter
## Customizing autogenerated links in frontmatter

Use the [`sidebar` frontmatter field](/reference/frontmatter/#sidebar) in individual pages to customize autogenerated links.

Expand Down Expand Up @@ -268,23 +267,22 @@ An autogenerated group including a page with the frontmatter above will generate
/>

:::note
The `sidebar` frontmatter configuration is only used for autogenerated links and will be ignored for manually defined links.
The `sidebar` frontmatter configuration is only used for links in autogenerated groups and docs links defined with the `slug` property. It does not apply to links defined with the `link` property.
:::

## Badges

Links, groups, and autogenerated groups can also include a `badge` property to display a badge next to their label.

```js {10,17}
```js {9,16}
starlight({
sidebar: [
{
label: 'Stars',
items: [
// A link with a "Supergiant" badge.
{
label: 'Persei',
link: '/stars/persei/',
slug: 'stars/persei',
badge: 'Supergiant',
},
],
Expand Down Expand Up @@ -343,16 +341,15 @@ By default, the badge will use the accent color of your site. To use a built-in

Optionally, you can create a custom badge style by setting the `class` property to a CSS class name.

```js {10}
```js {9}
starlight({
sidebar: [
{
label: 'Stars',
items: [
// A link with a yellow "Stub" badge.
{
label: 'Sirius',
link: '/stars/sirius/',
slug: 'stars/sirius',
badge: { text: 'Stub', variant: 'caution' },
},
],
Expand Down Expand Up @@ -441,14 +438,14 @@ starlight({
translations: {
'pt-BR': 'Andrômeda',
},
link: '/constellations/andromeda/',
slug: 'constellations/andromeda',
},
{
label: 'Scorpius',
translations: {
'pt-BR': 'Escorpião',
},
link: '/constellations/scorpius/',
slug: 'constellations/scorpius',
},
],
},
Expand All @@ -472,7 +469,7 @@ Browsing the documentation in Brazilian Portuguese will generate the following s

### Internationalization with internal links

[Internal links](#internal-links) can also be used to infer translated page titles from content frontmatter:
[Internal links](#internal-links) will automatically use translated page titles from content frontmatter by default:

```js {9-10}
starlight({
Expand Down Expand Up @@ -519,10 +516,7 @@ starlight({
label: 'Constellations',
// Collapse the group by default.
collapsed: true,
items: [
{ label: 'Andromeda', link: '/constellations/andromeda/' },
{ label: 'Orion', link: '/constellations/orion/' },
],
items: ['constellations/andromeda', 'constellations/orion'],
},
],
});
Expand Down

0 comments on commit 7921d51

Please sign in to comment.