https://github.com/brillout/vite-plugin-mdx

Vite Plugin for MDX
https://github.com/brillout/vite-plugin-mdx

Last synced: about 2 months ago
JSON representation

Vite Plugin for MDX

• Host: GitHub
• URL: https://github.com/brillout/vite-plugin-mdx
• Owner: brillout
• License: mit
• Created: 2021-02-02T19:37:28.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-05-06T00:46:50.000Z (5 months ago)
• Last Synced: 2024-07-20T08:52:47.921Z (2 months ago)
• Language: TypeScript
• Size: 832 KB
• Stars: 111
• Watchers: 7
• Forks: 36
• Open Issues: 7
• Metadata Files:
  • Readme: readme.md
  • License: license.md

Awesome Lists containing this project

README

        
====================== [**WE ARE LOOKING FOR A NEW MAINTAINER**](https://github.com/brillout/vite-plugin-mdx/issues/42) ====================

# Vite Plugin MDX

Use this Vite plugin to use MDX v1 with your Vite v2 app. For Vite v3+ we recommend migrating to MDX v2 using the official [`@mdx-js/rollup`](https://www.npmjs.com/package/@mdx-js/rollup), [this comment](https://github.com/brillout/vite-plugin-mdx/issues/44#issuecomment-974540152) explains how to implement it.

Features:

- Works with React and Preact.

- Works with Vue [**[WIP]**](https://github.com/brillout/vite-plugin-mdx/issues/3).

- HMR support.

- SSR support.

- Plugin support, such as [remark-frontmatter](https://github.com/remarkjs/remark-frontmatter).

## Getting Started

1. Install:

   1. Vite Plugin:

      ```sh

       npm install vite-plugin-mdx

      ```

   2. MDX v1:

      ```sh

      npm install @mdx-js/mdx

      ```

   3. MDX React:

      ```sh

      npm install @mdx-js/react

      ```

      Or MDX Preact:

      ```sh

      npm install @mdx-js/preact

      ```

2. Add the plugin to your `vite.config.js`.

   ```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.

   ```mdx-js

   // 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: 

   ```

   ```jsx

   // Counter.jsx

   import React, { useState } from 'react'

   export { Counter }

   function Counter() {

     const [count, setCount] = useState(0)

     return (

        setCount((count) => count + 1)}>

         Counter: {count}

       

     )

   }

   ```

## Examples

- [React example](/examples/react/).

- [Preact example](/examples/preact/).

## File-specific options

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

```ts

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.

```mdx

import '../foo/bar.mdx'

```