Skip to content
Starlight

Pages

Starlight generates your site’s HTML pages based on your content, with flexible options provided via Markdown frontmatter. In addition, Starlight projects have full access to Astro’s powerful page generation tools. This guide shows how page generation works in Starlight.

Content pages

File formats

Starlight supports authoring content in Markdown and MDX with no configuration required. You can add support for Markdoc by following the “Markdoc” guide.

Add pages

Add new pages to your site by creating .md or .mdx files in src/content/docs/. Use sub-folders to organize your files and to create multiple path segments.

For example, the following file structure will generate pages at example.com/hello-world and example.com/reference/faq:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • hello-world.md
        • Directoryreference/
          • faq.md

Type-safe frontmatter

All Starlight pages share a customizable common set of frontmatter properties to control how the page appears:

---
title: Hello, World!
description: This is a page in my Starlight-powered site
---

If you forget anything important, Starlight will let you know.

Custom pages

For advanced use cases, you can add custom pages by creating a src/pages/ directory. The src/pages/ directory uses Astro’s file-based routing and includes support for .astro files amongst other page formats. This is helpful if you need to build pages with a completely custom layout or generate a page from an alternative data source.

For example, this project mixes Markdown content in src/content/docs/ with Astro and HTML routes in src/pages/:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • hello-world.md
    • Directorypages/
      • custom.astro
      • archived.html

Read more in the “Pages” guide in the Astro docs.

Using Starlight’s design in custom pages

To use the Starlight layout in custom pages, wrap your page content with the <StarlightPage /> component. This can be helpful if you are generating content dynamically but still want to use Starlight’s design.

src/pages/custom-page/example.astro
---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
import CustomComponent from './CustomComponent.astro';
---


<StarlightPage frontmatter={{ title: 'My custom page' }}>
  <p>This is a custom page with a custom component:</p>
  <CustomComponent />
</StarlightPage>

Props

The <StarlightPage /> component accepts the following props.

frontmatter (required)

type: StarlightPageFrontmatter

Set the frontmatter properties for this page, similar to frontmatter in Markdown pages. The title property is required and all other properties are optional.

The following properties differ from Markdown frontmatter:

  • The slug property is not supported and is automatically set based on the custom page’s URL.
  • The editUrl option requires a URL to display an edit link.
  • The sidebar frontmatter property for customizing how the page appears in autogenerated link groups is not available. Pages using the <StarlightPage /> component are not part of a collection and cannot be added to an autogenerated sidebar group.
  • The draft option only displays a notice that the page is a draft but does not automatically exclude it from production builds.

type: SidebarItem[]
default: the sidebar generated based on the global sidebar config

Provide a custom site navigation sidebar for this page. If not set, the page will use the default global sidebar.

For example, the following page overrides the default sidebar with a link to the homepage and a group of links to various other custom pages.

<StarlightPage
  frontmatter={{ title: 'Orion' }}
  sidebar={[
    { label: 'Home', link: '/' },
    {
      label: 'Constellations',
      items: [
        { label: 'Andromeda', link: '/andromeda/' },
        { label: 'Orion', link: '/orion/' },
        { label: 'Ursa Minor', link: '/ursa-minor/', badge: 'Stub' },
      ],
    },
  ]}
>
  Example content.
</StarlightPage>

See the “Sidebar Navigation” guide to learn more about the available options for customizing the sidebar.

hasSidebar

type: boolean
default: false if frontmatter.template is 'splash', otherwise true

Control whether or not the sidebar should be displayed on this page.

headings

type: { depth: number; slug: string; text: string }[]
default: []

Provide an array of all the headings on this page. Starlight will generate the page table of contents from these headings if provided.

dir

type: 'ltr' | 'rtl'
default: the writing direction for the current locale

Set the writing direction for this page’s content.

lang

type: string
default: the language of the current locale

Set the BCP-47 language tag for this page’s content, e.g. en, zh-CN, or pt-BR.

isFallback

type: boolean
default: false

Indicate if this page is using fallback content because there is no translation for the current language.