Templates
A template is a Svelte component that wraps documents. It's the place for a document's title, byline and surrounding layout, and it can replace the elements of the documents it wraps. mdsvex 0.x called these layouts.
Defining templates
Name your templates in the templates option:
mdsvex({
templates: {
default: '#lib/templates/Post.svelte',
docs: '#lib/templates/Docs.svelte'
}
});---
title: Hello
date: 2026-11-02
---
# Hello
A post.<script module>
export const metadata = {
title: 'Hello',
date: '2026-11-02',
};
</script>
<script>
import Template_MDSVEX from '#lib/templates/Post.svelte';
let __mdsvex_props = $props();
</script>
<Template_MDSVEX
{...metadata}
{...__mdsvex_props}
><h1>Hello</h1>
<p>A post.</p></Template_MDSVEX
> Each value is a specifier, resolved from the project root like an import, or a URL, such as new URL('./src/Blog.svelte', import.meta.url).
A template renders the document with {@render children()}:
<script>
let { title, date, children } = $props();
</script>
<article>
<h1>{title}</h1>
<time datetime={date}>{date}</time>
{@render children()}
</article>Templates are ordinary components, so editing one hot reloads the documents that use it. See the templates playground example.
Documents as templates
A template can be a document too, so its own content is markdown. Like a component, it reads its props and renders children. This is src/lib/templates/Note.svx:
<script>
let { title, children } = $props();
</script>
# {title}
{@render children()}
Written by the _docs team_.<script>
let { title, children } = $props();
</script>
<h1>{title}</h1>
{@render children()}
<p>
Written by the <em>docs team</em>.
</p> mdsvex({
templates: { note: '#lib/templates/Note.svx' }
});It can replace elements from its <script module>, as a component does.
- As a template it is never wrapped in a template itself, so a
templatekey in its frontmatter,select_templateand thedefaultentry don't apply to it.
Choosing a template
mdsvex picks a document's template from the first of these that gives an answer:
- The
?template=query on the import, see opting out. - The
templatekey in the frontmatter, a template name orfalse. select_template(id, metadata), if you configured one.- The
defaultentry intemplates. - Otherwise, no template.
---
title: Writing docs
template: docs
---<script module>
export const metadata = {
title: 'Writing docs',
template: 'docs',
};
</script>
<script>
import Template_MDSVEX from '#lib/templates/Docs.svelte';
let __mdsvex_props = $props();
</script>
<Template_MDSVEX
{...metadata}
{...__mdsvex_props}
></Template_MDSVEX> - An unknown name is an error that lists the templates you configured:
---
title: Writing docs
template: blog
---Error Unknown template "blog" from frontmatter. Known templates: default, docs (frontmatter line 3)
select_template runs for documents whose frontmatter has no template key. It gets the file path and the metadata. It returns a template name, false for none, or undefined to fall through to default:
mdsvex({
templates: {
default: '#lib/templates/Post.svelte',
docs: '#lib/templates/Docs.svelte'
},
select_template: (id) =>
id.includes('/changelog/') ? false : id.includes('/docs/') ? 'docs' : undefined
});compile and compile_async take the same select_template, with the compile's filename as the path:
compile(source, {
filename: '/site/docs/intro.svx',
templates,
select_template: (id) => (id?.includes('/docs/') ? 'docs' : undefined)
});- A compile without a
filenamepassesundefinedas the path, so a callback shared with the Vite plugin reads it withid?..
Opting out
template: false in the frontmatter renders a document without one:
---
template: false
---<script module>
export const metadata = {
template: false,
};
</script> To choose for one import only, add ?template= to it. ?template=false unwraps the document and ?template=docs picks another template. The query wins over the frontmatter:
<script>
import Intro from './intro.svx?template=false';
</script>
<Intro />TypeScript can't resolve an import with a query of its own, so a ?template= import needs a declaration in the project, see types for these imports.
Template props
A template gets:
- every frontmatter key as its own prop, so
let { title } = $props()readstitle; plugin_data, what the plugins left for the document, when they left any (see plugin data);children, a snippet that renders the document;- the props passed to the document, so
<Post featured />reaches the template asfeatured.
---
title: Hello
---
# Hello<script module>
export const metadata = {
title: 'Hello',
};
</script>
<script>
import Template_MDSVEX from '#lib/templates/Post.svelte';
let __mdsvex_props = $props();
</script>
<Template_MDSVEX
{...metadata}
{...__mdsvex_props}
><h1>Hello</h1></Template_MDSVEX
> A document that reads its own props with let props = $props() still forwards them all to its template. If it destructures them, let { featured } = $props(), it forwards none, as $props() can only be called once.
- The frontmatter can't have a
childrenkey when the document has a template, nor aplugin_datakey when its plugins left data. Each is an error that points at the line:
---
title: Hello
children: none
---
# HelloError The frontmatter key children collides with the children of template "default", rename it (frontmatter line 3)
What gets hoisted
Some things only work at the top level of a component, so they stay outside the template:
<script>and<script module>;<style>;<svelte:head>,<svelte:window>,<svelte:body>,<svelte:document>and<svelte:options>.
---
title: Hello
---
<svelte:head>
<title>Hello</title>
</svelte:head>
# Hello
<style>
h1 { color: tomato }
</style><script module>
export const metadata = {
title: 'Hello',
};
</script>
<script>
import Template_MDSVEX from '#lib/templates/Post.svelte';
let __mdsvex_props = $props();
</script>
<svelte:head
><title>Hello</title></svelte:head
><Template_MDSVEX
{...metadata}
{...__mdsvex_props}
><h1>Hello</h1></Template_MDSVEX
>
<style>
h1 {
color: tomato;
}
</style> Everything else, markdown, HTML and components alike, is the document body that the template renders as children.