#3058 274cc06 Thanks @techfg! - Fixes display of focus indicator around site title
#3181 449c822 Thanks @HiDeoo! - Fixes an issue where all headings in Markdown and MDX content were rendered with a clickable anchor link, even in non-Starlight pages.
#3168 ca693fe Thanks @jsparkdev! - Updates Korean langage support with improvements and missing translations
#3153 ea31f46 Thanks @SuperKXT! - Fixes hover styles for highlighted directory in FileTree component.
#2905 b5232bc Thanks @HiDeoo! - Fixes a potential issue for projects with dynamic routes added by an user, an Astro integration, or a Starlight plugin where some styles could end up being missing.
#3165 80a7871 Thanks @KianNH! - Increases maxBuffer for an internal spawnSync() call to support larger Git commit histories when using Starlight’s lastUpdated feature.
#3158 d1f3c8b Thanks @heisenberg0924! - Adds Hungarian language support
#2322 f14eb0c Thanks @HiDeoo! - Groups all of Starlight’s CSS declarations into a single starlight cascade layer.
This change allows for easier customization of Starlight’s CSS as any custom unlayered CSS will override the default styles. If you are using cascade layers in your custom CSS, you can use the @layer CSS at-rule to define the order of precedence for different layers including the ones used by Starlight.
We recommend checking your site’s appearance when upgrading to make sure there are no style regressions caused by this change.
#3122 3a087d8 Thanks @delucis! - Removes default attrs and content values from head entries parsed using Starlight’s schema.
Previously when adding head metadata via frontmatter or user config, Starlight would automatically add values for attrs and content if not provided. Now, these properties are left undefined.
This makes it simpler to add tags in route middleware for example as you no longer need to provide empty values for attrs and content:
head.push({ tag: 'style', content: 'div { color: red }' attrs: {},});head.push({ tag: 'link', content: '' attrs: { rel: 'me', href: 'https://example.com' },});This is mostly an internal API but if you are overriding Starlight’s Head component or processing head entries in some way, you may wish to double check your handling of Astro.locals.starlightRoute.head is compatible with attrs and content potentially being undefined.
#3033 8c19678 Thanks @delucis! - Adds support for generating clickable anchor links for headings.
By default, Starlight now renders an anchor link beside headings in Markdown and MDX content. A new <AnchorHeading> component is available to achieve the same thing in custom pages built using <StarlightPage>.
If you want to disable this new Markdown processing set the markdown.headingLinks option in your Starlight config to false:
starlight({ title: 'My docs', markdown: { headingLinks: false, },}),⚠️ BREAKING CHANGE: The minimum supported version of Astro is now v5.5.0.
Please update Starlight and Astro together:
npx @astrojs/upgrade#2322 f14eb0c Thanks @HiDeoo! - Removes Shiki css-variables theme fallback.
⚠️ BREAKING CHANGE:
Previously, Starlight used to automatically provide a fallback theme for Shiki, the default syntax highlighter built into Astro if the configured Shiki theme was not github-dark.
This fallback was only relevant when the default Starlight code block renderer, Expressive Code, was disabled and Shiki was used. Starlight no longer provides this fallback.
If you were relying on this behavior, you now manually need to update your Astro configuration to use the Shiki css-variables theme to match the previous behavior.
import { defineConfig } from 'astro/config';
export default defineConfig({ markdown: { shikiConfig: { theme: 'css-variables', }, },});Additionally, you can use custom CSS to control the appearance of the code blocks. Here are the previously used CSS variables for the fallback theme:
:root { --astro-code-foreground: var(--sl-color-white); --astro-code-background: var(--sl-color-gray-6); --astro-code-token-constant: var(--sl-color-blue-high); --astro-code-token-string: var(--sl-color-green-high); --astro-code-token-comment: var(--sl-color-gray-2); --astro-code-token-keyword: var(--sl-color-purple-high); --astro-code-token-parameter: var(--sl-color-red-high); --astro-code-token-function: var(--sl-color-red-high); --astro-code-token-string-expression: var(--sl-color-green-high); --astro-code-token-punctuation: var(--sl-color-gray-2); --astro-code-token-link: var(--sl-color-blue-high);}#3088 1885049 Thanks @HiDeoo! - Fixes a regression in Starlight version 0.33.0 that caused the description and links to language alternates for multilingual websites to be missing from the <head> of the page.
#3065 463adf5 Thanks @HiDeoo! - Updates the social configuration option TSDoc example to match the shape of the expected value.
#3026 82deb84 Thanks @HiDeoo! - Fixes a potential list styling issue if the last element of a list item is a <script> tag.
⚠️ BREAKING CHANGE:
This release drops official support for Chromium-based browsers prior to version 105 (released 30 August 2022) and Firefox-based browsers prior to version 121 (released 19 December 2023). You can find a list of currently supported browsers and their versions using this browserslist query.
With this release, Starlight-generated sites will still work fine on those older browsers except for this small detail in list item styling, but future releases may introduce further breaking changes for impacted browsers, including in patch releases.
#3025 f87e9ac Thanks @delucis! - Makes social configuration more flexible.
⚠️ BREAKING CHANGE: The social configuration option has changed syntax. You will need to update this in astro.config.mjs when upgrading.
Previously, a limited set of platforms were supported using a shorthand syntax with labels built in to Starlight. While convenient, this approach was less flexible and required dedicated code for each social platform added.
Now, you must specify the icon and label for each social link explicitly and you can use any of Starlight’s built-in icons for social links.
The following example shows updating the old social syntax to the new:
social: { github: 'https://github.com/withastro/starlight', discord: 'https://astro.build/chat',},social: [ { icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }, { icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },],#2927 c46904c Thanks @HiDeoo! - Adds the head route data property which contains an array of all tags to include in the <head> of the current page.
Previously, the <Head> component was responsible for generating a list of tags to include in the <head> of the current page and rendering them.
This data is now available as Astro.locals.starlightRoute.head instead and can be modified using route data middleware.
The <Head> component now only renders the tags provided in Astro.locals.starlightRoute.head.
#2924 6a56d1b Thanks @HiDeoo! - ⚠️ BREAKING CHANGE: Ensures that the <Badge> and <Icon> components no longer render with a trailing space.
In Astro, components that include styles render with a trailing space which can prevent some use cases from working as expected, e.g. when using such components inlined with text. This change ensures that the <Badge> and <Icon> components no longer render with a trailing space.
If you were previously relying on that implementation detail, you may need to update your code to account for this change. For example, considering the following code:
<Badge text="New" />FeatureThe rendered text would previously include a space between the badge and the text due to the trailing space automatically added by the component:
New FeatureSuch code will now render the badge and text without a space:
NewFeatureTo fix this, you can add a space between the badge and the text:
<Badge text="New" />Feature<Badge text="New" /> Feature#2727 7c8fa30 Thanks @techfg! - Updates mobile menu toggle styles to display a close icon while the menu is open
#2927 c46904c Thanks @HiDeoo! - Fixes an issue where overriding the canonical URL of a page using the head configuration option or head frontmatter field would strip any other <link> tags from the <head>.
#2927 c46904c Thanks @HiDeoo! - Fixes an issue where generated canonical URLs would include a trailing slash when using the trailingSlash Astro option is set to 'never'.
#3025 f87e9ac Thanks @delucis! - Fixes Starlight’s autogenerated <meta name="twitter:site"> tags when a Twitter link is set in social config. Previously these incorrectly rendered content="/username" and now correctly render content="@username".
#3030 5bdf139 Thanks @trueberryless! - Updates the type of the isFallback field in route data from true to boolean, keeping it optional but allowing false as a possible value.
#3018 188b8cf Thanks @trueberryless! - Adds validation for user config routeMiddleware so it does not conflict with Astro’s middleware.
#3021 e3f881e Thanks @jsparkdev! - Updates Korean language support
#3013 5b599dd Thanks @oluwatobiss! - Adds Substack icon to social links list
#2955 77b6a41 Thanks @trueberryless! - Adds 5 new icons: figma, sketch, vim, vscode, and zed.
#2961 da57fab Thanks @ematipico! - Adds 1 new icon: jetbrains.
#2926 c0170fd Thanks @resoltico! - Adds Latvian language support
#2918 790c000 Thanks @HiDeoo! - Fixes a trailing slash inconsistency in generated sidebar links when using the trailingSlash: 'ignore' Astro option (the default) between internal and auto-generated links. Starlight behavior for this configuration value is to use a trailing slash as many common hosting providers redirect to URLs with a trailing slash by default.
#2390 f493361 Thanks @delucis! - Moves route data to Astro.locals instead of passing it down via component props
⚠️ Breaking change:
Previously, all of Starlight’s templating components, including user or plugin overrides, had access to a data object for the current route via Astro.props.
This data is now available as Astro.locals.starlightRoute instead.
To update, refactor any component overrides you have:
@astrojs/starlight/props, which is now deprecated.Astro.props to use Astro.locals.starlightRoute instead.{...Astro.props} into child components, which is no longer required.In the following example, a custom override for Starlight’s LastUpdated component is updated for the new style:
---import Default from '@astrojs/starlight/components/LastUpdated.astro'; import type { Props } from '@astrojs/starlight/props';
const { lastUpdated } = Astro.props; const { lastUpdated } = Astro.locals.starlightRoute;
const updatedThisYear = lastUpdated?.getFullYear() === new Date().getFullYear();---
{updatedThisYear && ( <Default {...Astro.props}><slot /></Default> <Default><slot /></Default>)}Community Starlight plugins may also need to be manually updated to work with Starlight 0.32. If you encounter any issues, please reach out to the plugin author to see if it is a known issue or if an updated version is being worked on.
#2578 f895f75 Thanks @HiDeoo! - Deprecates the Starlight plugin setup hook in favor of the new config:setup hook which provides the same functionality.
⚠️ BREAKING CHANGE:
The Starlight plugin setup hook is now deprecated and will be removed in a future release. Please update your plugins to use the new config:setup hook instead.
export default { name: 'plugin-with-translations', hooks: { 'setup'({ config }) { 'config:setup'({ config }) { // Your plugin configuration setup code }, },};#2578 f895f75 Thanks @HiDeoo! - Exposes the built-in localization system in the Starlight plugin config:setup hook.
⚠️ BREAKING CHANGE:
This addition changes how Starlight plugins add or update translation strings used in Starlight’s localization APIs.
Plugins previously using the injectTranslations() callback function from the plugin config:setup hook should now use the same function available in the i18n:setup hook.
export default { name: 'plugin-with-translations', hooks: { 'config:setup'({ injectTranslations }) { 'i18n:setup'({ injectTranslations }) { injectTranslations({ en: { 'myPlugin.doThing': 'Do the thing', }, fr: { 'myPlugin.doThing': 'Faire le truc', }, }); }, },};#2858 2df9d05 Thanks @XREvo! - Adds support for Pagefind’s multisite search features
#2578 f895f75 Thanks @HiDeoo! - Adds a new HookParameters utility type to get the type of a plugin hook’s arguments.
#2578 f895f75 Thanks @HiDeoo! - Adds a new useTranslations() callback function to the Starlight plugin config:setup hook to generate a utility function to access UI strings for a given language.
#2578 f895f75 Thanks @HiDeoo! - Adds a new absolutePathToLang() callback function to the Starlight plugin config:setup to get the language for a given absolute file path.
ed6f9fd Thanks @HiDeoo! - Exposes the StarlightIcon TypeScript type referencing the names of Starlight’s built-in icons.
#2777 88f4214 Thanks @hippotastic! - Updates astro-expressive-code dependency to the latest version (0.40).
This includes an update to the latest Shiki version (1.26.1), providing access to all current Shiki themes and syntax highlighting languages, and adding the config options shiki.engine, shiki.bundledLangs, shiki.langAlias and removeUnusedThemes. It also adds new style variants to the optional collapsible sections plugin.
See the Expressive Code release notes for full details.
#2736 29a885b Thanks @delucis! - ⚠️ BREAKING CHANGE: The minimum supported version of Astro is now 5.1.5
Please update Astro and Starlight together:
npx @astrojs/upgrade#2728 e187383 Thanks @delucis! - Updates minimum Pagefind dependency to v1.3.0, sets new defaults for Pagefind’s ranking options, and adds support for manually configuring the ranking options
The new ranking option defaults have been evaluated against Starlight’s own docs to improve the quality of search results. See “Customize Pagefind’s result ranking” for more details about how they work.
#157 23bf960 Thanks @tony-sull! - Adds a print stylesheet to improve the appearance of Starlight docs pages when printed
#2728 e187383 Thanks @delucis! - Fixes Pagefind logging to respect the Astro log level. When using Astro’s --verbose or --silent CLI flags, these are now respected by Pagefind as well.
#2792 412effb Thanks @dhruvkb! - Uses semantic var(--sl-color-hairline) for the page sidebar border instead of var(--sl-color-gray-6). This is visually the same as previously but makes it easier to override the hairline color consistently across a site.
#2736 29a885b Thanks @delucis! - Updates internal dependencies @astrojs/sitemap and @astrojs/mdx to the latest versions
#2782 d9d415b Thanks @delucis! - Fixes a documentation link in the JSDoc comment for the StarlightExpressiveCodeOptions type
#2708 442c819 Thanks @delucis! - Fixes colour contrast correction in code blocks
#2747 474c27e Thanks @bbag! - Ensures <Tab> component toggling is stable when smooth scrolling is enabled via custom CSS
#2740 0e169c9 Thanks @HiDeoo! - Fixes an issue preventing Pagefind to be disabled using the pagefind frontmatter field.
#2732 a10b466 Thanks @Sidnioulz! - Adds Storybook, Confluence and Jira social icons
#2717 c5fcbb3 Thanks @delucis! - Fixes a list item spacing issue where line break elements (<br>) could receive a margin, breaking layout in Firefox
#2724 02d7ac6 Thanks @dionysuzx! - Adds social link support for Farcaster
#2635 ec4b851 Thanks @HiDeoo! - Fixes an issue where the language picker in multilingual sites could display the wrong language when navigating between pages with the browser back/forward buttons.
#2612 8d5a4e8 Thanks @HiDeoo! - Adds support for Astro v5, drops support for Astro v4.
⚠️ BREAKING CHANGE: Astro v4 is no longer supported. Make sure you update Astro and any other official integrations at the same time as updating Starlight:
npx @astrojs/upgradeCommunity Starlight plugins and Astro integrations may also need to be manually updated to work with Astro v5. If you encounter any issues, please reach out to the plugin or integration author to see if it is a known issue or if an updated version is being worked on.
⚠️ BREAKING CHANGE: Starlight’s internal content collections, which organize, validate, and render your content, have been updated to use Astro’s new Content Layer API and require configuration changes in your project.
Move the content config file. This file no longer lives within the src/content/config.ts folder and should now exist at src/content.config.ts.
Edit the collection definition(s). To update the docs collection, a loader is now required:
import { defineCollection } from "astro:content";import { docsLoader } from "@astrojs/starlight/loaders";import { docsSchema } from "@astrojs/starlight/schema";
export const collections = { docs: defineCollection({ schema: docsSchema() }), docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),};If you are using the i18n collection to provide translations for additional languages you support or override our default labels, you will need to update the collection definition in a similar way and remove the collection type which is no longer available:
import { defineCollection } from "astro:content";import { docsLoader, i18nLoader } from "@astrojs/starlight/loaders";import { docsSchema, i18nSchema } from "@astrojs/starlight/schema";
export const collections = { docs: defineCollection({ schema: docsSchema() }), docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), i18n: defineCollection({ type: 'data', schema: i18nSchema() }), i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),};Update other collections. To update any other collections you may have, follow the “Updating existing collections” section in the Astro 5 upgrade guide.
If you are unable to make any changes to your collections at this time, including Starlight’s default docs and i18n collections, you can enable the legacy.collections flag to upgrade to v5 without updating your collections. This legacy flag exists to provide temporary backwards compatibility, and will allow you to keep your collections in their current state until the legacy flag is no longer supported.
#2669 310df7d Thanks @aaronperezaguilera! - Adds Catalan UI translations
#2664 62ff007 Thanks @HiDeoo! - Publishes provenance containing verifiable data to link a package back to its source repository and the specific build instructions used to publish it.
#2670 0223b42 Thanks @aaronperezaguilera! - Adds Spanish UI translations for the Pagefind search modal
#2642 12750ae Thanks @dragomano! - Updates Russian UI translations
#2656 4d543be Thanks @HiDeoo! - Improves error message when an invalid configuration or no configuration is provided to the Starlight integration.
#2645 cf12beb Thanks @techfg! - Fixes support for favicon URLs that contain a search query and/or hash
#2650 38db4ec Thanks @raviqqe! - Moves @types/js-yaml package to non-dev dependencies
#2633 5adb720 Thanks @HiDeoo! - Fixes a VoiceOver issue with Safari where the content of a <script> element could be read before the sidebar content.
#2663 34755f9 Thanks @astrobot-houston! - Adds a new seti:vite icon for Vite configuration files in the <FileTree> component
#2611 6059d96 Thanks @HiDeoo! - Fixes a UI string type issue in projects with multiple data content collections.
#2606 10b15a7 Thanks @delucis! - Makes <CardGrid> more resilient to complex child content on smaller viewports
#2605 ec7ab4f Thanks @brianzelip! - Exposes SidebarPersister component in package exports for use in custom overrides
#2614 9a31980 Thanks @HiDeoo! - Fixes an issue with custom pages using the <StarlightPage /> component and a custom sidebar missing highlighting for the active page and navigation links.
#2613 a73780f Thanks @delucis! - Fixes support for sidebar frontmatter options in sidebar entries using slug or the string shorthand for internal links
#2551 154c8e3 Thanks @hippotastic! - Updates the astro-expressive-code dependency to the latest version (0.38).
The new version allows using ec.config.mjs to selectively override individual Expressive Code styles and settings provided by Starlight themes and plugins, speeds up Shiki language loading, and adds the config option expressiveCode.shiki.injectLangsIntoNestedCodeBlocks. See the Expressive Code release notes for full details.
#2252 6116db0 Thanks @HiDeoo! - Improves build performance for sites with large sidebars
This release adds a caching layer to Starlight’s sidebar generation logic, reducing the number of times sidebars need to be regenerated while building a site. Some benchmarks for projects with a complex sidebar saw builds complete more than 35% faster with this change.
#2503 a4c8edd Thanks @HiDeoo! - Improves the accessibility of asides and tabs by removing some unnecessary HTML landmarks.
241966b Thanks @RafidMuhymin! - Adds social link icon for Nostr#2546 bf42300 Thanks @HiDeoo! - Fixes an issue where i18n content collection related errors, e.g. malformed JSON or YAML, would not be reported.
#2548 07673c8 Thanks @HiDeoo! - Fixes a URL localization edge case. In projects without a root locale configured, slugs without a locale prefix did not fall back to the default locale as expected.
#2547 91e1dd7 Thanks @HiDeoo! - Fixes a Firefox Markdown content rendering issue for text sentences separated by a line break.
#2524 1b46783 Thanks @jsparkdev! - Fixes a broken link to Astro’s Docs in an error message
#2444 d585b3e Thanks @HiDeoo! - Fixes a UI string translation issue for languages with a region subtag.
#2518 0f69db8 Thanks @morinokami! - Updates Japanese UI translations
#2507 bd6ced5 Thanks @HiDeoo! - Fixes a table of contents highlighting issue after resizing the window.
#2444 d585b3e Thanks @HiDeoo! - Refactors various components to use the new built-in localization system to access translated UI strings.
#2408 0b4823d Thanks @HiDeoo! - Fixes a link formatting issue when using the Astro build.format option set to file with a base.
#2380 7b451cf Thanks @delucis! - Loosen Starlight’s i18n schema to pass through unknown keys
#2388 6bba3d8 Thanks @HiDeoo! - Fixes a potential type-checking issue in Starlight projects.
#2443 a0f40b3 Thanks @kevinzunigacuellar! - Fixes CSS issue where bottom padding is not applied in the search dialog.
#1923 5269aad Thanks @HiDeoo! - Overhauls the built-in localization system which is now powered by the i18next library and available to use anywhere in your documentation website.
See the “Using UI translations” guide to learn more about how to access built-in UI labels or your own custom strings in your project. Plugin authors can also use the new injectTranslations() helper to add or update translation strings.
⚠️ BREAKING CHANGE: The Astro.props.labels props has been removed from the props passed down to custom component overrides.
If you are relying on Astro.props.labels (for example to read a built-in UI label), you will need to update your code to use the new Astro.locals.t() helper instead.
---import type { Props } from '@astrojs/starlight/props';// The `search.label` UI label for this page’s language:const searchLabel = Astro.locals.t('search.label');---#2285 7286220 Thanks @HiDeoo! - Adds support for translating sidebar badges.
#1923 5269aad Thanks @HiDeoo! - ⚠️ BREAKING CHANGE: The minimum supported version of Astro is now 4.14.0
Please update Astro and Starlight together:
npx @astrojs/upgrade
#1255 6f3202b Thanks @Fryuni! - Adds support for server-rendered Starlight pages.
When building a project with hybrid or server output mode, a new prerender option on Starlight config can be set to false to make all Starlight pages be rendered on-demand:
export default defineConfig({ output: 'server', integrations: [ starlight({ prerender: false, }), ],});#2242 756e85e Thanks @delucis! - Refactors the logic for persisting and restoring sidebar state across navigations for better performance on slow or busy devices
#1255 6f3202b Thanks @Fryuni! - Improves performance of computing the last updated times from Git history.
Instead of executing git for each docs page, it is now executed twice regardless of the number of pages.
#1255 6f3202b Thanks @Fryuni! - Fixes last updated times on projects with custom srcDir
#2281 5062d30 Thanks @HiDeoo! - Fixes a potential text rendering issue that could include extra whitespaces for text containing colons.
#2279 62d59e2 Thanks @HiDeoo! - Fixes an issue with frontmatter schemas containing collection references used with the <StarlightPage /> component and an Astro version greater than 4.14.0.
#2273 746e0cd Thanks @delucis! - Fixes type error when using Starlight with Astro v4.15
#2265 25b661e Thanks @SeraphicRav! - Adds TikTok social icon
#2250 c0a6166 Thanks @HiDeoo! - Removes internal E2E tests from the package published to the npm registry.
#2253 72bc76a Thanks @HiDeoo! - Fixes an issue preventing to use the class attribute in hero action link buttons.
#1784 68f56a7 Thanks @HiDeoo! - Adds <LinkButton> component for visually distinct and emphasized call to action links
#2150 9368494 Thanks @delucis! - Adds state persistence across page navigations to the main site sidebar
#2087 caa84ea Thanks @HiDeoo! - Adds persistence to synced <Tabs> so that a user’s choices are reflected across page navigations.
#2051 ec3b579 Thanks @HiDeoo! - Adds a guideline to the last step of the <Steps> component.
If you want to preserve the previous behaviour and hide the guideline on final steps, you can add the following custom CSS to your site:
/* Hide the guideline for the final step in <Steps> lists. */.sl-steps > li:last-of-type::after { background: transparent;}#1784 68f56a7 Thanks @HiDeoo! - Changes the hero component action button default variant from minimal to primary.
⚠️ BREAKING CHANGE: If you want to preserve the previous appearance, hero component action buttons previously declared without a variant will need to be updated to include the variant property with the value minimal.
hero: actions: - text: View on GitHub link: https://github.com/astronaut/my-project icon: external variant: minimal#2168 e044fee Thanks @HiDeoo! - ⚠️ BREAKING CHANGE: Updates the <StarlightPage /> component sidebar prop to accept an array of SidebarItems like the main Starlight sidebar configuration in astro.config.mjs.
This change simplifies the definition of sidebar items in the <StarlightPage /> component, allows for shared sidebar configuration between the global sidebar option and <StarlightPage /> component, and also enables the usage of autogenerated sidebar groups with the <StarlightPage /> component.
If you are using the <StarlightPage /> component with a custom sidebar configuration, you will need to update the sidebar prop to an array of SidebarItem objects.
For example, the following custom page with a custom sidebar configuration defines a “Resources” group with a “New” badge, a link to the “Showcase” page which is part of the docs content collection, and a link to the Starlight website:
<StarlightPage frontmatter={{ title: 'My custom page' }} sidebar={[ { type: 'group', label: 'Resources', badge: { text: 'New' }, items: [ { type: 'link', label: 'Showcase', href: '/showcase/' }, { type: 'link', label: 'Starlight', href: 'https://starlight.astro.build/', }, ], }, ]}> <p>This is a custom page with a custom component.</p></StarlightPage>This configuration will now need to be updated to the following:
<StarlightPage frontmatter={{ title: 'My custom page' }} sidebar={[ { label: 'Resources', badge: { text: 'New' }, items: [ 'showcase', { label: 'Starlight', link: 'https://starlight.astro.build/' }, ], }, ]}> <p>This is a custom page with a custom component.</p></StarlightPage>See the “Sidebar Navigation” guide to learn more about the available options for customizing the sidebar.
#2155 8bed886 Thanks @delucis! - Improves page load performance on slower devices
#2167 9ac7725 Thanks @delucis! - Fixes an issue detecting the built-in locale when running Starlight in a web container environment on Firefox
#2166 4f12049 Thanks @delucis! - Updates @astrojs/mdx, @astrojs/sitemap, astro-expressive-code, unified, and vfile dependencies to the latest version
#2154 0b381d5 Thanks @mktbsh! - Updates <head> logic to deduplicate <link rel="canonical"> tags. This means that custom canonicals set via frontmatter now override the default canonical generated by Starlight.
#2157 6757d97 Thanks @astrobot-houston! - Updates file tree icon mapping to correctly map .cjs and .mjs extensions in several contexts
#2156 904ad47 Thanks @delucis! - Fixes builds for projects with a space in their pathname
#2137 703903b Thanks @cevdetardaharan! - Removes twitter:title and twitter:description meta tags from <head>
#2126 ada51ee Thanks @essential-randomness! - Adds support for markdown formatting in aside titles
#2135 9bbb969 Thanks @oluwatobiss! - Adds Pinterest social icon
#2122 359a642 Thanks @HiDeoo! - Fixes an i18n configuration issue for multilingual sites when using Astro’s i18n config with prefixDefaultLocale set to false.
#2107 61e223b Thanks @sanabel-al-firdaws! - Updates Arabic UI translations
#2105 81f8a2c Thanks @delucis! - Fixes an edge case in custom pagination link processing
Custom link values for prev/next in page frontmatter are now always used as authored.
Previously this was not the case in some edge cases such as for the first and final pages in the sidebar.
#2119 464685a Thanks @evadecker! - Improves styling of <hr>, <blockquote>, and <code> within asides
#2025 47f32c1 Thanks @HiDeoo! - Removes the / search shortcut for accessibility reasons.
⚠️ Potentially breaking change: The search.shortcutLabel UI string has been removed. If you were using this string in your custom UI, you will need to update your code.
#2064 c5b47cb Thanks @SnowDingo! - Improves styling of Markdown tables to work better in different contexts, including against different background colours like when used in asides.
#2031 2bab648 Thanks @delucis! - Makes sidebar entry parsing stricter in Starlight config
⚠️ Potentially breaking change: Previously Starlight would accept a sidebar entry that matched one of its expected shapes, even if it included additional properties. For example, including both link and items was considered valid, with items being ignored. Now, it is an error to include more than one of link, items, or autogenerate in a sidebar entry.
If you see errors after updating, look for sidebar entries in the Starlight configuration in astro.config.mjs that include too many keys and remove the one that was previously ignored.
#1874 eeba06e Thanks @lorenzolewis! - Adds a new syntax for specifying sidebar link items for internal links
You can now specify an internal page using only its slug, either as a string, or as an object with a slug property:
starlight({ title: 'Docs with easier sidebars', sidebar: ['getting-started', { slug: 'guides/installation' }],});Starlight will use the linked page’s frontmatter to configure the sidebar link.
f0181d2 Thanks @andrii-bodnar! - Updates the Ukrainian UI translations#2062 5ac0ac6 Thanks @evadecker! - Increase theme and language select inline padding
#2056 87e9ad0 Thanks @HiDeoo! - Fixes an issue preventing remark plugins injected by Starlight plugins to handle Markdown text and leaf directives.
#2063 3ee1a94 Thanks @delucis! - Translate fileTree.directory and aside.* UI string into Norwegian (Bokmål).
#2054 dbfd3ee Thanks @HiDeoo! - Fixes an issue when using the <StarlightPage> component in a custom page with a user-defined srcDir configuration.
#2038 87f3f92 Thanks @dragomano! - Updates Russian UI translations
#2043 53f4cd4 Thanks @playmr365! - Updates Czech UI translations
#2041 8af5a60 Thanks @HiDeoo! - Fixes <Steps> numbering bug caused by Chrome v126 CSS counter rewrite
#2008 40359c7 Thanks @vnepogodin! - Add Slovak language UI translation.
#2004 0aa2f06 Thanks @liruifengv! - Removes an outdated export in package.json
#2007 44ca490 Thanks @delucis! - Updates internal dependencies
#1993 60165b2 Thanks @HiDeoo! - Fixes an i18n configuration issue when using a single root locale.
#1978 a5ab8cd6 Thanks @kylewlacy! - Add new social icon for Zulip
#1962 2ef19a94 Thanks @torn4dom4n! - Updates Vietnamese UI translations
#1976 5a61f73c Thanks @jsparkdev! - Updates Korean UI translations
#1987 0b8a8439 Thanks @HiDeoo! - Fixes issues with the locale text direction detection mechanism in some environments like WebContainers or Bun.
#1841 ee0cd38a Thanks @HiDeoo! - Adds support for Astro.currentLocale and Astro’s i18n routing.
⚠️ Potentially breaking change: Starlight now configures Astro’s i18n option for you based on its locales config.
If you are currently using Astro’s i18n option as well as Starlight’s locales option, you will need to remove one of these.
In general we recommend using Starlight’s locales, but if you have a more advanced configuration you may choose to keep Astro’s i18n config instead.
#1958 081d1a96 Thanks @delucis! - Allows users to opt into displaying a “Built with Starlight” link in the site footer
#1530 dd64836a Thanks @kevinzunigacuellar! - Adds a new <Badge> component
#1846 2de67039 Thanks @delucis! - Updates @astrojs/mdx to v3 and enables MDX optimization by default
⚠️ Potentially breaking change: MDX optimization speeds up builds (Starlight’s docs are building ~40% faster for example), but restricts some advanced MDX features. See full details in the MDX optimization documentation.
Most Starlight users should be unaffected, but if you are using MDX files outside of Starlight pages with the components prop, you may see issues. You can disable optimization by adding MDX manually to your integrations array in astro.config.mjs:
import { defineConfig } from 'astro/config'; import mdx from '@astrojs/mdx';import starlight from '@astrojs/starlight';
// https://astro.build/configexport default defineConfig({ integrations: [ starlight({ title: 'My docs', // ... }), mdx(), ],});#1735 1a9ab50d Thanks @HiDeoo! - Adds custom styles for <details> and <summary> elements in Markdown content.
#1846 2de67039 Thanks @delucis! - ⚠️ BREAKING CHANGE: The minimum supported version of Astro is now 4.8.6
Please update Astro and Starlight together:
npx @astrojs/upgrade#1871 03bb126b Thanks @delucis! - Adds a blueSky icon and social link option
#1873 13f33b81 Thanks @ekfuhrmann! - Adds 1 new icon: alpine
#1857 32cdfaf0 Thanks @tarikcoskun! - Updates Turkish UI translations
#1736 cfa94a34 Thanks @julien-deramond! - Prevent list items from overflowing Markdown content
#1838 9fe84754 Thanks @delucis! - Adds extra information to the errors thrown by the <Steps> component to help locate misformatted code
#1863 50be60bb Thanks @torn4dom4n! - Update Vietnamese translation
#1837 a33a1223 Thanks @delucis! - Adds three new icons: comment, comment-alt, heart
#1842 c7838636 Thanks @delucis! - Moves the href used in the site title link to Starlight’s route data object. This makes it possible for overrides to change the title link while reusing Starlight’s default component implemenation.
#1840 cb85563c Thanks @MiahaCybersec! - Adds 1 new icon: hackerone
#640 7dc503ea Thanks @HiDeoo! - Adds support for syncing multiple sets of tabs on the same page.
#1620 ca0678ca Thanks @emjio! - Adds support for translating the site title
⚠️ Potentially breaking change: The shape of the title field on Starlight’s internal config object has changed. This used to be a string, but is now an object.
If you are relying on config.title (for example in a custom <SiteTitle> or <Head> component), you will need to update your code. We recommend using the new siteTitle prop available to component overrides:
---import type { Props } from '@astrojs/starlight/props';
// The site title for this page’s language:const { siteTitle } = Astro.props;---#1613 61493e55 Thanks @HiDeoo! - Adds new draft frontmatter option to exclude a page from production builds.
#640 7dc503ea Thanks @HiDeoo! - Updates the default line-height from 1.8 to 1.75. This change avoids having a line height with a fractional part which can cause scripts accessing dimensions involving the line height to get an inconsistent rounded value in various browsers.
If you want to preserve the previous line-height, you can add the following custom CSS to your site:
:root { --sl-line-height: 1.8;}#1720 749ddf85 Thanks @jacobdalamb! - Updates astro-expressive-code dependency to the latest minor release (0.35) and exposes a new @astrojs/starlight/expressive-code/hast module for users who need to use Expressive Code’s version of hast.
This includes a potentially breaking change if you use custom Expressive Code plugins. See the Expressive Code release notes for full details.
#1769 bd5f1cbd Thanks @ncjones! - Adds support for accessing frontmatter data as a variable when using Markdoc
#1788 681a4273 Thanks @dragomano! - Adds Russian translations for Expressive Code labels
#1780 4db6025a Thanks @MiahaCybersec! - Adds 1 new icon: signal
#1785 65009c9c Thanks @dreyfus92! - Adds 5 new icons: node, cloudflare, vercel, netlify and deno
#1786 d05d693a Thanks @delucis! - Fixes type inference for i18n strings added by extending the default schema
#1777 6949404b Thanks @HiDeoo! - Fixes an issue where TypeScript could fail to serialize the frontmatter schema when configured to emit declaration files
#1734 4493dcfa Thanks @delucis! - Refactors <ThemeSelect> custom element logic to improve performance
#1731 f08b0dff Thanks @techfg! - Fixes responding to system color scheme changes when theme is auto
#1793 2616f0c7 Thanks @Mrahmani71! - Updates the Farsi UI translations
#1709 c5cd1811 Thanks @HiDeoo! - Fixes a UI strings translation issue for sites configured with a single non-root language different from English.
#1723 3b29b3ab Thanks @OliverSpeir! - Fixes accessibility by using aria-selected="false" for inactive tabs instead of removing aria-selected="true" in the tablist of Starlight’s <Tabs> component
#1706 f171ac4d Thanks @jorenbroekema! - Fixes some minor type errors
#1622 3a074bad Thanks @SamuelLHuber! - Adds 1 new icon: farcaster
#1616 a86f9b71 Thanks @dragomano! - Updates Russian UI strings
#1698 67b892fd Thanks @liruifengv! - Adds 1 new icon: starlight
#1687 6fa9ea7e Thanks @mingjunlu! - Translates fileTree.directory UI string into Traditional Chinese.
#1614 78fc9042 Thanks @kpodurgiel! - Adds Polish UI translations
#1596 13ed30cd Thanks @HiDeoo! - Adds support for toggling the built-in search modal using the Ctrl+k keyboard shortcut.
#1608 4096e1b7 Thanks @HiDeoo! - Removes nested CSS from the <FileTree> component to prevent a potential warning when using Tailwind CSS.
#1626 67459cb4 Thanks @hippotastic! - Fixes a bundling issue that caused imports from @astrojs/starlight/components to fail when using the config setting expressiveCode: false.
#1584 8851d5cd Thanks @HiDeoo! - Adds 2 new icons: apple and linux.
#1577 0ba77890 Thanks @morinokami! - Translates fileTree.directory UI string into Japanese.
#1593 fa7ed245 Thanks @liruifengv! - Translates fileTree.directory UI string into simplified Chinese.
#1585 bd4e278f Thanks @HiDeoo! - Translates fileTree.directory UI string into French.
#1587 c5794260 Thanks @Eveeifyeve! - Adds 1 new icon: homebrew.
#1568 5f99a71d Thanks @HiDeoo! - Adds support for optionally setting an icon on a <TabItem> component to make it easier to visually distinguish between tabs.
#1308 9a918a5b Thanks @HiDeoo! - Adds <FileTree> component to display the structure of a directory.
#1308 9a918a5b Thanks @HiDeoo! - Adds 144 new file-type icons from the Seti UI icon set, available with the seti: prefix, e.g. seti:javascript.
#1564 d880065e Thanks @delucis! - Adds a <Steps> component for styling more complex guided tasks.
#1308 9a918a5b Thanks @HiDeoo! - Adds 5 new icons: astro, biome, bun, mdx, and pnpm.
8e091147 Thanks @hippotastic! - Updates Expressive Code to v0.33.4 to fix potential race condition bug in Shiki.
#1541 1043052f Thanks @hippotastic! - Updates astro-expressive-code dependency to the latest minor release (0.33).
This unlocks support for word wrap and line numbers, as well as updating the syntax highlighter to the latest Shiki release, which includes new and updated language grammars.
See the Expressive Code release notes for more information including details of potentially breaking changes.
#1527 163bc84 Thanks @HiDeoo! - Exports the StarlightPageProps TypeScript type representing the props expected by the <StarlightPage /> component.
#1504 fc83a05 Thanks @mingjunlu! - Adds Traditional Chinese UI translations
#1534 aada680 Thanks @delucis! - Improves DX of the sidebar prop used by the new <StarlightPage> component.
#1485 2cb3578 Thanks @timokoessler! - Add support for setting html attributes of hero action links
#1175 dd11b95 Thanks @HiDeoo! - Adds a new <StarlightPage> component to use the Starlight layout in custom pages.
To learn more about this new feature, check out the new “Using Starlight’s design in custom pages” guide.
#1499 97bf523 Thanks @delucis! - Adds a new <Aside> component
The new component is in addition to the existing custom Markdown syntax.
#1454 1d9ef56 Thanks @Fryuni! - Makes Starlight compatible with on-demand server rendering (sometimes referred to as server-side rendering or SSR).
Starlight pages are always prerendered, even when using output: 'server'.
#1454 1d9ef56 Thanks @Fryuni! - Enables Astro’s experimental.globalRoutePriority option and bumps the minimum required Astro version.
⚠️ BREAKING CHANGE The minimum supported Astro version is now 4.2.7. Upgrade Astro and Starlight together:
npx @astrojs/upgrade#1461 2e17880 Thanks @liruifengv! - Improves the table of contents title translation in Simplified Chinese
#1462 4741ccc Thanks @delucis! - Fixes overflow of very long site titles on narrow viewports
#1459 9a8e0ec Thanks @delucis! - Fixes a bug where table of contents highlighting could break given very specific combinations of content and viewport size
#1458 8c88642 Thanks @delucis! - Silences i18n content collection warnings for projects without custom translations.
#1437 655aed4 Thanks @hippotastic! - Adds Starlight-specific types to defineEcConfig function and exports StarlightExpressiveCodeOptions.
This provides Starlight types and IntelliSense support for your Expressive Code configuration options inside an ec.config.mjs file. See the Expressive Code documentation for more information.
#1420 275f87f Thanks @abdelhalimjean! - Fix rare font-family issue if users have a font installed with a name of ""
#1365 a0af7cc Thanks @kevinzunigacuellar! - Correctly format Pagefind search result links when trailingSlash: 'never' is used
#1389 21b3620 Thanks @connor-baer! - Adds new disable404Route config option to disable injection of Astro’s default 404 route
#1395 ce05dfb Thanks @hippotastic! - Adds a new <Code> component to render dynamic code strings with Expressive Code
#1383 490c6ef Thanks @delucis! - Refactors Starlight’s internal virtual module system for components to avoid circular references
This is a change to an internal API.
If you were importing the internal virtual:starlight/components module, this no longer exists.
Update your imports to use the individual virtual modules now available for each component, for example virtual:starlight/components/EditLink.
#1151 134292d Thanks @kevinzunigacuellar! - Fixes sidebar auto-generation issue when a file and a directory, located at the same level, have identical names.
For example, src/content/docs/guides.md and src/content/docs/guides/example.md will now both be included and src/content/docs/guides.md is treated in the same way a src/content/docs/guides/index.md file would be.
#1386 0163634 Thanks @delucis! - Tightens line-height on <LinkCard> titles to fix regression from original design
If you want to preserve the previous line-height, you can add the following custom CSS to your site:
.sl-link-card a { line-height: 1.6;}#1376 8398432 Thanks @delucis! - Tweaks vertical spacing in Markdown content styles.
This is a subtle change to Starlight’s default content styling that should improve most sites:
1.5rem to 1rem.The overall impact is to tighten up content that belongs together and improve the visual hierarchy of headings to break up sections.
Although this is a subtle change, we recommend visually inspecting your site in case this impacts layout of any custom CSS or components.
If you want to preserve the previous spacing, you can add the following custom CSS to your site:
/* Restore vertical spacing to match Starlight v0.15 and below. */.sl-markdown-content :not(a, strong, em, del, span, input, code) + :not(a, strong, em, del, span, input, code, :where(.not-content *)) { margin-top: 1.5rem;}.sl-markdown-content :not(h1, h2, h3, h4, h5, h6) + :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *)) { margin-top: 2.5rem;}#1372 773880d Thanks @HiDeoo! - Updates the table of contents highlighting styles to prevent UI shifts when scrolling through a page.
If you want to preserve the previous, buggy styling, you can add the following custom CSS to your site:
starlight-toc a[aria-current='true'],starlight-toc a[aria-current='true']:hover,starlight-toc a[aria-current='true']:focus { font-weight: 600; color: var(--sl-color-text-invert); background-color: var(--sl-color-text-accent);}#1303 3eefd21 Thanks @lilnasy! - chore: fix type errors in Starlight internals
#1351 932c022 Thanks @roberto-butti! - Adds Italian translation for search.devWarning UI
#1298 c7e995c Thanks @kevinzunigacuellar! - Fixes incorrect sorting behavior for some autogenerated sidebars
#1347 8994d00 Thanks @kevinzunigacuellar! - Refactor getLastUpdated to use node:child_process instead of execa.
#1353 90fe8da Thanks @delucis! - Fixes sidebar scrollbar hiding behind navbar
#1273 ae53155 Thanks @natemoo-re! - Updates <SocialIcon /> styling for improved accessibility. Specifically, the component now meets the Target Size (Minimum) success criteria defined by Web Content Accessibility Guidelines (WCAG) 2.2.
#1289 9bd343f Thanks @HiDeoo! - Adds French translations for Expressive Code UI
#1280 6b1693d Thanks @kevinzunigacuellar! - Adds Spanish translations for Expressive Code UI
#1276 667f23d Thanks @hippotastic! - Updates astro-expressive-code dependency to the latest version
#1266 c9edf30 Thanks @alex-way! - Removes redundant subprocess calls in git last-updated time utility to improve performance
#1278 e88abb0 Thanks @HiDeoo! - Exports the StarlightUserConfig TypeScript type representing the user’s Starlight configuration received by plugins.
#1238 02a808e Thanks @delucis! - Add support for Astro v4, drop support for Astro v3
⚠️ BREAKING CHANGE Astro v3 is no longer supported. Make sure you update Astro and any other integrations at the same time as updating Starlight.
Use the new @astrojs/upgrade command to upgrade Astro and Starlight together:
npx @astrojs/upgrade#1242 d8fc9e1 Thanks @delucis! - Enables link prefetching on hover by default
Astro v4’s prefetch support is now enabled by default. If prefetch is not set in astro.config.mjs, Starlight will use prefetch: { prefetchAll: true, defaultStrategy: 'hover' } by default.
If you want to preserve previous behaviour, disable link prefetching in astro.config.mjs:
import { defineConfig } from 'astro/config';import starlight from '@astrojs/starlight';
export default defineConfig({ // Disable link prefetching: prefetch: false,
integrations: [ starlight({ // ... }), ],});
#1144 7c0b8cb Thanks @delucis! - Adds a configuration option to disable site indexing with Pagefind and the default search UI
#942 efd7fdc Thanks @HiDeoo! - Adds plugin API
See the plugins reference to learn more about creating plugins for Starlight using this new API.
#1135 e5a863a Thanks @delucis! - Exposes localized UI strings in route data
Component overrides can now access a labels object in their props which includes all the localized UI strings for the current page.
#1162 00d101b Thanks @delucis! - Adds support for extending Starlight’s content collection schemas
#1023 a3b80f7 Thanks @kevinzunigacuellar! - Respect the trailingSlash and build.format Astro options when creating Starlight navigation links.
⚠️ Potentially breaking change: This change will cause small changes in link formatting for most sites. These are unlikely to break anything, but if you care about link formatting, you may want to change some Astro settings.
If you want to preserve Starlight’s previous behavior, set trailingSlash: 'always' in your astro.config.mjs:
import { defineConfig } from 'astro/config';import starlight from '@astrojs/starlight';
export default defineConfig({ trailingSlash: 'always', integrations: [ starlight({ // ... }), ],});#742 c6a4bcb Thanks @hippotastic! - Adds Expressive Code as Starlight’s default code block renderer
⚠️ Potentially breaking change:
This addition changes how Markdown code blocks are rendered. By default, Starlight will now use Expressive Code.
If you were already customizing how code blocks are rendered and don’t want to use the features provided by Expressive Code, you can preserve the previous behavior by setting the new config option expressiveCode to false.
If you had previously added Expressive Code manually to your Starlight project, you can now remove the manual set-up in astro.config.mjs:
expressiveCode option.astro-expressive-code integration.For example:
import starlight from '@astrojs/starlight';import { defineConfig } from 'astro/config'; import expressiveCode from 'astro-expressive-code';
export default defineConfig({ integrations: [ expressiveCode({ themes: ['rose-pine'], }), starlight({ title: 'My docs', expressiveCode: { themes: ['rose-pine'], }, }), ],});Note that the built-in Starlight version of Expressive Code sets some opinionated defaults that are different from the astro-expressive-code defaults. You may need to set some styleOverrides if you wish to keep styles exactly the same.
#517 5b549cb Thanks @liruifengv! - Add i18n support for default aside labels
#1088 4fe5537 Thanks @Lootjs! - i18n(ru): added Russian aside labels translation
#1083 e03a653 Thanks @at-the-vr! - i18n(hi): Add Hindi language support
#1075 2f2adf2 Thanks @russbiggs! - Add Slack social link icon
#1065 2d72ed6 Thanks @HiDeoo! - Ignore search keyboard shortcuts for elements with contents that are editable
#1081 f27f781 Thanks @farisphp! - i18n(id): Add Indonesian aside labels translation
#1082 ce27486 Thanks @bogdaaamn! - i18n(ro): Add Romanian UI translations
#1069 b86f360 Thanks @Genteure! - Fix sidebar highlighting and navigation buttons for pages with path containing non-ASCII characters
#1025 0d1e75e Thanks @HiDeoo! - Internal: fix import issue in translation string loading mechanism
#1044 a5a9754 Thanks @HiDeoo! - Fix last updated dates for pages displaying fallback content
#1049 c27495d Thanks @HiDeoo! - Expose Markdown content styles in @astrojs/starlight/style/markdown.css
#995 5bf4457 Thanks @kevinzunigacuellar! - Adds support for adding sidebar badges to group headings
#988 977fe13 Thanks @magicDGS! - Include social icon links in mobile menu
#280 72cca2d Thanks @cbontems! - Support light & dark variants of the hero image.
⚠️ Potentially breaking change: The hero.image schema is now slightly stricter than previously.
The hero.image.html property can no longer be used alongside the hero.image.alt or hero.image.file properties.
Previously, html was ignored when used with file and alt was ignored when used with html.
Now, those combinations will throw errors.
If you encounter errors, remove the image.hero property that is not in use.
#944 7a6446e Thanks @HiDeoo! - Fix issue with sidebar autogenerated groups configured with a directory containing leading or trailing slash
#985 92b3b57 Thanks @delucis! - Fix edit URLs for pages displaying fallback content
#986 0470734 Thanks @dreyfus92! - Prevent overscrolling on mobile table of contents by setting ‘overscroll-behavior: contain’.
#924 39d6302 Thanks @kevinzunigacuellar! - Remove extra margin from markdown lists that uses inline code
#814 1e517d9 Thanks @julien-deramond! - Prevent text from overflowing pagination items
#892 2b30321 Thanks @delucis! - Add Patreon social link icon
#852 344c92e Thanks @Lootjs! - Improve Russian language support
#891 395920c Thanks @Frikadellios! - Add Ukrainian language support
#890 63ea8e8 Thanks @delucis! - Update execa dependency to v8
#859 eaa7a90 Thanks @oggnimodd! - Improve Indonesian language support
#774 903a579 Thanks @HiDeoo! - Support adding HTML attributes to sidebar links from config and frontmatter
#796 372ec96 Thanks @HiDeoo! - Add the @astrojs/sitemap and @astrojs/mdx integrations only if they are not detected in the Astro configuration.
⚠️ BREAKING CHANGE The minimum supported version of Astro is now v3.2.0. Make sure you update Astro at the same time as updating Starlight:
npm install astro@latest#447 b45719b Thanks @andremralves! - Add titleDelimiter configuration option and include site title in page <title> tags
⚠️ BREAKING CHANGE — Previously, every page’s <title> only included its individual frontmatter title.
Now, <title> tags include the page title, a delimiter character (| by default), and the site title.
For example, in the Startlight docs, <title>Configuration Reference</title> is now <title>Configuration Reference | Starlight</title>.
If you have a page where you need to override this new behaviour, set a custom title using the head frontmatter property:
---title: My Pagehead: - tag: title content: Custom Title---#709 140e729 Thanks @delucis! - Add support for overriding Starlight’s built-in components
⚠️ BREAKING CHANGE — The page footer is now included on pages with template: splash in their frontmatter. Previously, this was not the case. If you are using template: splash and want to continue to hide footer elements, disable them in your frontmatter:
---title: Landing pagetemplate: splash# Disable unwanted footer elements as needededitUrl: falselastUpdated: falseprev: falsenext: false---⚠️ BREAKING CHANGE — This change involved refactoring the structure of some of Starlight’s built-in components slightly. If you were previously overriding these using other techniques, you may need to adjust your code.
#810 dbe977b Thanks @hasham-qaiser! - Use <span> instead of <h2> in sidebar group headings
#807 7c73dd1 Thanks @torn4dom4n! - Add Vietnamese translations for Starlight UI
#756 f55a8f0 Thanks @julien-deramond! - Prevent text from overflowing in several cases
#783 f94727e Thanks @kevinzunigacuellar! - Fix GitHub edit link to include src path from project config
#781 a293ef9 Thanks @dreyfus92! - Removed role from Banner component to avoid duplication in header.
#745 006d606 Thanks @TheOtterlord! - Prevent Starlight crashing when the content folder doesn’t exist, or is empty
#775 2ef3036 Thanks @delucis! - Fix content collection schema compatibility with Astro 3.1 and higher
#773 423d575 Thanks @tlandmangh! - Fix Dutch UI translation for “Previous page” links
#647 ea57726 Thanks @bgmort! - Fix translated 404 pages not being excluded from search results
#667 9828f73 Thanks @delucis! - Break inline <code> across lines to avoid overflow
#642 e623d92 Thanks @fk! - Don’t hard-code nav height in table of contents highlighting script
#676 6419006 Thanks @vedmalex! - Upgrade and pin Pagefind to latest beta release.
#647 ea57726 Thanks @bgmort! - Add frontmatter option to exclude a page from Pagefind search results
#626 5dd22b8 Thanks @delucis! - Throw an error for duplicate MDX or sitemap integrations
#615 7b75b3e Thanks @delucis! - Bump minimum required Astro version to 3.0
⚠️ BREAKING CHANGE Astro v2 is no longer supported. Make sure you update Astro and any other integrations at the same time as updating Starlight.
1b367e3 Thanks @KubaJastrz! - Avoid applying hovered <select> text color to its <options>
#529 c2d0e7f Thanks @delucis! - For improved compatibility with Tailwind, some Starlight built-in class names are now prefixed with "sl-".
While not likely, if you were relying on one of these internal class names in your own components or custom CSS, you will need to update to use the prefixed version.
flex, md:flex, lg:flex, block, md:block, lg:block, hidden, md:hidden, lg:hidden.sl-flex, md:sl-flex, lg:sl-flex, sl-block, md:sl-block, lg:sl-block, sl-hidden, md:sl-hidden, lg:sl-hidden.#593 5b8af95 Thanks @delucis! - Add announcement banner feature
#516 70a32a1 Thanks @kevinzunigacuellar! - Support adding badges to sidebar links from config file and frontmatter
#525 87caf21 Thanks @delucis! - Improve inline code and code block support in RTL languages
#537 56c19bc Thanks @carlgleisner! - Add Swedish UI translations.
#528 f5e5503 Thanks @jsparkdev! - add Korean language support
#506 5e3133c Thanks @HiDeoo! - Improve table of content current item highlight behavior
#499 fcff49e Thanks @D3vil0p3r! - Add icons for Instagram
#502 3c87a16 Thanks @Mrahmani71! - Add Farsi UI translations
#496 cd28392 Thanks @lorenzolewis! - Fix lastUpdated date position to be consistent
#402 d8669b8 Thanks @chopfitzroy! - Fix content sometimes appearing above the mobile table of contents.
#441 0119a49 Thanks @lorenzolewis! - Add support for hiding entries from an autogenerated sidebar:
---title: About this projectsidebar: hidden: true---#470 d076aec Thanks @delucis! - Drop support for the --sl-hue-accent CSS custom property.
⚠️ BREAKING CHANGE — In previous Starlight versions you could control the accent color by setting the --sl-hue-accent custom property. This could result in inaccessible color contrast and unpredictable results.
You must now set accent colors directly. If you relied on setting --sl-hue-accent, migrate by setting light and dark mode colors in your custom CSS:
:root { --sl-hue-accent: 234; --sl-color-accent-low: hsl(var(--sl-hue-accent), 54%, 20%); --sl-color-accent: hsl(var(--sl-hue-accent), 100%, 60%); --sl-color-accent-high: hsl(var(--sl-hue-accent), 100%, 87%);}
:root[data-theme='light'] { --sl-color-accent-high: hsl(var(--sl-hue-accent), 80%, 30%); --sl-color-accent: hsl(var(--sl-hue-accent), 90%, 60%); --sl-color-accent-low: hsl(var(--sl-hue-accent), 88%, 90%);}The new color theme editor might help if you’d prefer to set a new color scheme.
#397 73eb5e6 Thanks @lorenzolewis! - Add LinkCard component
#460 2e0fb90 Thanks @HiDeoo! - Fix current page highlight in sidebar for URLs with no trailing slash
#467 461a5d5 Thanks @delucis! - Fix type error for downstream tsc users
#475 06a205e Thanks @Yan-Thomas! - Locales whose language tag includes a regional subtag now use built-in UI translations for their base language. For example, a locale with a language of pt-BR will use our pt UI translations.
#473 6a7692a Thanks @HiDeoo! - Fix issue with nested <Tabs> components
#424 4485d90 Thanks @delucis! - Add support for customising autogenerated sidebar link labels from page frontmatter, overriding the page title:
---title: About this projectsidebar: label: About---#359 e733311 Thanks @IDurward! - Add support for defining the order of auto-generated link groups in the sidebar using a frontmatter value:
---title: Page to display firstsidebar: order: 1---#413 5a9d8f1 Thanks @delucis! - Fix site title overflow bug for longer titles on narrow screens
#381 6e62909 Thanks @lorenzolewis! - Preserve order of social config in navbar
#419 38ff53c Thanks @lorenzolewis! - Improve styling of sidebar entries that wrap onto multiple lines
#418 c7b2a4e Thanks @delucis! - Set tab-size: 2 on content code blocks to override default browser value of 8
#399 31b8a5a Thanks @HiDeoo! - Add new global favicon option defaulting to '/favicon.svg' to set the path of the default favicon for your website. Additional icons can be specified using the head option.
#414 e951671 Thanks @delucis! - Add GitLab to social link icons
#383 0ebc47e Thanks @delucis! - Fix edge case where index files in an index directory would end up with the wrong slug
#373 308b3aa Thanks @lorenzolewis! - Fix visual overflow for wide logos
#385 fb35397 Thanks @lorenzolewis! - Fix nested elements in markdown content
#386 e6f6f30 Thanks @huijing! - Prevent search keyboard shortcuts from triggering when input elements are focused
8415df6 Thanks @HiDeoo! - Fix build warnings when using the TypeScript verbatimModuleSyntax compiler option#352 a2e23be Thanks @TheOtterlord! - Fix page scrolling when the window resizes, while the mobile nav is open
#353 65b2b75 Thanks @liruifengv! - Add Simplified Chinese language support
#336 2b3302b Thanks @delucis! - Add support for LinkedIn, Threads, and Twitch social icon links
#335 757c65f Thanks @delucis! - Fix relative path resolution on Windows
#332 0600c1a Thanks @sasoria! - Add Norwegian UI translations
#328 e478848 Thanks @astridx! - Add missing accessible labels for Codeberg and YouTube social links
#313 dc42569 Thanks @delucis! - Add a not-content CSS class that allows users to opt out of Starlight’s default content styling
#297 fb15a9b Thanks @HiDeoo! - Improve <Tabs> component keyboard interactions
#303 69b7d4c Thanks @HiDeoo! - Add new global pagination option defaulting to true to define whether or not the previous and next page links are shown in the footer. A page can override this setting or the link text and/or URL using the new prev and next frontmatter fields.
#259 8102389 Thanks @HiDeoo! - Add support for collapsed sidebar groups
#256 048e948 Thanks @HiDeoo! - Add new global lastUpdated option defaulting to false to define whether or not the last updated date is shown in the footer. A page can override this setting or the generated date using the new lastUpdated frontmatter field.
⚠️ Breaking change. Starlight will no longer show this date by default. To keep the previous behavior, you must explicitly set lastUpdated to true in your configuration.
starlight({ lastUpdated: true,}),#264 ed1e46b Thanks @astridx! - Add new icon for displaying codeberg.org in social links.
#260 01b65b1 Thanks @ElianCodes! - Add Dutch UI translations
#269 fdc18b5 Thanks @baspinarenes! - Add Turkish UI translations
#270 1d3e705 Thanks @cbontems! - Improve French UI translations
#272 6b23ebc Thanks @cbontems! - Add YouTube social link support
#273 d4f5134 Thanks @Waxer59! - Fix typo in Spanish UI translations
#237 4279d75 Thanks @HiDeoo! - Use path instead of slugified path for auto-generated sidebar item configuration
⚠️ Potentially breaking change. If your docs directory names don’t match their URLs, for example they contain whitespace like docs/my docs/, and you were referencing these in an autogenerate sidebar group as my-docs, update your config to reference these with the directory name instead of the slugified version:
autogenerate: { directory: 'my-docs', directory: 'my docs',}#226 1aa2187 Thanks @delucis! - Add support for custom 404 pages.
#234 91309ae Thanks @morinokami! - Add Japanese translation for search.devWarning
#227 fbdecfa Thanks @Yan-Thomas! - Add missing i18n support to the Search component’s dev warning.
#244 f1bcbeb Thanks @Waxer59! - Add Spanish translation for search.devWarning
#171 198c3f0 Thanks @delucis! - Add Starlight generator tag to HTML output
#217 490fd98 Thanks @delucis! - Updated sidebar styles. Sidebars now support top-level links and groups are styled with a subtle border and indentation to improve comprehension of nesting.
#178 d046c55 Thanks @delucis! - Add support for translating the Pagefind search modal
#210 cb5b121 Thanks @delucis! - Change page title ID to _top for cleaner hash URLs
⚠️ Potentially breaking change if you were linking manually to #starlight__overview anywhere. If you were, update these links to use #_top instead.
#190 a3809e4 Thanks @gabrielemercolino! - Added Italian language support
#193 c9ca4eb Thanks @BryceRussell! - Fix bottom padding for sidebar on larger screen sizes
#174 6ab31b4 Thanks @rviscomi! - Split withBase URL helper to fix use with files.
#168 cb18eef Thanks @BryceRussell! - Fix bottom padding on left sidebar
#167 990ec53 Thanks @BryceRussell! - Add bundlePath option to Pagefind configuration
4f666ba Thanks @delucis! - Fix focus outline positioning in tabs
#155 Thanks @thomasbnt! - Add French language support
#158 92d82f5 Thanks @kevinzunigacuellar! - Fix word wrapping in search modal on narrow screens
fab453c Thanks @delucis! - Design tweak: larger sidebar text with more spacing
#134 5f4acdf Thanks @Yan-Thomas! - Add Portuguese language support
8805fbf Thanks @delucis! - Add box-shadow to prev/next page links as per designs
81ef58e Thanks @delucis! - Design tweak: slightly less horizontal padding in header component on narrower viewports
8c103b3 Thanks @delucis! - Design tweak: pad bottom of page content slightly
#129 bbcb277 Thanks @delucis! - Fix bug setting writing direction from a single root locale
ded79af Thanks @delucis! - Add missing skip link to 404 page
#99 d162b2f Thanks @delucis! - Fix “next page” arrow showing on pages not in sidebar
#99 d162b2f Thanks @delucis! - Add support for a “splash” layout
#99 d162b2f Thanks @delucis! - Support hiding right sidebar table of contents
#99 d162b2f Thanks @delucis! - Move edit page link to page footer so it is accessible on mobile
8688778 Thanks @delucis! - Fix small CSS compatibility issue
#93 c6d7960 Thanks @delucis! - Fix default locale routing bug when not using root locale
d8a171b Thanks @delucis! - Fix autogenerated sidebar bug with index routes in subdirectories
d8b9f32 Thanks @delucis! - Fix false positive in sidebar autogeneration logic
#92 02821d2 Thanks @delucis! - Update Pagefind to latest v1 alpha
51fe914 Thanks @delucis! - Guarantee route and autogenerated sidebar sort order
116c4f5 Thanks @delucis! - Fix minor dev layout bug in Search modal for RTL languages
c86c1d6 Thanks @BryceRussell! - Improve outside click detection on the search modal#78 d3ee6fc Thanks @delucis! - Add support for customising and translating Starlight’s UI.
Users can provide translations in JSON files in src/content/i18n/ which is a data collection. For example, a src/content/i18n/de.json might translate the search UI:
{ "search.label": "Suchen", "search.shortcutLabel": "(Drücke / zum Suchen)"}This change also allows Starlight to provide built-in support for more languages than just English and adds German & Spanish support.
#76 5e82073 Thanks @lloydjatkinson! - Scale down code block font size to match Figma design
#78 d3ee6fc Thanks @delucis! - Require a minimum Astro version of 2.5.0
#62 a91191e Thanks @delucis! - Make base support consistent, including when trailingSlash: 'never' is set.
#61 608f34c Thanks @liruifengv! - Fix toc headingsObserver rootMargin
#66 9ca67d8 Thanks @Yan-Thomas! - Make site title width fit the content
#64 4460e55 Thanks @delucis! - Fix table of contents intersection observer for all possible viewport sizes.
#67 38c2c1f Thanks @TheOtterlord! - Fix background color on select component
#57 5b6cccb Thanks @BryceRussell! - Update site title link to include locale
#55 8597b9c Thanks @delucis! - Fix routing logic to handle index.md slug differences between docs collection root and nested directories.
#54 db728d6 Thanks @TheOtterlord! - Add padding to scroll preventing headings being obscured by nav
#51 3adbdbb Thanks @delucis! - Support displaying a custom logo in the nav bar.
#51 3adbdbb Thanks @delucis! - All Starlight projects now use Astro’s experimental optimized asset support.
#47 e96d9a7 Thanks @delucis! - Fix CSS ordering issue caused by imports in 404 route.
#47 e96d9a7 Thanks @delucis! - Highlight current page section in table of contents.
05f8fd4 Thanks @delucis! - Include initial-scale=1 in viewport meta tag.
#47 e96d9a7 Thanks @delucis! - Fix usage of aria-current in navigation sidebar to use page value.
#48 a49485d Thanks @delucis! - Improve right sidebar layout.