Skip to content

Latest commit

 

History

History
119 lines (89 loc) · 2.33 KB

readme.md

File metadata and controls

119 lines (89 loc) · 2.33 KB

Vite Plugin MDX

Vite plugin to use MDX with your Vite app.

Features:

  • Works with MDX v1 and MDX v2.
  • Works with React and Preact.
  • Works with Vue [WIP].
  • HMR support.
  • SSR support.
  • Plugin support, such as remark-frontmatter.

Getting Started

  1. Install:

    1. Vite Plugin:
       npm install vite-plugin-mdx
    2. MDX v1:
      npm install @mdx-js/mdx
      Or MDX v2:
      npm install @mdx-js/mdx@next
    3. MDX React:
      npm install @mdx-js/react
      Or MDX Preact:
      npm install @mdx-js/preact
  2. Add the plugin to your vite.config.js.

    // vite.config.js
    
    import mdx from 'vite-plugin-mdx'
    
    // `options` are passed to `@mdx-js/mdx`
    const options = {
      // See https://mdxjs.com/advanced/plugins
      remarkPlugins: [
        // E.g. `remark-frontmatter`
      ],
      rehypePlugins: [],
    }
    
    export default {
      plugins: [mdx(options)]
    }
  3. You can now write .mdx files.

    // hello.mdx
    
    import { Counter } from './Counter.jsx'
    
    # Hello
    
    This text is written in Markdown.
    
    MDX allows Rich React components to be used directly in Markdown: <Counter/>
    
    // Counter.jsx
    
    import React, { useState } from 'react'
    
    export { Counter }
    
    function Counter() {
      const [count, setCount] = useState(0)
    
      return (
        <button onClick={() => setCount((count) => count + 1)}>
          Counter: {count}
        </button>
      )
    }

Examples

File-specific options

To define options a per-file basis, you can pass a function to the mdx plugin factory.

mdx((filename) => {
  // Any options passed to `mdx` can be returned.
  return {
    remarkPlugins: [
      // Enable a plugin based on the current file.
      /\/components\//.test(filename) && someRemarkPlugin,
    ]
  }
})

Pre-built transclusion

To embed an .mdx or .md file into another, you can import it without naming its export. The file extension is required. Remark plugins are applied to the imported file before it's embedded.

import '../foo/bar.mdx'