Use `_top` instead of `starlight__overview` as page title ID (#210)

* Use `top` instead of `starlight__overview` as page title ID

* Add changeset

* `_top` not `top`

7 files changed, 14 insertions, 6 deletions

diff --git a/.changeset/mighty-wolves-jog.md b/.changeset/mighty-wolves-jog.md
new file mode 100644
index 00000000..80f7c6e8
--- /dev/null
+++ b/.changeset/mighty-wolves-jog.md
@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+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.
diff --git a/packages/starlight/404.astro b/packages/starlight/404.astro
index ae7f1765..46cf5189 100644
--- a/packages/starlight/404.astro
+++ b/packages/starlight/404.astro
@@ -36,7 +36,7 @@ const { lang = 'en', dir = 'ltr', locale } = config.defaultLocale || {};
       <Header slot="header" {locale} />
       <main>
         <MarkdownContent>
-          <h1 id="starlight__overview">404</h1>
+          <h1 id="_top" data-page-title>404</h1>
           <p>Houston, we have a problem.</p>
           <p>
             We couldn’t find that link. Check the address or
diff --git a/packages/starlight/components/Hero.astro b/packages/starlight/components/Hero.astro
index a4768622..9bc66c7c 100644
--- a/packages/starlight/components/Hero.astro
+++ b/packages/starlight/components/Hero.astro
@@ -38,7 +38,7 @@ const imageAttrs = {
   }
   <div class="flex stack">
     <div class="flex copy">
-      <h1 id="starlight__overview" set:html={title} />
+      <h1 id="_top" data-page-title set:html={title} />
       {tagline && <div class="tagline" set:html={tagline} />}
     </div>
     {
diff --git a/packages/starlight/components/SkipLink.astro b/packages/starlight/components/SkipLink.astro
index e4e88440..38ce3cac 100644
--- a/packages/starlight/components/SkipLink.astro
+++ b/packages/starlight/components/SkipLink.astro
@@ -8,7 +8,7 @@ interface Props {
 const t = useTranslations(Astro.props.locale);
 ---
 
-<a href="#starlight__overview">{t('skipLink.label')}</a>
+<a href="#_top">{t('skipLink.label')}</a>
 
 <style>
   a {
diff --git a/packages/starlight/components/TableOfContents/generateToC.ts b/packages/starlight/components/TableOfContents/generateToC.ts
index a6c54765..fcc64a33 100644
--- a/packages/starlight/components/TableOfContents/generateToC.ts
+++ b/packages/starlight/components/TableOfContents/generateToC.ts
@@ -25,7 +25,7 @@ export function generateToC(
   headings: MarkdownHeading[],
   { minHeadingLevel, maxHeadingLevel, title = 'Overview' }: TocOpts
 ) {
-  const overview = { depth: 2, slug: 'starlight__overview', text: title };
+  const overview = { depth: 2, slug: '_top', text: title };
   headings = [
     overview,
     ...headings.filter(
diff --git a/packages/starlight/components/TableOfContents/starlight-toc.ts b/packages/starlight/components/TableOfContents/starlight-toc.ts
index 5320b8d8..f327ff71 100644
--- a/packages/starlight/components/TableOfContents/starlight-toc.ts
+++ b/packages/starlight/components/TableOfContents/starlight-toc.ts
@@ -22,7 +22,7 @@ export class StarlightTOC extends HTMLElement {
     const isHeading = (el: Element): el is HTMLHeadingElement => {
       if (el instanceof HTMLHeadingElement) {
         // Special case for page title h1
-        if (el.id === 'starlight__overview') return true;
+        if ('pageTitle' in el.dataset) return true;
         // Check the heading level is within the user-configured limits for the ToC
         const level = el.tagName[1];
         if (level) {
diff --git a/packages/starlight/index.astro b/packages/starlight/index.astro
index d6b693fa..6b5193aa 100644
--- a/packages/starlight/index.astro
+++ b/packages/starlight/index.astro
@@ -102,7 +102,8 @@ const hasHero = Boolean(entry.data.hero);
           ) : (
             <ContentPanel>
               <h1
-                id="starlight__overview"
+                id="_top"
+                data-page-title
                 style="font-size: var(--sl-text-h1); line-height: var(--sl-line-height-headings); font-weight: 600; color: var(--sl-color-white); margin-top: 1rem;"
               >
                 {entry.data.title}