Blueprints

Blueprints are dope. They allow you to define a set of plugins, a component to render your markdown files in, and custom components to use in place of the default prose elements.

Blueprint Configuration

Blueprints are configured in the blueprints property of your MDSXConfig, which is created using the defineConfig function.

Here's an example of what your blueprint configuration might look like:

	import { defineConfig } from 'mdsx';
import rehypeSlug from 'rehype-slug';
import remarkGfm from 'remark-gfm';
import remarkCapitalize from 'remark-capitalize';
import rehypePrettyCode from 'rehype-pretty-code';
import rehypeToc from 'rehype-toc';
 
export const mdsxConfig = defineConfig({
	extensions: ['.md'],
	remarkPlugins: [remarkGfm],
	rehypePlugins: [rehypeSlug],
	blueprints: {
		default: {
			rehypePlugins: [rehypePrettyCode],
			path: 'src/lib/blueprints/default/blueprint.svelte',
		},
		blog: {
			remarkPlugins: [remarkCapitalize],
			rehypePlugins: [rehypeToc],
			path: 'src/lib/blueprints/blog/blueprint.svelte',
		},
	},
});	

We have two blueprints defined here, default and blog. The default blueprint will be used for any markdown files that don't specify a blueprint in their frontmatter. blog is a named blueprint that will be applied to markdown files that specify blueprint: blog in their frontmatter.

Plugins

The plugins specified in the remarkPlugins and rehypePlugins properties of your blueprint configuration will only be applied to any markdown files that use that blueprint.

Path

The path property specifies the path to the blueprint component that your markdown files will be rendered inside of. You can learn more about the blueprint component below.

Blueprint Component

The blueprint component acts as a wrapper (or layout) for the markdown files associated with it, meaning the content of the markdown file will be rendered inside its slot. It also has a few other features that make it really powerful, which we'll cover below.

Frontmatter / Metadata

The blueprint component receives a metadata prop that contains the frontmatter from the markdown file being rendered.

So if you had a collection of markdown files that had frontmatter like this:

	---
title: My Markdown File
description: This is my markdown file.
coverImage: /images/cover.jpg
---	

You could setup your blueprint to handle rendering the title, description, and cover image:

	<script lang="ts">
	export let metadata: {
		title: string;
		description: string;
		coverImage: string;
	};
</script>
 
<img src={metadata.coverImage} alt={metadata.title} />
<h1>{metadata.title}</h1>
<p>{metadata.description}</p>
 
<!-- Markdown contents would be rendered in the slot -->
<slot />	

Custom Components

Blueprints can also export components. These will be used to override the default prose elements when your markdown file is rendered.

For example, if we had the following markdown file:

	# My Markdown File
 
This is my markdown file.
 
## Get Started
 
[Click here to get started](/docs/get-started)	

By default, the titles would be rendered as h1 and h2 elements, the paragraph would be rendered as a p element, and the link would be rendered as an a element.

If you wanted to use a custom component instead, you can do so by exporting a component with the same name as the element you want to replace from the <script context="module"> tag of your blueprint component.

Here's how we could override the h1, h2, p, and a elements from the example above:

	<script lang="ts" context="module">
	export { default as h1 } from '$lib/components/h1.svelte';
	export { default as h2 } from '$lib/components/h2.svelte';
	export { default as p } from '$lib/components/p.svelte';
	export { default as a } from '$lib/components/a.svelte';
</script>
 
<slot />	

Now, when the markdown file is rendered, the h1, h2, p, and a elements will be replaced with the components we exported from our blueprint component, allowing us to extend their functionality beyond what the default elements provide.

If you want to take a more in-depth look at how to create custom components for your blueprints, check out the External Links recipe, which walks through creating a dynamic link component that automatically handles external links.

Using Blueprints

Once you have your blueprint(s) defined, you can use them by specifying the blueprint property in the frontmatter of your markdown files.

For example, consider the following blueprint configuration:

	import { defineConfig } from 'mdsx';
 
export const mdsxConfig = defineConfig({
	extensions: ['.md'],
	blueprints: {
		default: {
			path: 'src/lib/blueprints/default/blueprint.svelte',
		},
		blog: {
			path: 'src/lib/blueprints/blog/blueprint.svelte',
		},
	},
});	

Default Blueprint

The default blueprint will be used for any markdown files that don't specify a blueprint in their frontmatter.

Using the example above, if we had a markdown file with the following frontmatter:

	---
title: My Markdown File
description: This is my markdown file.
---	

The default blueprint would be used for this file.

Named Blueprints

The blueprint's name is the property name from the blueprints object in your MDSXConfig. For the example above, the default blueprint's name is default and the blog blueprint's name is blog.

Here's how we could use the blog blueprint for a markdown file:

	---
title: My Markdown File
description: This is my markdown file.
blueprint: blog
---	

Opting Out of Blueprints

There are times when the default blueprint covers all but one or two of your markdown files. In these cases, you can opt out of using a blueprint entirely by setting blueprint: false in the frontmatter.

	---
title: My Markdown File
description: This is my markdown file.
blueprint: false
---	

Now, the default blueprint nor any other blueprint will be used for this file.