Move site title `href` to route data for easier overrides (#1842)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>

5 files changed, 30 insertions, 6 deletions

diff --git a/.changeset/polite-cheetahs-help.md b/.changeset/polite-cheetahs-help.md
new file mode 100644
index 00000000..450ec379
--- /dev/null
+++ b/.changeset/polite-cheetahs-help.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+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.
diff --git a/docs/src/content/docs/reference/overrides.md b/docs/src/content/docs/reference/overrides.md
index 74ae9032..9293654b 100644
--- a/docs/src/content/docs/reference/overrides.md
+++ b/docs/src/content/docs/reference/overrides.md
@@ -56,6 +56,13 @@ The base path at which a language is served. `undefined` for root locale slugs.
 
 The site title for this page’s locale.
 
+#### `siteTitleHref`
+
+**Type:** `string`
+
+The value for the site title’s `href` attribute, linking back to the homepage, e.g. `/`.
+For multilingual sites this will include the current locale, e.g. `/en/` or `/zh-cn/`.
+
 #### `slug`
 
 **Type:** `string`
diff --git a/packages/starlight/components/SiteTitle.astro b/packages/starlight/components/SiteTitle.astro
index 1f09a7df..2f4b8299 100644
--- a/packages/starlight/components/SiteTitle.astro
+++ b/packages/starlight/components/SiteTitle.astro
@@ -2,13 +2,10 @@
 import { logos } from 'virtual:starlight/user-images';
 import config from 'virtual:starlight/user-config';
 import type { Props } from '../props';
-import { formatPath } from '../utils/format-path';
-
-const { siteTitle } = Astro.props;
-const href = formatPath(Astro.props.locale || '/');
+const { siteTitle, siteTitleHref } = Astro.props;
 ---
 
-<a {href} class="site-title sl-flex">
+<a href={siteTitleHref} class="site-title sl-flex">
 	{
 		config.logo && logos.dark && (
 			<>
diff --git a/packages/starlight/utils/route-data.ts b/packages/starlight/utils/route-data.ts
index a47e68f2..841804bd 100644
--- a/packages/starlight/utils/route-data.ts
+++ b/packages/starlight/utils/route-data.ts
@@ -9,6 +9,7 @@ import { ensureTrailingSlash } from './path';
 import type { Route } from './routing';
 import { localizedId } from './slugs';
 import { useTranslations } from './translations';
+import { formatPath } from './format-path';
 
 export interface PageProps extends Route {
 	headings: MarkdownHeading[];
@@ -17,6 +18,8 @@ export interface PageProps extends Route {
 export interface StarlightRouteData extends Route {
 	/** Title of the site. */
 	siteTitle: string;
+	/** URL or path used as the link when clicking on the site title. */
+	siteTitleHref: string;
 	/** Array of Markdown headings extracted from the current page. */
 	headings: MarkdownHeading[];
 	/** Site navigation sidebar entries for this page. */
@@ -48,6 +51,7 @@ export function generateRouteData({
 	return {
 		...props,
 		siteTitle,
+		siteTitleHref: getSiteTitleHref(locale),
 		sidebar,
 		hasSidebar: entry.data.template !== 'splash',
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
@@ -118,3 +122,7 @@ export function getSiteTitle(lang: string): string {
 	}
 	return config.title[defaultLang] as string;
 }
+
+export function getSiteTitleHref(locale: string | undefined): string {
+	return formatPath(locale || '/');
+}
diff --git a/packages/starlight/utils/starlight-page.ts b/packages/starlight/utils/starlight-page.ts
index e736457b..24c3bb17 100644
--- a/packages/starlight/utils/starlight-page.ts
+++ b/packages/starlight/utils/starlight-page.ts
@@ -3,7 +3,13 @@ import { type ContentConfig, type SchemaContext } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 import { parseWithFriendlyErrors } from './error-map';
 import { stripLeadingAndTrailingSlashes } from './path';
-import { getSiteTitle, getToC, type PageProps, type StarlightRouteData } from './route-data';
+import {
+	getSiteTitle,
+	getSiteTitleHref,
+	getToC,
+	type PageProps,
+	type StarlightRouteData,
+} from './route-data';
 import type { StarlightDocsEntry } from './routing';
 import { slugToLocaleData, urlToSlug } from './slugs';
 import { getPrevNextLinks, getSidebar } from './navigation';
@@ -224,6 +230,7 @@ export async function generateStarlightPageRouteData({
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
 		sidebar,
 		siteTitle: getSiteTitle(localeData.lang),
+		siteTitleHref: getSiteTitleHref(localeData.locale),
 		slug,
 		toc: getToC({
 			...routeProps,