Extend Starlight’s frontmatter schema in a Starlight plugin

Starlight plugins offer an easy-to-share and reusable way to customize and extend Starlight, the fully-featured documentation theme built on top of the Astro framework.

This guide will walk you through the process of extending Starlight’s frontmatter schema, built on top of Astro’s content collections, enabling you to use custom frontmatter properties in a Starlight plugin.

Prerequisites

You will need to have a Starlight plugin set up. If you don’t have one yet, you can follow the “How to create a Starlight plugin” note to create one or refer to the Starlight documentation for a complete reference.

Extend frontmatter schema

Starlight supports extending the frontmatter schema of content pages using the extend property in the docsSchema() options.

This option accepts a Zod schema which in the case of Starlight plugins, can be exported from the plugin package and referenced by users in their src/content.config.ts configuration file.

Export a Zod schema

To export a Zod schema from a Starlight plugin, you can add a new entry in the exports field of the plugin’s package.json file.

The following example adds a new entry point name ./schema that points to a schema.ts file in the plugin’s root directory:

{
  "name": "starlight-plugin-example",
  "version": "0.0.1",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": "./plugin.ts"
    ".": "./plugin.ts",
    "./schema": "./schema.ts"
  },
  "peerDependencies": {
    "@astrojs/starlight": ">=0.34"
  }
}

Next, you can create the schema.ts file in the plugin’s root directory and export a Zod schema from it. The following example exports a simple Zod schema that adds an optional tags property field to the frontmatter schema:

import { z } from 'astro/zod'

// Export a Zod schema to extend the Starlight frontmatter schema.
export const examplePluginSchema = z.object({
  // Add an optional field accepting an array of strings.
  tags: z.array(z.string()).optional(),
})

Use the Zod schema

To reference and use the previously exported Zod schema in the content collections configuration file located at src/content.config.ts, users can import it from the plugin package and set it as the extend property in the docsSchema() options.

The following example updates the extend option in the content collections configuration file to use a Zod schema exported from the starlight-plugin-example package:

import { defineCollection } from 'astro:content'
import { docsLoader } from '@astrojs/starlight/loaders'
import { docsSchema } from '@astrojs/starlight/schema'
import { examplePluginSchema } from 'starlight-plugin-example/schema'

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({ extend: examplePluginSchema }),
  }),
}

Users can now use the tags property in their content page frontmatter, and the value will be validated against the Zod schema defined in the Starlight plugin. The plugin can also access the tags property in route data using the tags property of the entry.data object which contains frontmatter values for the current page.

To learn more about Starlight plugins, check out the “Starlight Plugins by Example” notebook for additional guides and examples.