Adding few blank components that would make extending easier #1443

palmiak · 2024-01-31T23:36:58Z

palmiak
Jan 31, 2024

What version of `starlight` are you using?

0.17.2

What is your idea?

While adding things like OG is quite simple because we just have to override the <Head />, it is more tricky to add something to the bottom of the page (right before ).

Overall, I was thinking that maybe it would be a good idea to add a few blank components, that we can use just for extending.

For example:

<HeadStart />
<HeadEnd />
<BodyStart />
<BodyEnd />

They would be placed in the Page.astro:


<html
	lang={Astro.props.lang}
	dir={Astro.props.dir}
	data-has-toc={Boolean(Astro.props.toc)}
	data-has-sidebar={Astro.props.hasSidebar}
	data-has-hero={Boolean(Astro.props.entry.data.hero)}
>
	<head>
		<HeadStart {...Astro.props} />
		<Head {...Astro.props} />
		<style>
			html:not([data-has-toc]) {
				--sl-mobile-toc-height: 0rem;
			}
			html:not([data-has-sidebar]) {
				--sl-content-width: 67.5rem;
			}
			/* Add scroll padding to ensure anchor headings aren't obscured by nav */
			html {
				/* Additional padding is needed to account for the mobile TOC */
				scroll-padding-top: calc(1.5rem + var(--sl-nav-height) + var(--sl-mobile-toc-height));
			}
			main {
				padding-bottom: 3vh;
			}
			@media (min-width: 50em) {
				[data-has-sidebar] {
					--sl-content-inline-start: var(--sl-sidebar-width);
				}
			}
			@media (min-width: 72em) {
				html {
					scroll-padding-top: calc(1.5rem + var(--sl-nav-height));
				}
			}
		</style>
		<ThemeProvider {...Astro.props} />
		<HeadEnd {...Astro.props} />
	</head>
	<body>
		<BodyStart {...Astro.props} />
		<SkipLink {...Astro.props} />
		<PageFrame {...Astro.props}>
			<Header slot="header" {...Astro.props} />
			{Astro.props.hasSidebar && <Sidebar slot="sidebar" {...Astro.props} />}
			<TwoColumnContent {...Astro.props}>
				<PageSidebar slot="right-sidebar" {...Astro.props} />
				<main
					data-pagefind-body={pagefindEnabled}
					lang={Astro.props.entryMeta.lang}
					dir={Astro.props.entryMeta.dir}
				>
					{/* TODO: Revisit how this logic flows. */}
					<Banner {...Astro.props} />
					{
						Astro.props.entry.data.hero ? (
							<ContentPanel {...Astro.props}>
								<Hero {...Astro.props} />
								<MarkdownContent {...Astro.props}>
									<slot />
								</MarkdownContent>
								<Footer {...Astro.props} />
							</ContentPanel>
						) : (
							<>
								<ContentPanel {...Astro.props}>
									<PageTitle {...Astro.props} />
									{Astro.props.isFallback && <FallbackContentNotice {...Astro.props} />}
								</ContentPanel>
								<ContentPanel {...Astro.props}>
									<MarkdownContent {...Astro.props}>
										<slot />
									</MarkdownContent>
									<Footer {...Astro.props} />
								</ContentPanel>
							</>
						)
					}
				</main>
			</TwoColumnContent>
		</PageFrame>
		<BodyEnd {...Astro.props}/>
	</body>
</html>

As I mentioned - those components would be empty by default, so any overriding wouldn't break the core functionality.

Why is this feature necessary?

I think adding more components like this (and maybe it would be a good idea to add even more of them - not sure about this, only those 4 came to my mind as the most common ones) would make extending Starlight easier and safer because those components would serve more as "slots" to fill with some custom content.

Do you have examples of this feature in other projects?

The idea is a bit inspired by WordPress' hook system, where you create hooks that can be extended from other parts of the code.

https://www.hostinger.com/tutorials/what-are-wordpress-hooks/

Participation

I am willing to submit a pull request for this feature.

delucis · 2024-02-01T15:02:16Z

delucis
Feb 1, 2024
Maintainer

Thanks for the suggestion @palmiak!

Would you mind expanding a bit on any specific use cases, e.g. things you’d have loved to be able to slot into one of these four suggested locations?

0 replies

palmiak · 2024-02-01T16:55:15Z

palmiak
Feb 1, 2024
Author

The simplest thing - all weird marketing scripts, or adding some functionality like OG:image (instead of overwriting head component). czw., 1 lut 2024, 16:02 użytkownik Chris Swithinbank < ***@***.***> napisał:

…

Thanks for the suggestion @palmiak <https://github.com/palmiak>! Would you mind expanding a bit on any specific use cases, e.g. things you’d have loved to be able to slot into one of these four suggested locations? — Reply to this email directly, view it on GitHub <#1443 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAR34OTR4V2ZQBHSHCE5LGDYROVAHAVCNFSM6AAAAABCT5QC7GVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DGMZVHE3TA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

1 reply

delucis Feb 1, 2024
Maintainer

Thanks — super helpful! I’m currently thinking about some head improvements for things like the OG image, so it’s good to also hear about similar needs elsewhere in the template.

