Frontmatter
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:
---
title: My lovely article
author: Dr. Fabuloso the Fabulous
tags: [svelte, markdown]
---
# {metadata.title}
By {metadata.author}.<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:
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:
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 };
}<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.
TypeScript
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:
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.
Supported YAML
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 andnullor~, as in YAML 1.2, soyesandoffstay 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.
---
title: 'Hello: World'
count: 0x1F
draft: off
published: 2026-10-02
author: { name: Ada, handle: ~ }
tags:
- svelte
- markdown
summary: >-
Two lines,
folded into one.
---<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 astitle: Hello: World. Quote it:title: 'Hello: World'.
---
title: Hello: World
---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) }
Custom frontmatter parsers
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) }
});---
author: &ada Ada
editor: *ada
---<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)
})
}
});---
title: Hello world
---<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.
filenameisundefinedwhen whoever compiles the document gives no path, ascompile()does without itsfilenameoption. 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) }
});---
title = "TOML Example"
[owner]
name = "some name"
---<script module>
export const metadata = {
title: 'TOML Example',
owner: { name: 'some name' },
};
</script>