Unleash awesomeness. Private packages, team management tools, and powerful integrations. Get started with npm Orgs »

mdx.macro

0.2.7 • Public • Published

mdx.macro

Babel Macro

npm version

A babel macro for converting mdx into components, using the @mdx-js/mdx package.

Installation

Just install mdx.macro. It includes @mdx-js/mdx and @mdx-js/tag as dependencies.

npm install mdx.macro --save

Usage

You have three options for importing your MDX:

  • Dynamic import: importMDX('./document.mdx')
  • Synchronous import: importMDX.sync('./document.mdx')
  • The mdx tag: mdx`Create a **component** from a template literal`

Dynamic import

Returns a promise to a component, which can be used with React.lazy()

import { importMDX } from './mdx.macro'
 
const MyDocument = React.lazy(() => importMDX('./my-document.mdx'))
 
ReactDOM.render(
  <React.Suspense fallback={<div>Loading...</div>}>
    <MyDocument />
  </React.Suspense>,
  document.getElementById('root')
)

Works by creating a temporary file under your project's node_modules/.cache/mdx.macro directory, and importing that.

import { importMDX } from './mdx.macro'
 
const promiseToMyDocument = importMDX('./my-document.mdx')
 
      ↓ ↓ ↓ ↓ ↓ ↓
 
const promiseToMyDocument = import('.cache/mdx.macro/my-document.hash1234.mdx.js')

Synchronous import

Returns a component that can be used directly.

import { importMDX } from './mdx.macro'
 
const MyDocument = importMDX.sync('./my-document.mdx')
 
ReactDOM.render(
  <MyDocument />,
  document.getElementById('root')
)

Works by creating a temporary file under your project's node_modules/.cache/mdx.macro directory, and importing that.

import { importMDX } from './mdx.macro'
 
const MyDocument = importMDX.sync('./my-document.mdx')
 
      ↓ ↓ ↓ ↓ ↓ ↓
 
import _MyDocument from '.cache/mdx.macro/my-document.hash1234.mdx.js'
 
const MyDocument = _MyDocument

Tagged Template Literals

Replaces an mdx tagged template literal with a document component. It also adds an import for MDXTag, but doesn't add an import for React.

import { mdx } from './mdx.macro'
 
const MyDocument = mdx`
# Don't Panic
 
Since we decided a few weeks ago to adopt the leaf as legal tender, we have, of course, all become immensely rich.
`
 
      ↓ ↓ ↓ ↓ ↓ ↓
 
import { MDXTag } from '@mdx-js/tag'
 
const MyDocument = ({ components, ...props }) => (
  <MDXTag name="wrapper" components={components}>
    <MDXTag name="h1" components={components}>{`Don't Panic`}</MDXTag>
    <MDXTag name="p" components={components}>
      <MDXTag
        name="em"
        components={components}
        parentName="p"
      >{`Since we decided a few weeks ago to adopt the leaf as legal tender, we have, of course, all become immensely rich.`}</MDXTag>
    </MDXTag>
  </MDXTag>
)

Caveats

Currently, changes to imported files aren't detected, even within create-react-app. Any PR that fixes this would be welcome!

License

MIT

install

npm i mdx.macro

Downloadsweekly downloads

52

version

0.2.7

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability