I would like to have my integration define custom frontmatter for a page, and then access this data inside my component.
#Starlight extend frontmatter with custom schema in integration
tawdry sorrel
celest surgeBOT
Hi @tawdry sorrel. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Sure, you can extend the frontmatter schema in Starlight's docs content collection by using the docsSchema() helper. This is configured in src/content/config.ts. Here's an example of how you can do this:
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({
schema: docsSchema()
}),
};
You can extend Starlight’s schema with additional fields by setting extend in the docsSchema() options. The value should be a Zod schema. Here's an example where a stricter type for description is provided to make it required and a new optional category field is added:
import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({
schema: docsSchema({
extend: z.object({
// Make a built-in field required instead of optional.
description: z.string(),
// Add a new field to the schema.
category: z.enum(['tutorial', 'guide', 'reference']).optional(),
}),
}),
}),
};
To access this data inside your component, you can use Astro.props.entry.data. For example, to display the current page’s title, you can do:
import type { Props } from '@astrojs/starlight/props';
const { title } = Astro.props.entry.data;<h1 id="_top">{title}</h1>
You can find more details in the following sources:
- **Customize frontmatter schema** (<https://starlight.astro.build/reference/frontmatter/#customize-frontmatter-schema>)
- **Extend frontmatter schema** (<https://starlight.astro.build/reference/frontmatter/#extend>)
- **Use page data** (<https://starlight.astro.build/guides/overriding-components/#use-page-data>)
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------@celest surge This is great, but I can't have a config.ts in src/docs, as I am creating an integration. Where would this docs schema extension go when creating a package?
celest surgeBOT
Let me check the knowledge base for you. One moment! :books:
If you're creating an integration as an npm package, you can define your custom schema within your package and then export it for use in the projects that install your package.
For example, within your package, you might have a file like my-package-schema.ts:
import { z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';
export const myPackageSchema = docsSchema({
extend: z.object({
// Make a built-in field required instead of optional.
description: z.string(),
// Add a new field to the schema.
category: z.enum(['tutorial', 'guide', 'reference']).optional(),
}),
});
Then, in the project that uses your package, you can import your custom schema and use it in the src/content/config.ts file:
import { defineCollection } from 'astro:content';
import { myPackageSchema } from 'my-package';
export const collections = {
docs: defineCollection({
schema: myPackageSchema,
}),
};
This way, you're defining the custom schema within your package, but applying it within the individual project's config.ts file.
Please note that these examples are based on the information provided in the knowledge sources and might need to be adjusted based on the specific requirements of your package and the projects that will use it.
For more information, you can refer to the following sources:
- Customize frontmatter schema (https://starlight.astro.build/reference/frontmatter/#customize-frontmatter-schema)
- Extend frontmatter schema (https://starlight.astro.build/reference/frontmatter/#extend)
- Using third-party collection schemas (https://docs.astro.build/en/guides/content-collections/#using-third-party-collection-schemas)