İçeriğe geç
Starlight

Configuration Reference

Bu içerik henüz dilinizde mevcut değil.

Configure the starlight integration

Starlight is an integration built on top the Astro web framework. You can configure your project inside the astro.config.mjs configuration file:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My delightful docs site',
		}),
	],
});

You can pass the following options to the starlight integration.

title (required)

type: string

Set the title for your website. Will be used in metadata and in the browser tab title.

description

type: string

Set the description for your website. Used in metadata shared with search engines in the <meta name="description"> tag if description is not set in a page’s frontmatter.

type: LogoConfig

Set a logo image to show in the navigation bar alongside or instead of the site title. You can either set a single src property or set separate image sources for light and dark.

starlight({
	logo: {
		src: './src/assets/my-logo.svg',
	},
});

LogoConfig

type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
	| { src: string }
	| { light: string; dark: string }
);

tableOfContents

type: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
default: { minHeadingLevel: 2; maxHeadingLevel: 3; }

Configure the table of contents shown on the right of each page. By default, <h2> and <h3> headings will be included in this table of contents.

type: { baseUrl: string }

Enable “Edit this page” links by setting the base URL these should use. The final link will be editLink.baseUrl + the current page path. For example, to enable editing pages in the withastro/starlight repo on GitHub:

starlight({
	editLink: {
		baseUrl: 'https://github.com/withastro/starlight/edit/main/',
	},
});

With this config, a /introduction page would have an edit link pointing to https://github.com/withastro/starlight/edit/main/src/docs/introduction.md.

type: SidebarItem[]

Configure your site’s sidebar navigation items.

A sidebar is an array of links and groups of links. Each item must have a label and one of the following properties:

  • link — a single link to a specific URL, e.g. '/home' or 'https://example.com'.

  • items — an array containing more sidebar links and subgroups.

  • autogenerate — an object specifying a directory of your docs to automatically generate a group of links from.

starlight({
	sidebar: [
		// A single link item labelled “Home”.
		{ label: 'Home', link: '/' },
		// A group labelled “Start Here” containing two links.
		{
			label: 'Start Here',
			items: [
				{ label: 'Introduction', link: '/intro' },
				{ label: 'Next Steps', link: '/next-steps' },
			],
		},
		// A group linking to all pages in the reference directory.
		{
			label: 'Reference',
			autogenerate: { directory: 'reference' },
		},
	],
});

Sorting

Autogenerated sidebar groups are sorted by filename alphabetically. For example, a page generated from astro.md would appear above the page for starlight.md.

Collapsing groups

Groups of links are expanded by default. You can change this behavior by setting a group’s collapsed property to true.

Autogenerated subgroups respect the collapsed property of their parent group by default. Set the autogenerate.collapsed property to override this.

sidebar: [
  // A collapsed group of links.
  {
    label: 'Collapsed Links',
    collapsed: true,
    items: [
      { label: 'Introduction', link: '/intro' },
      { label: 'Next Steps', link: '/next-steps' },
    ],
  },
  // An expanded group containing collapsed autogenerated subgroups.
  {
    label: 'Reference',
    autogenerate: {
      directory: 'reference',
      collapsed: true,
    },
  },
],

Translating labels

If your site is multilingual, each item’s label is considered to be in the default locale. You can set a translations property to provide labels for your other supported languages:

sidebar: [
  // An example sidebar with labels translated to Brazilian Portuguese.
  {
    label: 'Start Here',
    translations: { 'pt-BR': 'Comece Aqui' },
    items: [
      {
        label: 'Getting Started',
        translations: { 'pt-BR': 'Introdução' },
        link: '/getting-started',
      },
      {
        label: 'Project Structure',
        translations: { 'pt-BR': 'Estrutura de Projetos' },
        link: '/structure',
      },
    ],
  },
],

SidebarItem

type SidebarItem = {
	label: string;
	translations?: Record<string, string>;
	badge?: string | BadgeConfig;
} & (
	| {
			link: string;
			attrs?: Record<string, string | number | boolean | undefined>;
	  }
	| { items: SidebarItem[]; collapsed?: boolean }
	| {
			autogenerate: { directory: string; collapsed?: boolean };
			collapsed?: boolean;
	  }
);

BadgeConfig

interface BadgeConfig {
	text: string;
	variant: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
}

locales

type: { [dir: string]: LocaleConfig }

Configure internationalization (i18n) for your site by setting which locales are supported.

Each entry should use the directory where that language’s files are saved as the key.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My Site',
			// Set English as the default language for this site.
			defaultLocale: 'en',
			locales: {
				// English docs in `src/content/docs/en/`
				en: {
					label: 'English',
				},
				// Simplified Chinese docs in `src/content/docs/zh-cn/`
				'zh-cn': {
					label: '简体中文',
					lang: 'zh-CN',
				},
				// Arabic docs in `src/content/docs/ar/`
				ar: {
					label: 'العربية',
					dir: 'rtl',
				},
			},
		}),
	],
});

