Guides Frontmatter

Source

A document can start with YAML frontmatter between two --- lines.

The frontmatter is exported from the document's module script as metadata, so the document can read it and so can anything that imports the document:

You write src/routes/article/+page.svx
---
title: My lovely article
author: Dr. Fabuloso the Fabulous
tags: [svelte, markdown]
---

# {metadata.title}

By {metadata.author}.
You get
Compiles to
<script module>
  export const metadata = {
    title: 'My lovely article',
    author: 'Dr. Fabuloso the Fabulous',
    tags: ['svelte', 'markdown'],
  };
</script>

<h1>{metadata.title}</h1>
<p>By {metadata.author}.</p>
import { metadata } from './article.svx';

Templates get every key as its own prop.

  • Keys are not separate variables, so write {metadata.title} rather than {title}.

To list posts in SvelteKit, import their metadata with import.meta.glob and the ?metadata query:

src/routes/blog/+page.js
const posts = import.meta.glob('./*/+page.svx', {
	query: '?metadata',
	import: 'metadata',
	eager: true
});

export function load() {
	return {
		posts: Object.entries(posts).map(([path, metadata]) => ({
			slug: path.split('/')[1],
			...metadata
		}))
	};
}

A ?metadata import reads only the frontmatter, so the list does not load the component of every page.

A SvelteKit layout can read the frontmatter of the page it wraps the same way. Without eager, each page's metadata loads on its own, and the id of the route picks it:

src/routes/+layout.js
const pages = import.meta.glob('./**/+page.svx', {
	query: '?metadata',
	import: 'metadata'
});

export async function load({ route }) {
	// the root route is `/`, every other id has no trailing slash
	const dir = route.id === '/' ? '' : route.id;
	const metadata = await pages[`.${dir}/+page.svx`]?.();

	return { metadata: metadata ?? null };
}
src/routes/+layout.svelte
<script>
	let { data, children } = $props();
</script>

<svelte:head>
	<title>{data.metadata?.title ?? 'My site'}</title>
</svelte:head>

{@render children()}

data.metadata is null on a route that isn't a document, and on a document with no frontmatter. The same load works in a +layout.server.js.

mdsvex/globals in compilerOptions.types, beside vite/client, types the query imports: ?metadata, ?data and ?text.

A plain ./post.svx import is a file TypeScript can't read itself. In the editor, the mdsvex extension's TypeScript plugin reads it, with the exports the document has. tsc loads no plugins, so a type check on the command line needs a declaration in the project. A ?template= import is not a file at all, so it needs one in the editor too:

src/svx.d.ts
declare module '*.svx' {
	import type { Component } from 'svelte';
	const component: Component;
	export default component;
	export const metadata: Record<string, unknown> | undefined;
}

declare module '*?template=false' {
	import type { Component } from 'svelte';
	const component: Component;
	export default component;
	export const metadata: Record<string, unknown> | undefined;
}

A module pattern holds one *, so each ?template= value you import with needs a block of its own. The file has no top-level import, so its blocks declare modules rather than add to them.

mdsvex parses frontmatter itself, with no dependency, so compile still runs anywhere. It understands the YAML that frontmatter tends to use:

  • plain, single quoted and double quoted strings, including escapes in double quotes;
  • numbers (1, -4.2, 1e3, 0x1F, 0o17, .inf, .nan), booleans and null or ~, as in YAML 1.2, so yes and off stay strings;
  • dates, which stay strings, such as 2026-10-02;
  • nested maps, block sequences (- a), flow sequences ([a, b]) and flow maps ({ a: 1 });
  • literal | and folded > blocks, with - and + chomping;
  • comments.
You write
---
title: 'Hello: World'
count: 0x1F
draft: off
published: 2026-10-02
author: { name: Ada, handle: ~ }
tags:
  - svelte
  - markdown
summary: >-
  Two lines,
  folded into one.
---
You get
Compiles to
<script module>
  export const metadata = {
    title: 'Hello: World',
    count: 31,
    draft: 'off',
    published: '2026-10-02',
    author: {
      name: 'Ada',
      handle: null,
    },
    tags: ['svelte', 'markdown'],
    summary:
      'Two lines, folded into one.',
  };
</script>

These are errors that name the line, and point you at frontmatter.parse:

  • anchors (&), aliases (*), tags (!!str), complex keys (?) and merge keys (<<);
  • indenting with tabs;
  • a duplicate key;
  • frontmatter that isn't a map of keys to values;
  • a plain value containing :, such as title: Hello: World. Quote it: title: 'Hello: World'.
You write
---
title: Hello: World
---
Its compile throws

Error Unsupported frontmatter at line 2: a plain value can't contain ': ', quote the value. mdsvex's built-in parser handles common YAML. For anything else pass a parser, for example frontmatter: { parse: (raw) => yaml.parse(raw) }

frontmatter.parse replaces the built-in parser. It gets the raw text between the --- lines and returns an object of metadata. Returning null or undefined means no metadata.

For full YAML, use a YAML library such as yaml:

import { mdsvex } from 'mdsvex';
import { parse } from 'yaml';

mdsvex({
	frontmatter: { parse: (raw) => parse(raw) }
});
You write
---
author: &ada Ada
editor: *ada
---
You get
Compiles to
<script module>
  export const metadata = {
    author: 'Ada',
    editor: 'Ada',
  };
</script>

frontmatter.parse gets a second argument, { filename }, the path of the document. A value that comes from where the document lives, such as its slug, can go into metadata there:

import { mdsvex } from 'mdsvex';
import { parse } from 'yaml';

mdsvex({
	frontmatter: {
		parse: (raw, { filename }) => ({
			slug: filename?.split('/').at(-2),
			...parse(raw)
		})
	}
});
You write src/routes/blog/hello-world/+page.svx
---
title: Hello world
---
You get
Compiles to
<script module>
  export const metadata = {
    slug: 'hello-world',
    title: 'Hello world',
  };
</script>

The same parser runs for the compiled document, for a ?metadata import and for the ctx.frontmatter that plugins read, so all three see the slug. A slug written in the frontmatter wins here, because it is spread after.

  • filename is undefined when whoever compiles the document gives no path, as compile() does without its filename option. The key is always there.

The fences stay ---, but what goes between them is up to the parser. For TOML, with smol-toml:

import { mdsvex } from 'mdsvex';
import { parse } from 'smol-toml';

mdsvex({
	frontmatter: { parse: (raw) => parse(raw) }
});
You write
---
title = "TOML Example"

[owner]
name = "some name"
---
You get
Compiles to
<script module>
  export const metadata = {
    title: 'TOML Example',
    owner: { name: 'some name' },
  };
</script>

mdsvex, markdown with Svelte in it. MIT licence.