Skip to content
/ mdx Public
forked from mdx-js/mdx

JSX in Markdown for ambitious projects

License

Notifications You must be signed in to change notification settings

javdl/mdx

 
 

Repository files navigation

Logo

Build Status Join the community on Spectrum

MDX is a JSX in Markdown loader, parser, and renderer for ambitious projects. It combines the readability of Markdown with the expressivity of JSX. The best of both worlds. 🌐

See the MDX specification

Features

  • Fast
  • No runtime compilation
  • Pluggable
  • Element to React component mapping
  • React component import/export
  • Simpler image syntax
  • Webpack loader

Watch some of these features in action

Installation

npm install --save-dev @mdx-js/loader @mdx-js/mdx

Note: mdx requires a version of node that is >= v8.5

Configuring with Webpack

You'll need to specify the @mdx-js/loader webpack loader and follow it with the babel-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.md$/,
        use: ['babel-loader', '@mdx-js/loader']
      }
    ]
  }
}

Examples

Configuring with Parcel

You'll need to install the @mdx-js/parcel-plugin-mdx plugin to transpile MDX.

{
  "scripts": {
    "start": "parcel index.html --no-cache"
  },
  "dependencies": {
    "react": "16.4.1",
    "react-dom": "16.4.1",
    "@mdx-js/tag": "latest"
  },
  "devDependencies": {
    "@mdx-js/parcel-plugin-mdx": "latest",
    "parcel-bundler": "1.9.0"
  }
}

Examples

Configuring TypeScript

If you're getting errors from TypeScript related to imports with an *.mdx extension, create an mdx.d.ts file in your types directory and include inside your tsconfig.json

// types/mdx.d.ts
declare module '*.mdx' {
  let MDXComponent: (props) => JSX.Element;
  export default MDXComponent;
}

Usage

Create an md file, hello.md:

# Hello, world!

And import it from a component, pages/index.js:

import React from 'react'
import Hello from '../hello.md'

export default () => <Hello />

MDX syntax

Imports

Similarly to JSX, components can be rendered after an import:

import Graph from './components/graph'

## Here's a graph

<Graph />

Markdown file transclusion

You can transclude Markdown files by importing one .md file into another:

import License from './license.md'
import Contributing from './docs/contributing.md'

# Hello, world!

<License />

---

<Contributing />

Exports

You can use exports to export metadata like layout or authors. It's a mechanism for an imported MDX file to communicate with its parent. It works similarly to frontmatter, but uses ES2015 syntax.

// posts/post.mdx
import { fred, sue } from '../data/authors'
import Layout from '../components/blog-layout'

export const meta = {
  authors: [fred, sue],
  layout: Layout
}

# Post about MDX

MDX is a JSX in Markdown loader, parser, and renderer for ambitious projects.
// index.js
import React from 'react'
import Mdx, { meta } from 'posts/post.mdx'

const { authors, layout } = meta

export default () => (
  <layout>
    <Mdx />
    By: {authors.map(author => author.name)}
  </layout>
)

export default

The ES default export is used to provide a layout component which will wrap the transpiled JSX.

You can export it as a function:

import Layout from './Layout'

export default ({children}) => <Layout some='metadata' >{children}</Layout>

# Hello, world!

Or directly as a component:

import Layout from './Layout'

export default Layout

# Hello, world!

Any additional props passed to the imported MDX component will be passed to its default export:

// index.js
import Mdx from './posts/post.mdx'

export default () => (
  <Mdx someProp="value" />
)
// posts/post.mdx
import Layout from '../components/blog-layout'

# Hello, world!

export default ({ children, someProp }) => <Layout someProp={someProp}>{children}</Layout>

Component customization

You can pass in components for any html element that Markdown compiles to. This allows you to use your existing components and use CSS-in-JS like styled-components.

import React from 'react'
import Hello from '../hello.md'

import {
  Text,
  Heading,
  Code,
  InlineCode
} from '../ui'

export default () =>
  <Hello
    components={{
      h1: Heading,
      p: Text,
      code: Code,
      inlineCode: InlineCode
    }}
  />

MDXProvider

If you're using an app layout that wraps your JSX, you can use the MDXProvider to only pass your components in one place:

import React from 'react'
import { MDXProvider } from '@mdx-js/tag'

import * as components from './markdown-components'

export default props =>
  <MDXProvider components={components}>
    <main {...props} />
  </MDXProvider>

Plugins

Since MDX uses the remark/rehype ecosystems, you can use plugins to modify the AST at different stages of the transpilation process.

If you look at the next example, it shows you to pass plugins as options to the MDX loader.

Options

Name Type Required Description
mdPlugins Array[] false Array of remark plugins to manipulate the MDXAST
hastPlugins Array[] false Array of rehype plugins to manipulate the MDXHAST
skipExport Boolean false Skip export default wrapper on transpiled JSX

Specifying plugins

Plugins need to be passed to the MDX loader via webpack options.

If a plugin needs specific options, use the [plugin, pluginOptions] syntax.

const images = require('remark-images')
const emoji = require('remark-emoji')
const toc = require('remark-toc')

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: 'babel-loader'
          },
          {
            loader: '@mdx-js/loader',
            options: {
              mdPlugins: [images, emoji, [toc, {heading: 'intro'}]]
            }
          }
        ]
      }
    ]
  }
}
Next.js

If you're using Next.js, you can specify options in your next.config.js.

const images = require('remark-images')
const emoji = require('remark-emoji')

module.exports = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx'],
  webpack: (config, { defaultLoaders }) => {
    config.module.rules.push({
      test: /\.md$/,
      use: [
        defaultLoaders.babel,
        {
          loader: '@mdx-js/loader',
          options: {
            mdPlugins: [images, emoji]
          }
        }
      ]
    })

    return config
  }
}

Sync API

If you're using the MDX library directly, you might want to process an MDX string synchronously.

const jsx = mdx.sync('# Hello, world!')

Related

See the related projects in the MDX specification

Authors

About

JSX in Markdown for ambitious projects

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%