Frontmatter Reference

Bu içerik henüz dilinizde mevcut değil.

You can customize individual Markdown and MDX pages in Starlight by setting values in their frontmatter. For example, a regular page might set title and description fields:

---
title: About this project
description: Learn more about the project I’m working on.
---

Welcome to the about page!

Frontmatter fields

`title` (required)

type: string

You must provide a title for every page. This will be displayed at the top of the page, in browser tabs, and in page metadata.

`description`

type: string

The page description is used for page metadata and will be picked up by search engines and in social media previews.

`editUrl`

type: string | boolean

Overrides the global editLink config. Set to false to disable the “Edit page” link for a specific page or provide an alternative URL where the content of this page is editable.

`head`

type: HeadConfig[]

You can add additional tags to your page’s <head> using the head frontmatter field. This means you can add custom styles, metadata or other tags to a single page. Similar to the global head option.

---
title: About us
head:
  # Use a custom <title> tag
  - tag: title
    content: Custom about title
---

`tableOfContents`

type: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }

Overrides the global tableOfContents config. Customize the heading levels to be included or set to false to hide the table of contents on this page.

---
title: Page with only H2s in the table of contents
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

---
title: Page with no table of contents
tableOfContents: false
---

`template`

type: 'doc' | 'splash'
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.

`hero`

type: HeroConfig

Add a hero component to the top of this page. Works well with template: splash.

For example, this config shows some common options, including loading an image from your repository.

---
title: My Home Page
template: splash
hero:
  title: 'My Project: Stellar Stuff Sooner'
  tagline: Take your stuff to the moon and back in the blink of an eye.
  image:
    alt: A glittering, brightly colored logo
    file: ../../assets/logo.png
  actions:
    - text: Tell me more
      link: /getting-started/
      icon: right-arrow
      variant: primary
    - text: View on GitHub
      link: https://github.com/astronaut/my-project
      icon: external
---

You can display different versions of the hero image in light and dark modes.

---
hero:
  image:
    alt: A glittering, brightly colored logo
    dark: ../../assets/logo-dark.png
    light: ../../assets/logo-light.png
---

`HeroConfig`

interface HeroConfig {
  title?: string;
  tagline?: string;
  image?:
    | {
        // Relative path to an image in your repository.
        file: string;
        // Alt text to make the image accessible to assistive technology
        alt?: string;
      }
    | {
        // Relative path to an image in your repository to be used for dark mode.
        dark: string;
        // Relative path to an image in your repository to be used for light mode.
        light: string;
        // Alt text to make the image accessible to assistive technology
        alt?: string;
      }
    | {
        // Raw HTML to use in the image slot.
        // Could be a custom `<img>` tag or inline `<svg>`.
        html: string;
      };
  actions?: Array<{
    text: string;
    link: string;
    variant: 'primary' | 'secondary' | 'minimal';
    icon: string;
  }>;
}

`banner`

type: { content: string }

Displays an announcement banner at the top of this page.

The content value can include HTML for links or other content. For example, this page displays a banner including a link to example.com.

---
title: Page with a banner
banner:
  content: |
    We just launched something cool!
    <a href="https://example.com">Check it out</a>
---

`lastUpdated`

type: Date | boolean

Overrides the global lastUpdated option. If a date is specified, it must be a valid YAML timestamp and will override the date stored in Git history for this page.

---
title: Page with a custom last update date
lastUpdated: 2022-08-09
---

`prev`

type: boolean | string | { link?: string; label?: string }

Overrides the global pagination option. If a string is specified, the generated link text will be replaced and if an object is specified, both the link and the text will be overridden.

---
# Hide the previous page link
prev: false
---

---
# Override the previous page link text
prev: Continue the tutorial
---

---
# Override both the previous page link and text
prev:
  link: /unrelated-page/
  label: Check out this other page
---

`next`

type: boolean | string | { link?: string; label?: string }

Same as prev but for the next page link.

---
# Hide the next page link
next: false
---

`pagefind`

type: boolean
default: true

Set whether this page should be included in the Pagefind search index. Set to false to exclude a page from search results:

---
# Hide this page from the search index
pagefind: false
---

`sidebar`

type: SidebarConfig

Control how this page is displayed in the sidebar, when using an autogenerated link group.

`SidebarConfig`

interface SidebarConfig {
  label?: string;
  order?: number;
  hidden?: boolean;
  badge?: string | BadgeConfig;
  attrs?: Record<string, string | number | boolean | undefined>;
}

`label`

type: string
default: the page title

Set the label for this page in the sidebar when displayed in an autogenerated group of links.

---
title: About this project
sidebar:
  label: About
---

`order`

type: number

Control the order of this page when sorting an autogenerated group of links. Lower numbers are displayed higher up in the link group.

---
title: Page to display first
sidebar:
  order: 1
---

`hidden`

type: boolean
default: false

Prevents this page from being included in an autogenerated sidebar group.

---
title: Page to hide from autogenerated sidebar
sidebar:
  hidden: true
---

`badge`

type: string | BadgeConfig

Add a badge to the page in the sidebar when displayed in an autogenerated group of links. When using a string, the badge will be displayed with a default accent color. Optionally, pass a BadgeConfig object with text and variant fields to customize the badge.

---
title: Page with a badge
sidebar:
  # Uses the default variant matching your site’s accent color
  badge: New
---

---
title: Page with a badge
sidebar:
  badge:
    text: Experimental
    variant: caution
---

`attrs`

type: Record<string, string | number | boolean | undefined>

HTML attributes to add to the page link in the sidebar when displayed in an autogenerated group of links.

---
title: Page opening in a new tab
sidebar:
  # Opens the page in a new tab
  attrs:
    target: _blank
---

Frontmatter Reference

Frontmatter fields

title (required)

description

editUrl

head

tableOfContents

template

hero

HeroConfig

banner

lastUpdated

prev

next

pagefind

sidebar

SidebarConfig

label

order

hidden

badge

attrs