Skip to content

Style Pagefind root excerpt#3271

Closed
HiDeoo wants to merge 1 commit intowithastro:mainfrom
HiDeoo:hd-fix-search-ui-root-excerpt
Closed

Style Pagefind root excerpt#3271
HiDeoo wants to merge 1 commit intowithastro:mainfrom
HiDeoo:hd-fix-search-ui-root-excerpt

Conversation

@HiDeoo
Copy link
Copy Markdown
Member

@HiDeoo HiDeoo commented Jul 2, 2025

Description

In Pagefind, when searching the indexed content section, if a result is found before the first heading, an extra excerpt is shown below the page title.

At the moment, we do not style this excerpt at all in Starlight altho it can appear under some conditions, e.g. having a banner with content that is a potential match, and as we render <Banner> in <main> (our data-pagefind-body), before the <PageTitle>, it'll be detected as root sub result and the excerpt will be shown.

This PR adds some basic styling to the root excerpt so that it is visually consistent with the rest of the search results altho I'm personally not really happy with the result, as it kinda looks like a result rather than just an excerpt for a root result? I'm definitely not the best person when it comes to design, but I think we may be able to improve it further? A difference from nested results is that the title/link and excerpt are not grouped together with a parent element, they're just siblings in the entire page results.

Preview
With subresults SCR-20250702-kqta
With no subresults SCR-20250702-kqvy

This PR includes a temporary route data middleware adding a banner to every page so searching something like test will show the root excerpt.

Remaining tasks

  • Add a changeset when happy with the PR so we have more context about how to describe the change

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Jul 2, 2025

⚠️ No Changeset found

Latest commit: 1f4ff2e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@netlify
Copy link
Copy Markdown

netlify bot commented Jul 2, 2025

Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit 1f4ff2e
🔍 Latest deploy log https://app.netlify.com/projects/astro-starlight/deploys/6865014c93e8d100096f15b6
😎 Deploy Preview https://deploy-preview-3271--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 100 (🟢 up 1 from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Jul 2, 2025
Copy link
Copy Markdown
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah, I see the issues with this like you mentioned: the excerpt is not clickable and not clearly associated with the page title as one might expect.

I wonder if we can improve on that styling.

An additional thought: if the most common cause of this is our own banner component — we should maybe consider ignoring that by default? Don’t think it’s expected for that to appear in search results.

@delucis
Copy link
Copy Markdown
Member

delucis commented Jul 4, 2025

Couple of quick experiments:

  • Moving the excerpt up and removing top padding visually links the excerpt with the title a bit better:

     /* Move excerpts up closer to the result title */
     #starlight__search .pagefind-ui__result-excerpt:not(:where(.pagefind-ui__result-nested *)) {
         margin-top: -0.75em; /* Magic number — would be good to derive this instead. */
         padding-top: 0;
     }
     
     /* When the title is focused, also highlight the excerpt */
     #starlight__search .pagefind-ui__result-title:focus-within + .pagefind-ui__result-excerpt:not(:where(.pagefind-ui__result-nested *)) {
         background-color: var(--sl-color-accent-low);
     }

    search UI

  • But this introduces issues of course with hover states:

    search UI

  • We can’t use outline because of the overlap, but we can simulate it using border on a pseudo element attached to the excerpt:

     #starlight__search .pagefind-ui__result-excerpt:not(:where(.pagefind-ui__result-nested *))::after {
         content: "";
         position: absolute;
         inset: -1px;
         border: 1px solid transparent;
         border-top: 0;
     }

    Which we reveal when the title is hovered or focused:

     #starlight__search .pagefind-ui__result-title:where(:hover,:focus-within) + .pagefind-ui__result-excerpt:not(:where(.pagefind-ui__result-nested *))::after {
         border-color: var(--sl-color-accent-high);
     }

    Hover version:

    search UI

    Focus version:

    search UI

The weird thing about this approach is that the excerpt is still not actually hoverable to click the link over the excerpt — only on the title. Not sure if there’s a reliable way to extend the interactive area down over the excerpt without hard coding the height. Anchor positioning might help? But it doesn’t have broad support yet.

@delucis
Copy link
Copy Markdown
Member

delucis commented Jul 11, 2025

Chatted with @HiDeoo and we’re closing this in favour of our project rewriting the search UI from scratch which he is currently working on.

Any solution we try here will likely feel hacky and not fully work. #3276 should reduce the risk of users hitting this, so also reduces the urgency of a hacky fix like this.

@delucis delucis closed this Jul 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Search display broken due to code marks and other elements

2 participants