Getting Started

The following guide will give you the bare minimum to start using MDSX in your project. Once up and running, head over to the Blueprints section to learn more about the powerful features MDSX has to offer.

Install MDSX

MDSX is published as an npm package, so you can install it using your favorite package manager.

		npm install mdsx -D
	

Create an MDSX Config

Create mdsx.config.js in the root of your project.

At a minimum, you must specify the extensions option to tell MDSX which file extensions to process. There are many other configuration options available, which you can learn more about in the MDSXConfig API reference.

		import { defineConfig } from 'mdsx';
 
export const mdsxConfig = defineConfig({
	extensions: ['.md'],
});
	

Update Svelte Config

You'll need to update your Svelte config to include MDSX as a preprocessor. You can do so by updating your svelte.config.js file to include the following:

		import adapter from '@sveltejs/adapter-cloudflare';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
import { mdsx } from 'mdsx';
import { mdsxConfig } from './mdsx.config.js';
 
/** @type {import('@sveltejs/kit').Config} */
const config = {
	preprocess: [mdsx(mdsxConfig), vitePreprocess()],
	extensions: ['.svelte', '.md'],
	kit: {
		adapter: adapter(),
	},
};
 
export default config;
	

Create Your First Markdown File

Create a markdown file anywhere in your project. For this example, we'll create src/lib/some-content.md.

		---
title: My First MDSX Page
description: Getting started with MDSX
---
 
<script>
	const message = 'Hello from Svelte!';
</script>
 
# Welcome!
 
This is my first MDSX markdown file. Isn't it great?
 
## Description
 
It gets better than this, we promise.
 
{message}
	

Use the Markdown File

You can now import and use this file as you would any other Svelte component.

		<script>
	import SomeContent from '$lib/some-content.md';
</script>
 
<SomeContent />
	

Test It Out

Start your development server and navigate to your page. You should see your markdown content rendered as a Svelte component!

		npm run dev
	

And just like that, you're up and running with MDSX! 🎉

What You Can Do Now

With this basic setup, you can:

• Write markdown files and import them as Svelte components
• Use frontmatter to add metadata to your content
• Embed Svelte components directly in your markdown
• Use Svelte logic in markdown

Next Steps

This quick start guide doesn't even scratch the surface of what's possible with MDSX. Here's what we recommend exploring next:

Essential Features

• Blueprints - Create reusable layouts and component overrides
• Frontmatter - Learn how to work with metadata
• Custom Components - Replace default HTML elements with custom components