diff --git a/.changeset/tricky-wings-sit.md b/.changeset/tricky-wings-sit.md
new file mode 100644
index 00000000000..a68486e108b
--- /dev/null
+++ b/.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).
diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx
index c53fa0ba982..fecf144fea6 100644
--- a/docs/src/content/docs/guides/customization.mdx
+++ b/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.
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index a85c4f8471d..3419281311e 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/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`
diff --git a/packages/starlight/components/Page.astro b/packages/starlight/components/Page.astro
index baf12f3710c..cbe70752054 100644
--- a/packages/starlight/components/Page.astro
+++ b/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. */}
{
- starlightRoute.entry.data.hero ? (
+ starlightRoute.entry.data.template === 'blank' ? (
-
-
-
-
-
+
) : (
<>
-
- {starlightRoute.entry.data.draft && }
- {starlightRoute.isFallback && }
-
-
-
-
-
-
+ {starlightRoute.entry.data.hero ? (
+ <>
+
+
+
+
+
+
+ ) : (
+ <>
+
+ {starlightRoute.entry.data.draft && }
+ {starlightRoute.isFallback && }
+
+ )}
+ {starlightRoute.entry.data.hero ? null : (
+
+
+
+
+
+
+ )}
)
}
diff --git a/packages/starlight/schema.ts b/packages/starlight/schema.ts
index 746734f3f78..30e39179e7a 100644
--- a/packages/starlight/schema.ts
+++ b/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(),
diff --git a/packages/starlight/utils/routing/data.ts b/packages/starlight/utils/routing/data.ts
index 25fdc6a877e..2b99f41c768 100644
--- a/packages/starlight/utils/routing/data.ts
+++ b/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
diff --git a/packages/starlight/utils/routing/types.ts b/packages/starlight/utils/routing/types.ts
index 1980107803a..24b45f0407c 100644
--- a/packages/starlight/utils/routing/types.ts
+++ b/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 `` of the current page. */
head: HeadConfig;
+ /** Template to use for the rendered page, doc, splash or blank. */
+ template: 'blank' | 'splash' | 'doc';
}
diff --git a/packages/starlight/utils/starlight-page.ts b/packages/starlight/utils/starlight-page.ts
index c41aa90d2d9..cee8f50a997 100644
--- a/packages/starlight/utils/starlight-page.ts
+++ b/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;
}