vite-plugin-svelte-md

Markdown with Svelte for Vite

vite-plugin-svelte-md is heavily inspired by vite-plugin-md package.

📛 Features

This plugin converts markdown files to Svelte component templates. Combined with the Svelte plugin, you can convert markdown files to Svelte components.

For example, Input:

---
title: Markdown to Svelte
---

# Convert Markdown to Svelte Component

- List
- List
- List

<script>
    import MyComponent from './MyComponent.svelte'
</script>

<MyComponent>You can use Svelte components in Markdown</MyComponent>

Output:

<script context="module">
  export const frontmatter = { title: "Markdown to Svelte" };
</script>

<script>
  import MyComponent from "./MyComponent.svelte";
</script>

<svelte:head>
  <title>Markdown to Svelte</title>
  <meta property="og:title" content="Markdown to Svelte" />
</svelte:head>

<div class="markdown-body">
  <h1>Convert Markdown to Svelte Component</h1>
  <ul>
    <li>List</li>
    <li>List</li>
    <li>List</li>
  </ul>

  <p>
    <MyComponent>You can use Svelte components in Markdown</MyComponent>
  </p>
</div>

💿 Installation

npm install --save-dev vite-plugin-svelte-md

📖 Usage

with Vite

Add it to vite.config.js

// vite.config.js
import { defineConfig } from "vite";
import { svelte } from "@sveltejs/vite-plugin-svelte";
import svelteMd from "vite-plugin-svelte-md";

export default defineConfig({
  plugins: [
    svelteMd(), // <--
    svelte({
      extensions: [".svelte", ".md"], // <--
    }),
  ],
});

with SvelteKit

Edit svelte.config.js

// svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
  extensions: [".svelte", ".md"], // <--
};

Add it to vite.config.js

// vite.config.js
import { defineConfig } from "vite";
import { sveltekit } from "@sveltejs/kit/vite";
import svelteMd from "vite-plugin-svelte-md";

export default defineConfig({
  plugins: [
    svelteMd(), // <--
    sveltekit(),
  ],
});

Options

import svelteMd from "vite-plugin-svelte-md";
svelteMd({
  headEnabled: true,
  markdownItOptions: {},
  use: (md) => { /* ... */ },
  markdownItUses: [],
  wrapperClasses: "markdown-body",
});

headEnabled

Enables head tag generation from frontmatter. The default is true.

markdownItOptions

markdown-exit's option. See markdown-exit's docs for more details.

markdown-exit is a TypeScript rewrite of markdown-it, designed as a drop-in replacement. The name markdownItOptions was preserved for backwards compatibility.

use

A hook to register markdown-exit or markdown-it plugins, in a type-safe way.

Example:

svelteMd({
  use: (md) => md.use(plugin1).use(plugin2, options),
});

Note: you may encounter benign type errors when using markdown-it plugins that are not yet compatible with markdown-exit.

markdownItUses

An array of markdown-exit or markdown-it plugins.

Example:

svelteMd({
  markdownItUses: [require("markdown-it-anchor"), require("markdown-it-prism")],
});

You should favor use over markdownItUses as it enables better auto-completion and type-safety.

wrapperClasses

The class name of the div that wraps the content.

🎏 Comparison

vite-plugin-svelte-md is not the only library that converts Markdown to Svelte components:

🍊 Svelte Compatibility

You might encounter issues with markdown-it plugins that produce invalid Svelte code, e.g. a TeX plugin that outputs unescaped { and } characters. In this case, the simplest workaround is to wrap the plugin output in a Svelte {@html ...} tag:

import { tex } from '@mdit/plugin-tex';
import katex from 'katex';

mdSvelte({
  use: (md) =>
    md.use(tex, {
      // `katex.renderToString` produces HTML with unescaped `{` and `}` characters,
      // wrap its output with {@html JSON.stringify(...)} to avoid Svelte parsing errors.
      render: (content, displayMode) =>
        `{@html ${JSON.stringify(katex.renderToString(content, { displayMode }))}}`,
    }),
});

:beers: Contributing

Welcome contributing!

Please use GitHub's Issues/PRs.

:lock: License

See the LICENSE file for license rights and limitations (MIT).