palmiak · 2024-02-01T18:31:41Z

palmiak
Feb 1, 2024
Author

I would be interested in implementing those slots if you are interested. Not pushing, but would love to help a bit 💪 Having real fun building our first docs using Starlight. czw., 1 lut 2024, 19:13 użytkownik Chris Swithinbank < ***@***.***> napisał:

…

Thanks — super helpful! I’m currently thinking about some head improvements for things like the OG image, so it’s good to also hear about similar needs elsewhere in the template. — Reply to this email directly, view it on GitHub <#1443 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAR34OTIXL7QTM2GOHVGLVTYRPLLNAVCNFSM6AAAAABCT5QC7GVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DGMZYGE3DM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

1 reply

delucis Feb 1, 2024
Maintainer

Aww, that’s nice to hear!

Given these use cases are not really for UI but for scripts (because injecting elements into these locations would break layout in every case I think), I’m wondering if there’s a better API. I have an item on my to-do list to write up a proposal for an injectHead() tool, kind of like a “middleware” system for stuff that ends up in head, because in a way component overrides feel like an odd fit here and make it harder for e.g. multiple plugins to be involved. Now with your extra context, I can consider if there are other needs for a similar API.

In theory there’s not much need these days for scripts at the end of the page with <script defer> although I guess if you really want to delay queuing something up for download it could help.

palmiak · 2024-02-01T21:48:11Z

palmiak
Feb 1, 2024
Author

I like the idea about the middleware-like solution. For sure it would be much more extensible from the plugin perspective. Such tool could be quite universal and there could be more slots not only header. Footer (or right after the body open - don't remember for sure) slot might be useful for noscript tag for GTM for example. So more slots might be useful in some cases. czw., 1 lut 2024, 20:03 użytkownik Chris Swithinbank < ***@***.***> napisał:

…

Aww, that’s nice to hear! Given these use cases are not really for UI but for scripts (because injecting elements into these locations would break layout in every case I think), I’m wondering if there’s a better API. I have an item on my to-do list to write up a proposal for an injectHead() tool, kind of like a “middleware” system for stuff that ends up in head, because in a way component overrides feel like an odd fit here and make it harder for e.g. multiple plugins to be involved. Now with your extra context, I can consider if there are other needs for a similar API. In theory there’s not much need these days for scripts at the end of the page with <script defer> although I guess if you really want to delay queuing something up for download it could help. — Reply to this email directly, view it on GitHub <#1443 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAR34OQEK74ZJXXLTXPZ4N3YRPRIXAVCNFSM6AAAAABCT5QC7GVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DGMZYGU2TS> . You are receiving this because you were mentioned.Message ID: ***@***.***>

0 replies

HiDeoo · 2025-08-11T15:08:20Z

HiDeoo
Aug 11, 2025
Maintainer

Starting with Starlight 0.35.0, route data now include the head property which contains an array of all tags to include in the of the current page.

Such data can be customized using a route data middleware. For example, to add some meta tags for Open Graph images, this would look like the following:

// src/routeData.ts
import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

export const onRequest = defineRouteMiddleware((context) => {
  // Get the URL of the Open Graph image to use.
  const ogImageUrl = new URL(`/og/my-og-image.png`, context.site);

  // Get the array of all tags to include in the `<head>` of the current page.
  const { head } = context.locals.starlightRoute;

  // Add the `<meta/>` tags for the Open Graph images.
  head.push({
    tag: "meta",
    attrs: { property: "og:image", content: ogImageUrl.href },
  });
  head.push({
    tag: "meta",
    attrs: { name: "twitter:image", content: ogImageUrl.href },
  });
});

You can of course use any of the route data properties in your middleware e.g. to compute a dynamic Open Graph image URL based on the current page's ID for example.

As the most common use case suggested in this discussion was related to Open Graph images and it's getting quite old, I'll close this discussion and if we ever need to revisit some other solutions for different use cases, we can open a new discussion at that time.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Adding few blank components that would make extending easier #1443

Uh oh!

{{title}}

Uh oh!

Replies: 5 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Adding few blank components that would make extending easier #1443

Uh oh!

palmiak Jan 31, 2024

What version of starlight are you using?

What is your idea?

Why is this feature necessary?

Do you have examples of this feature in other projects?

Participation

Replies: 5 comments · 2 replies

Uh oh!

delucis Feb 1, 2024 Maintainer

Uh oh!

palmiak Feb 1, 2024 Author

Uh oh!

delucis Feb 1, 2024 Maintainer

Uh oh!

palmiak Feb 1, 2024 Author

Uh oh!

delucis Feb 1, 2024 Maintainer

Uh oh!

palmiak Feb 1, 2024 Author

Uh oh!

HiDeoo Aug 11, 2025 Maintainer

palmiak
Jan 31, 2024

What version of `starlight` are you using?

Replies: 5 comments 2 replies

delucis
Feb 1, 2024
Maintainer

palmiak
Feb 1, 2024
Author

delucis Feb 1, 2024
Maintainer

palmiak
Feb 1, 2024
Author

delucis Feb 1, 2024
Maintainer

palmiak
Feb 1, 2024
Author

HiDeoo
Aug 11, 2025
Maintainer