feat: add blank template

.changeset/tricky-wings-sit.md

@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds support for an empty page template to allow full control over the content panel of the page.
+
+Read more about the new `'blank'` template in the ["Page layout" guide](https://starlight.astro.build/guides/customization/#page-layout).

docs/src/content/docs/guides/customization.mdx

@@ -111,10 +111,11 @@ Learn how to [add a sitemap link to `robots.txt`](https://docs.astro.build/en/gu
 
 ## Page layout
 
-By default, Starlight pages use a layout with a global navigation sidebar and a table of contents that shows the current page headings.
+By default, Starlight pages use a layout with a global navigation sidebar and a table of contents that shows the current page headings. This layout is ideal for documentation sites with lots of content to explore.
 
-You can apply a wider page layout without sidebars by setting [`template: splash`](/reference/frontmatter/#template) in a page’s frontmatter.
-This works particularly well for landing pages and you can see it in action on the [homepage of this site](/).
+Starlight also offers two additional page templates that can help you create a more customized experience for your readers.
+
+The `splash` template is a wider layout that removes the sidebars. This works particularly well for landing pages and you can see it in action on the [homepage of this site](/). You can apply a wider page layout without sidebars by setting [`template: splash`](/reference/frontmatter/#template) in a page’s frontmatter.
 
 ```md {5}
 ---
@@ -125,6 +126,21 @@ template: splash
 ---
 ```
 
+The `blank` template minimizes the page layout to just the top header and main content area, giving you a blank canvas to work with. This is ideal for pages where you want to create a completely custom design or layout. Use the `blank` template by setting [`template: blank`](/reference/frontmatter/#template) in frontmatter:
+
+```md {5}
+---
+# src/content/docs/index.md
+
+title: My Custom Page
+template: blank
+---
+```
+
+:::note
+With the `blank` template, you are responsible for adding any navigation or other elements you want on the page, so it’s best suited for advanced users who are comfortable working with Astro and Starlight’s components.
+:::
+
 ## Table of contents
 
 Starlight displays a table of contents on each page to make it easier for readers to jump to the heading they are looking for.

docs/src/content/docs/reference/frontmatter.md

@@ -85,12 +85,13 @@ tableOfContents: false
 
 ### `template`
 
-**type:** `'doc' | 'splash'`  
+**type:** `'doc' | 'splash' | 'blank'`  
 **default:** `'doc'`
 
 Set the layout template for this page.
 Pages use the `'doc'` layout by default.
 Set to `'splash'` to use a wider layout without any sidebars designed for landing pages.
+Set to `'blank'` to have full control over the content panel of the page.
 
 ### `hero`
 

packages/starlight/components/Page.astro

@@ -92,30 +92,39 @@ if (pagefindEnabled) mainDataAttributes['data-pagefind-body'] = '';
 					lang={starlightRoute.entryMeta.lang}
 					dir={starlightRoute.entryMeta.dir}
 				>
-					{/* TODO: Revisit how this logic flows. */}
 					<Banner />
 					{
-						starlightRoute.entry.data.hero ? (
+						starlightRoute.entry.data.template === 'blank' ? (
 							<ContentPanel>
-								<Hero />
-								<MarkdownContent>
-									<slot />
-								</MarkdownContent>
-								<Footer />
+								<slot />
 							</ContentPanel>
 						) : (
 							<>
 								<ContentPanel>
-									<PageTitle />
-									{starlightRoute.entry.data.draft && <DraftContentNotice />}
-									{starlightRoute.isFallback && <FallbackContentNotice />}
-								</ContentPanel>
-								<ContentPanel>
-									<MarkdownContent>
-										<slot />
-									</MarkdownContent>
-									<Footer />
+									{starlightRoute.entry.data.hero ? (
+										<>
+											<Hero />
+											<MarkdownContent>
+												<slot />
+											</MarkdownContent>
+											<Footer />
+										</>
+									) : (
+										<>
+											<PageTitle />
+											{starlightRoute.entry.data.draft && <DraftContentNotice />}
+											{starlightRoute.isFallback && <FallbackContentNotice />}
+										</>
+									)}
 								</ContentPanel>
+								{starlightRoute.entry.data.hero ? null : (
+									<ContentPanel>
+										<MarkdownContent>
+											<slot />
+										</MarkdownContent>
+										<Footer />
+									</ContentPanel>
+								)}
 							</>
 						)
 					}

packages/starlight/schema.ts

@@ -37,9 +37,9 @@ const StarlightFrontmatterSchema = (context: SchemaContext) =>
 
 		/**
 		 * Set the layout style for this page.
-		 * Can be `'doc'` (the default) or `'splash'` for a wider layout without any sidebars.
+		 * Can be `'doc'` (the default), `'splash'` for a wider layout without any sidebars, or `'blank'` for a completely blank layout.
 		 */
-		template: z.enum(['doc', 'splash']).default('doc'),
+		template: z.enum(['doc', 'splash', 'blank']).default('doc'),
 
 		/** Display a hero section on this page. */
 		hero: HeroSchema(context).optional(),

packages/starlight/utils/routing/data.ts

@@ -51,18 +51,19 @@ export function generateRouteData({
 		siteTitle,
 		siteTitleHref: getSiteTitleHref(locale),
 		sidebar,
-		hasSidebar: entry.data.template !== 'splash',
+		hasSidebar: entry.data.template === 'doc',
 		pagination: getPrevNextLinks(sidebar, config.pagination, entry.data),
 		toc: getToC(props),
 		lastUpdated: getLastUpdated(props),
 		editUrl: getEditUrl(props),
 		head: getHead(props, context, siteTitle),
+		template: entry.data.template,
 	};
 }
 
 export function getToC({ entry, lang, headings }: PageProps) {
 	const tocConfig =
-		entry.data.template === 'splash'
+		entry.data.template === 'splash' || entry.data.template === 'blank'
 			? false
 			: entry.data.tableOfContents !== undefined
 				? entry.data.tableOfContents

packages/starlight/utils/routing/types.ts

@@ -98,4 +98,6 @@ export interface StarlightRouteData extends Route {
 	Content?: RenderResult['Content'];
 	/** Array of tags to include in the `<head>` of the current page. */
 	head: HeadConfig;
+	/** Template to use for the rendered page, doc, splash or blank. */
+	template: 'blank' | 'splash' | 'doc';
 }

packages/starlight/utils/starlight-page.ts

@@ -154,7 +154,7 @@ export async function generateStarlightPageRouteData({
 		editUrl,
 		entry,
 		entryMeta,
-		hasSidebar: props.hasSidebar ?? entry.data.template !== 'splash',
+		hasSidebar: props.hasSidebar ?? entry.data.template === 'doc',
 		head: getHead(pageProps, context, siteTitle),
 		headings,
 		lastUpdated,
@@ -163,6 +163,7 @@ export async function generateStarlightPageRouteData({
 		siteTitle,
 		siteTitleHref: getSiteTitleHref(localeData.locale),
 		toc: getToC(pageProps),
+		template: entry.data.template,
 	};
 	return routeData;
 }