Frontmatter

How MDSX handles frontmatter in your markdown files.

MDSX automatically parses YAML frontmatter from your markdown files and makes it available throughout the compilation process. This allows you to add metadata to your content and use it in your components and blueprints.

Basic Frontmatter

Frontmatter is defined at the top of your markdown file using YAML syntax between --- delimiters:

src/content/example.md

		---
title: My Document
description: This is a description of my document
author: John Doe
date: 2024-01-15
tags: [markdown, mdsx, svelte]
---
 
# My Document
 
This is the content of my document...

MDSX will parse this frontmatter and make it available as metadata in the compiled Svelte component.

Metadata Access

When MDSX compiles your markdown file, it automatically creates a metadata export in the module script and destructures the frontmatter keys for easy access:

		<!-- output -->
<script module>
	export const metadata = {
		title: 'My Document',
		description: 'This is a description of my document',
		author: 'John Doe',
		date: '2024-01-15',
		tags: ['markdown', 'mdsx', 'svelte'],
	};
	const { title, description, author, date, tags } = metadata;
</script>

Which means you can confidently use these variables directly in your markdown content:

src/content/example.md

		---
title: My Document
description: This is a description of my document
author: John Doe
---
 
# {title}
 
By {author}
 
{description}
 
## Content
 
Your markdown content here...

Blueprint Integration

Frontmatter is particularly powerful when used with Blueprints. The metadata object is passed as a prop to your blueprint component.

You can use this to create a consistent layout for your markdown files:

src/lib/blueprints/default/blueprint.svelte

		<script lang="ts">
	let {
		metadata,
		children,
	}: {
		metadata: {
			title: string;
			description: string;
			author: string;
			date: string;
			tags: string[];
		};
		children: Snippet;
	} = $props();
</script>
 
<article>
	<header>
		<h1>{metadata.title}</h1>
		<p>{metadata.description}</p>
		<footer>
			<span>By {metadata.author}</span>
			<time datetime={metadata.date}>{metadata.date}</time>
		</footer>
	</header>
 
	{@render children?.()}
</article>

Blueprint Selection

You can use frontmatter to specify which blueprint should be used for a particular markdown file:

src/content/blog-post.md

		---
title: My Blog Post
description: A blog post about MDSX
blueprint: blog
---
 
# My Blog Post
 
Content here...

This will use the blog blueprint instead of the default one.

Custom Frontmatter Parser

By default, MDSX uses yaml to parse frontmatter. However, you can provide a custom parser function in your MDSX configuration:

mdsx.config.js

		import { defineConfig } from 'mdsx';
import { parse as parseToml } from '@iarna/toml';
 
export const mdsxConfig = defineConfig({
	extensions: ['.md'],
	frontmatterParser: (str) => {
		// custom logic to parse frontmatter
		// return parsed object or undefined if no frontmatter found
		const match = /^---\n([sS]*?)\n---/.exec(str);
		if (match) return parseToml(match[1]);
		return undefined;
	},
});

Warning

If you provide a custom parser, it's your responsibility to handle the frontmatter extraction and return the parsed object. The parser should return undefined if no frontmatter is found.

No Frontmatter

If your markdown file doesn't have frontmatter, MDSX will still create a metadata export, but it will be an empty object:

src/content/no-frontmatter.md

		# No Frontmatter
 
This file has no frontmatter.

Compiles to:

		<script module>
	export const metadata = {};
</script>
 
<h1>No Frontmatter</h1><p>This file has no frontmatter.</p>

Complex Data Types

MDSX supports all YAML data types in frontmatter:

src/content/complex-frontmatter.md

		---
title: Complex Example
numbers: [1, 2, 3, 4, 5]
nested:
  key: value
  array: [a, b, c]
boolean: true
null_value: null
multiline: |
  This is a
  multiline string
---
 
# {title}
 
Numbers: {numbers.join(', ')}
 
Nested value: {nested.key}