Guides Templates

Source

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.

Name your templates in the templates option:

vite.config.js
mdsvex({
	templates: {
		default: '#lib/templates/Post.svelte',
		docs: '#lib/templates/Docs.svelte'
	}
});
You write src/routes/hello/+page.svx
---
title: Hello
date: 2026-11-02
---

# Hello

A post.
You get
Compiles to
<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()}:

src/lib/templates/Post.svelte
<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.

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:

You write src/lib/templates/Note.svx
<script>
	let { title, children } = $props();
</script>

# {title}

{@render children()}

Written by the _docs team_.
You get
Compiles to
<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 template key in its frontmatter, select_template and the default entry don't apply to it.

mdsvex picks a document's template from the first of these that gives an answer:

  1. The ?template= query on the import, see opting out.
  2. The template key in the frontmatter, a template name or false.
  3. select_template(id, metadata), if you configured one.
  4. The default entry in templates.
  5. Otherwise, no template.
You write
---
title: Writing docs
template: docs
---
You get
Compiles to
<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:
You write
---
title: Writing docs
template: blog
---
Its compile throws

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 filename passes undefined as the path, so a callback shared with the Vite plugin reads it with id?..

template: false in the frontmatter renders a document without one:

You write
---
template: false
---
You get
Compiles to
<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.

A template gets:

  • every frontmatter key as its own prop, so let { title } = $props() reads title;
  • 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 as featured.
You write
---
title: Hello
---

# Hello
You get
Compiles to
<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 children key when the document has a template, nor a plugin_data key when its plugins left data. Each is an error that points at the line:
You write
---
title: Hello
children: none
---

# Hello
Its compile throws

Error The frontmatter key children collides with the children of template "default", rename it (frontmatter line 3)

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>.
You write
---
title: Hello
---

<svelte:head>
	<title>Hello</title>
</svelte:head>

# Hello

<style>
	h1 { color: tomato }
</style>
You get
Compiles to
<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.

mdsvex, markdown with Svelte in it. MIT licence.