Configuration Reference
Цей контент ще не доступний вашою мовою.
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:
You can pass the following options to the starlight
integration.
title
(required)
type: string | Record<string, string>
Set the title for your website. Will be used in metadata and in the browser tab title.
The value can be a string, or for multilingual sites, an object with values for each different locale.
When using the object form, the keys must be BCP-47 tags (e.g. en
, ar
, or zh-CN
):
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.
logo
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
.
LogoConfig
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.
editLink
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:
With this config, a /introduction
page would have an edit link pointing to https://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md
.
sidebar
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.
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.
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:
SidebarItem
BadgeConfig
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.
LocaleConfig
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:
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' | 'matrix' | 'microsoftTeams' | 'openCollective' | 'patreon' | 'reddit' | 'rss' | 'signal' | '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.
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'
.
expressiveCode
type: StarlightExpressiveCodeOptions | boolean
default: true
Starlight uses Expressive Code to render code blocks and add support for highlighting parts of code examples, adding filenames to code blocks, and more. See the “Code blocks” guide to learn how to use Expressive Code syntax in your Markdown and MDX content.
You can use any of the standard Expressive Code configuration options as well as some Starlight-specific properties, by setting them in Starlight’s expressiveCode
option.
For example, set Expressive Code’s styleOverrides
option to override the default CSS. This enables customizations like giving your code blocks rounded corners:
If you want to disable Expressive Code, set expressiveCode: false
in your Starlight config:
In addition to the standard Expressive Code options, you can also set the following Starlight-specific properties in your expressiveCode
config to further customize theme behavior for your code blocks :
themes
type: Array<string | ThemeObject | ExpressiveCodeTheme>
default: ['starlight-dark', 'starlight-light']
Set the themes used to style code blocks.
See the Expressive Code themes
documentation for details of the supported theme formats.
Starlight uses the dark and light variants of Sarah Drasner’s Night Owl theme by default.
If you provide at least one dark and one light theme, Starlight will automatically keep the active code block theme in sync with the current site theme.
Configure this behavior with the useStarlightDarkModeSwitch
option.
useStarlightDarkModeSwitch
type: boolean
default: true
When true
, code blocks automatically switch between light and dark themes when the site theme changes.
When false
, you must manually add CSS to handle switching between multiple themes.
useStarlightUiThemeColors
type: boolean
default: true
if themes
is not set, otherwise false
When true
, Starlight’s CSS variables are used for the colors of code block UI elements (backgrounds, buttons, shadows etc.), matching the site color theme.
When false
, the colors provided by the active syntax highlighting theme are used for these elements.
pagefind
type: boolean
default: true
Define whether Starlight’s default site search provider Pagefind is enabled.
Set to false
to disable indexing your site with Pagefind.
This will also hide the default search UI if in use.
head
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.
Entries in head
are converted directly to HTML elements and do not pass through Astro’s script or style processing.
If you need to import local assets like scripts, styles, or images, override the Head component.
HeadConfig
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.
If you need to set additional variants or fallback favicons, you can add tags using the head
option:
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”.
disable404Route
type: boolean
default: false
Disables injecting Starlight’s default 404 page. To use a custom src/pages/404.astro
route in your project, set this option to true
.
components
type: Record<string, string>
Provide the paths to components to override Starlight’s default implementations.
See the Overrides Reference for details of all the components that you can override.
plugins
type: StarlightPlugin[]
Extend Starlight with custom plugins. Plugins apply changes to your project to modify or add to Starlight’s features.
Visit the plugins showcase to see a list of available plugins.
See the Plugins Reference for details about creating your own plugins.