Add `titleDelimiter` option to the api and a new design for `<title>` (#447)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

5 files changed, 44 insertions, 4 deletions

diff --git a/.changeset/modern-timers-switch.md b/.changeset/modern-timers-switch.md
new file mode 100644
index 00000000..6bc1fa1e
--- /dev/null
+++ b/.changeset/modern-timers-switch.md
@@ -0,0 +1,21 @@
+---
+'@astrojs/starlight': minor
+---
+
+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:
+
+
+```md
+---
+title: My Page
+head:
+  - tag: title
+    content: Custom Title
+---
+```
\ No newline at end of file
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
index 6545ca7a..6836d865 100644
--- a/docs/src/content/docs/index.mdx
+++ b/docs/src/content/docs/index.mdx
@@ -1,5 +1,8 @@
 ---
 title: Starlight 🌟 Build documentation sites with Astro
+head:
+  - tag: title
+    content: Starlight 🌟 Build documentation sites with Astro
 description: Starlight helps you build beautiful, high-performance documentation websites with Astro.
 template: splash
 banner:
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index aeae37cc..5acaa356 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -425,3 +425,13 @@ starlight({
   ],
 });
 ```
+
+### `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”.
diff --git a/packages/starlight/components/HeadSEO.astro b/packages/starlight/components/HeadSEO.astro
index d187bd98..e744103c 100644
--- a/packages/starlight/components/HeadSEO.astro
+++ b/packages/starlight/components/HeadSEO.astro
@@ -15,7 +15,6 @@ interface Props {
 const { data, lang } = Astro.props;
 
 const canonical = Astro.site ? new URL(Astro.url.pathname, Astro.site) : undefined;
-const title = data.title || config.title;
 const description = data.description || config.description;
 
 const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
@@ -24,7 +23,7 @@ const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
 		tag: 'meta',
 		attrs: { name: 'viewport', content: 'width=device-width, initial-scale=1' },
 	},
-	{ tag: 'title', content: title },
+	{ tag: 'title', content: `${data.title} ${config.titleDelimiter} ${config.title}` },
 	{ tag: 'link', attrs: { rel: 'canonical', href: canonical?.href } },
 	{ tag: 'meta', attrs: { name: 'generator', content: Astro.generator } },
 	{
@@ -41,7 +40,7 @@ const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
 		},
 	},
 	// OpenGraph Tags
-	{ tag: 'meta', attrs: { property: 'og:title', content: title } },
+	{ tag: 'meta', attrs: { property: 'og:title', content: data.title } },
 	{ tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
 	{ tag: 'meta', attrs: { property: 'og:url', content: canonical?.href } },
 	{ tag: 'meta', attrs: { property: 'og:locale', content: lang } },
@@ -52,7 +51,7 @@ const headDefaults: z.input<ReturnType<typeof HeadConfigSchema>> = [
 		tag: 'meta',
 		attrs: { name: 'twitter:card', content: 'summary_large_image' },
 	},
-	{ tag: 'meta', attrs: { name: 'twitter:title', content: title } },
+	{ tag: 'meta', attrs: { name: 'twitter:title', content: data.title } },
 	{ tag: 'meta', attrs: { name: 'twitter:description', content: description } },
 ];
 
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index fb7b7226..863ba759 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/utils/user-config.ts
@@ -279,6 +279,13 @@ const UserConfigSchema = z.object({
 
 	/** The default favicon for your site which should be a path to an image in the `public/` directory. */
 	favicon: FaviconSchema(),
+
+	/** Will be used as title delimiter in the generated `<title>` tag. */
+	titleDelimiter: z
+		.string()
+		.default('|')
+		.describe("Will be used as title delimiter in the generated `<title>` tag."),
+
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(