Learn Quick start

Source

Install the prerelease as a development dependency.

npm
npm i --save-dev mdsvex@next

mdsvex needs Svelte 5 and Vite 6 or later.

mdsvex is a Vite plugin. It turns markdown files into Svelte components, and the Svelte plugin compiles them like any other component.

Add mdsvex to your Vite config:

vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { mdsvex } from 'mdsvex';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [mdsvex({ extensions: ['.svx', '.md'] }), sveltekit()]
});

Declare the extensions in mdsvex(). It registers them with SvelteKit, so you don't repeat them in sveltekit({ extensions }). Order doesn't matter.

Any markdown file is now a component, and a +page.svx is a route:

src/routes/
├── +page.svelte
└── blog/
    └── hello/
        └── +page.svx

When using @sveltejs/vite-plugin-svelte, add the extensions to svelte() as well. mdsvex can't register them there.

vite.config.js
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { mdsvex } from 'mdsvex';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [mdsvex(), svelte({ extensions: ['.svelte', '.svx'] })]
});
  • If one is missing, the build errors explaining the problem.

Options that point at a file, such as templates and components, resolve the way an import from your project root would. That includes aliases, packages, relative paths and SvelteKit 3's #lib subpath imports:

{
	"imports": {
		"#lib/*": "./src/lib/*"
	}
}
mdsvex({
	templates: { default: '#lib/templates/Post.svelte' }
});

Imports inside a document work the same way, import Chart from '#lib/Chart.svelte'.

  • Subpath imports need the file extension.

Fenced code is highlighted by default, with twinkleplop. mdsvex adds no CSS, so install a theme and import it once, in your root layout:

npm
npm i --save-dev @twinkleplop/theme-github
src/routes/+layout.svelte
<script>
	import '@twinkleplop/theme-github';

	let { children } = $props();
</script>

{@render children()}

Without a theme, code renders in one colour. The theme gives light colours, and dark ones under a .dark class. To follow the reader's system setting instead, see themes.

mdsvex, markdown with Svelte in it. MIT licence.