LocaleConfig

interface LocaleConfig {
	label: string;
	lang?: string;
	dir?: 'ltr' | 'rtl';
}

You can set the following options for each locale:

label (required)

type: string

The label for this language to show to users, for example in the language switcher. Most often you will want this to be the language’s name as a user of that language would expect to read it, e.g. "English", "العربية", or "简体中文".

lang

type: string

The BCP-47 tag for this language, e.g. "en", "ar", or "zh-CN". If not set, the language’s directory name will be used by default. Language tags with regional subtags (e.g. "pt-BR" or "en-US") will use built-in UI translations for their base language if no region-specific translations are found.

dir

type: 'ltr' | 'rtl'

The writing direction of this language; "ltr" for left-to-right (the default) or "rtl" for right-to-left.

Root locale

You can serve the default language without a /lang/ directory by setting a root locale:

starlight({
	locales: {
		root: {
			label: 'English',
			lang: 'en',
		},
		fr: {
			label: 'Français',
		},
	},
});

For example, this allows you to serve /getting-started/ as an English route and use /fr/getting-started/ as the equivalent French page.

defaultLocale

type: string

Set the language which is the default for this site. The value should match one of the keys of your locales object. (If your default language is your root locale, you can skip this.)

The default locale will be used to provide fallback content where translations are missing.

social

type: Partial<Record<'bitbucket' | 'codeberg' | 'codePen' | 'discord' | 'email' | 'facebook' | 'github' | 'gitlab' | 'gitter' | 'instagram' | 'linkedin' | 'mastodon' | 'microsoftTeams' | 'patreon' | 'reddit' | 'rss' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'twitch' | 'twitter' | 'x.com' | 'youtube', string>>

Optional details about the social media accounts for this site. Adding any of these will display them as icon links in the site header.

starlight({
	social: {
		codeberg: 'https://codeberg.org/knut/examples',
		discord: 'https://astro.build/chat',
		github: 'https://github.com/withastro/starlight',
		gitlab: 'https://gitlab.com/delucis',
		linkedin: 'https://www.linkedin.com/company/astroinc',
		mastodon: 'https://m.webtoo.ls/@astro',
		threads: 'https://www.threads.net/@nmoodev',
		twitch: 'https://www.twitch.tv/bholmesdev',
		twitter: 'https://twitter.com/astrodotbuild',
		'x.com': 'https://x.com/astrodotbuild',
		youtube: 'https://youtube.com/@astrodotbuild',
	},
});

customCss

type: string[]

Provide CSS files to customize the look and feel of your Starlight site.

Supports local CSS files relative to the root of your project, e.g. './src/custom.css', and CSS you installed as an npm module, e.g. '@fontsource/roboto'.

starlight({
	customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
});

type: HeadConfig[]

Add custom tags to the <head> of your Starlight site. Can be useful for adding analytics and other third-party scripts and resources.

starlight({
	head: [
		// Example: add Fathom analytics script tag.
		{
			tag: 'script',
			attrs: {
				src: 'https://cdn.usefathom.com/script.js',
				'data-site': 'MY-FATHOM-ID',
				defer: true,
			},
		},
	],
});

HeadConfig

interface HeadConfig {
	tag: string;
	attrs?: Record<string, string | boolean | undefined>;
	content?: string;
}

lastUpdated

type: boolean
default: false

Control whether the footer shows when the page was last updated.

By default, this feature relies on your repository’s Git history and may not be accurate on some deployment platforms performing shallow clones. A page can override this setting or the Git-based date using the lastUpdated frontmatter field.

pagination

type: boolean
default: true

Define if the footer should include previous and next page links.

A page can override this setting or the link text and/or URL using the prev and next frontmatter fields.

favicon

type: string
default: '/favicon.svg'

Set the path of the default favicon for your website which should be located in the public/ directory and be a valid (.ico, .gif, .jpg, .png, or .svg) icon file.

starlight({
  favicon: '/images/favicon.svg',
}),

If you need to set additional variants or fallback favicons, you can add tags using the head option:

starlight({
  favicon: '/images/favicon.svg'.
  head: [
    // Add ICO favicon fallback for Safari.
    {
      tag: 'link',
      attrs: {
        rel: 'icon',
        href:'/images/favicon.ico',
        sizes: '32x32',
      },
    },
  ],
});

titleDelimiter

type: string
default: '|'

Sets the delimiter between page title and site title in the page’s <title> tag, which is displayed on browser tabs.

By default, every page has a <title> of Page Title | Site Title. For example, this page is titled “Configuration Reference” and this site is titled “Starlight”, so the <title> for this page is “Configuration Reference | Starlight”.

components

type: Record<string, string>

Provide the paths to components to override Starlight’s default implementations.

starlight({
	components: {
		SocialLinks: './src/components/MySocialLinks.astro',
	},
});

See the Overrides Reference for details of all the components that you can override.