Usage with Vite

vite-plugin-satteri lets you import Markdown and MDX files directly in a Vite project. .md imports give you the rendered HTML; .mdx imports give you a JSX component. YAML or TOML frontmatter comes through parsed as a named export either way.

#Link to this headingInstall

pnpm add -D vite-plugin-satteri satteri

npm install --save-dev vite-plugin-satteri satteri

yarn add -D vite-plugin-satteri satteri

bun add --dev vite-plugin-satteri satteri

satteri is a peer dependency, so install it alongside the plugin.

#Link to this headingConfigure

Add the plugin to vite.config.ts:

import { defineConfig } from "vite";
import satteri from "vite-plugin-satteri";

export default defineConfig({
  plugins: [
    satteri({
      features: {
        gfm: true,
        frontmatter: true,
      },
    }),
  ],
});

That's the whole setup. Any .md or .mdx file in your project is now importable.

#Link to this headingImporting Markdown

A .md import gives you the rendered HTML as a string plus any parsed frontmatter (YAML between --- fences, or TOML between +++ fences):

import postHtml, { frontmatter } from "./post.md";

document.getElementById("post").innerHTML = postHtml;
console.log(frontmatter.title);

The default export and the named html export point at the same string, so pick whichever reads better at the call site.

#Link to this headingImporting MDX

An .mdx import is an ES module that exports a component. The JSX runtime follows whatever you configure in mdx.jsxImportSource:

import { defineConfig } from "vite";
import satteri from "vite-plugin-satteri";

export default defineConfig({
  plugins: [
    satteri({
      mdx: {
        jsxImportSource: "preact",
      },
    }),
  ],
});

Then in your app:

import { render } from "preact";
import Intro, { frontmatter } from "./intro.mdx";

render(<Intro />, document.getElementById("root"));

By default, the plugin compiles MDX with development: true in serve so React gives you useful component stacks, and switches to the production runtime in build. Override with mdx: { development: false }.

#Link to this headingOptions

MdxOptions mirrors Sätteri's MDX options minus outputFormat. The plugin always emits an ES module so Vite can import it.

Plugins given here apply to every Markdown and MDX file, unless an entry opts out of one. See What an entry can be for how a plugin limits itself to some files, and the Plugins guide for how to write them.

#Link to this headingTypeScript

TypeScript does not know by default what a .md or .mdx import resolves to.

Add a declaration file (e.g. src/satteri-modules.d.ts) in order to teach TypeScript:

declare module "*.md" {
  const html: string;
  const frontmatter: Record<string, unknown>;
  export default html;
  export { html, frontmatter };
}

declare module "*.mdx" {
  import type { ComponentType } from "preact";
  const MDXContent: ComponentType<Record<string, unknown>>;
  export const frontmatter: Record<string, unknown>;
  export default MDXContent;
}

Swap preact for react (or your framework of choice) to match your jsxImportSource.