mdx-js / mdx

Markdown for the component era

Markdown for the component era

MDX is an authorable format that lets you seamlessly write JSX in your markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast. 🚀

import {Chart} from './snowfall.js'
export const year = 2013

# Last year’s snowfall

In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.

<Chart year={year} color="#fcb32c" />

See § What is MDX for more info on the format. See § Playground to try it out.

What is this?

This GitHub repository contains several packages for compiling the MDX format to JavaScript, integrating with bundlers such as webpack and Rollup, and for using it with frameworks such as React, Preact, and Vue.

See § Getting started for how to integrate MDX into your project.

Security

See § Security on our site for information.

Contribute

See § Contribute on our site for ways to get started. See § Support for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Sponsor

See § Sponsor on our site for how to help financially.

Vercel		Motif		HashiCorp		GitBook		Gatsby
Netlify		Coinbase	ThemeIsle	Expo	Boost Note	Markdown Space	Holloway
		You?

License

MIT © Compositor and Vercel

mdx's Issues

Add back .jsx code block support

This will be, at least temporarily, required for more complex blocks of jsx due to limitations in parsing.

Write some real documentation

.md webpack loader

Implement parcel bundler plugin

HTML/JSX tags inside inlineCode gets parsed wrong

This breaks:

`<test>`

Improve mdxfmt (api + cli), document it

Add support for multiple imports in the same paragraph

Component rendering

GitHub style emoji support

Allow React rendering opt-out

Add a few more examples

JSX parsing bugs

children props are overridden

<Foo children='bar' />

Children prop is empty because the ast children attribute is used.

unnecessary p tags

<Foo>
  Bar
</Foo>

Results in

<h1>
  <p>Bar</p>
</h1>

complex jsx is borked

<Foo>
  <Bar
    children={props.bar.map(b =>
      <Baz key={b}>{b}</Baz>
    )}
  />
</Foo>

Perhaps stuff like this is where we introduce the .jsx code block back?

Expression based props error

<Foo color={'pink'} />

Errors with (in next example):

Error
Error
    at tokens.reduce.type (http://localhost:3000/_next/-/page/index.js:2090:19)
    at Array.reduce (<anonymous>)
    at parse (http://localhost:3000/_next/-/page/index.js:2084:23)
    at Of.parser (http://localhost:3000/_next/-/page/index.js:823:18)
    at Of.tokenize [as tokenizeBlock] (http://localhost:3000/_next/-/page/index.js:72636:18)
    at Of.parse (http://localhost:3000/_next/-/page/index.js:68441:20)
    at Function.parse (http://localhost:3000/_next/-/page/index.js:80537:45)
    at pipelineParse (http://localhost:3000/_next/-/page/index.js:80284:16)
    at wrapped (http://localhost:3000/_next/-/page/index.js:80139:19)
    at next (http://localhost:3000/_next/-/page/index.js:80102:24)

Parse imports with babel

Get test suite working again

• loader
• mdx
• mdxast
• remark-images
• tag

Render js/jsx files with support for getInitialProps

Pretty rendered snapshots

Option to specify LiveEditor css, with a couple options

• black on white
• white on black
• default styling for editor
• no stylesheet at all

Add example snapshotting as part of test suite when ready for 1.0

Implement basic cli

Add option for including table of contents for page

Add publish script to bump all packages, install deps, test and then publish to npm

Modify live editor wrapper to be a div rather than pre element

Allow multi-line jsx

Old:

<TerminalInput prefix>npm i next@latest react@latest react-dom@latest</TerminalInput>

<Caption>In addition to bumping Next.js etc...</Caption>

new:

<TerminalInput prefix>npm i next@latest react@latest react-dom@latest</TerminalInput>
<Caption>In addition to bumping Next.js etc...</Caption>

Consider how to align with the .mdx proposal

Some thoughts inspired by rauchg's .mdx proposal and an iteration on formalizing c8r/markdown.

Inlining JSX

This is a <Text.span>span</Text.span>.

Code blocks

Specifying .jsx as the language will render the React components.
You can also specify front matter which is passed as props to the components being rendered.

---
foo: bar
---
<Awesome>{props.foo}</Awesome>

Inlining JS

{new Date()}

Providing scope/element mapping

We need to be able to provide components, props,

Perhaps this can be done with a MarkdownProvider and ScopeProvider?

Implementation details

The following detauls need to be sorted out for a solid spec/implementation:

Mdast

Depending on what syntax we arrive at, we will need to transform the MD AST to render the desired components.

Interesting related projects/implementations:

• https://github.com/jamesknelson/mdxc
• https://github.com/andreypopp/reactdown

Loaders for webpack/parcel

import Post from './posts/proposal.mdx'

export default <Post />

Import syntax

Ideas:

• imports as the beginning of a mdx file
• using front matter

Pluggable

Similarly to how remark provides a pluggable API, we should also allow plugins to be passed in.
This allows further customization down the road, and also supporting the existing remark plugin ecosystem (toc, gh integrations, etc).

Linting and prettier

Code blocks and inlined js can be run through prettier at the mdast stage and then re-output to markdown.

I suspect the same will be possible with inlined JSX as well.

Input

Hello, <World some='prop' />

Output

Hello, <World some="prop" />

Convert tests to es6 to be consistent with lib code

MDX and MDXAST spec discussion

Use this to add any thoughts/criticisms/etc. to the MDX and MDXAST specs <3.

Improve tests

Add GitHub link options

Implement a MarkdownProvider

This will add a context that provides an element to component mapping, and any other globally available components.

As an example API, this will render Heading for the h1 element in readme.md.

import React from 'react'
import { MarkdownProvider } from '@compositor/markdown'

import { Heading } from './ui'

import Readme from './readme.md

export default () =>
  <MarkdownProvider components={{ h1: Heading }}>
    <Readme />
  </MarkdownProvider>

Add remark-slug

Benchmark factories vs components for JSX rendering

Add ability to override LiveEditor component

Implement inline jsx

Break out plugins into standalone libs

Move MDXTag into core library

File transclusion

Adds babel + yaml parser to the bundle

And a few other modules 😅

Handle layout key in frontmatter

After some discussion with @timneutkens and @jxnblk we think it makes most sense to allow layout to be optionally specified in frontmatter.

---
title: Awesome Page
slug: /awesome
layout: ./PageLayout
team:
  - jxn
  - mrmrs
  - johno
---

Resulting in, when layout is defined, the result would be something similar to:

import PageLayout from './PageLayout'

// ... stuff

export default PostLayout(frontmatter)(Markdown)

Something to consider: Should a layout be a HOC or standard component?

Add back live editor, no longer being called after new jsx implementation

Move non-react transclusion code to standalone remark-transclude module

import fs from 'fs'
import path from 'path'
import visit from 'unist-util-visit'
import { parse } from 'remark'

import {
  isTranscludable,
  isRelativeFile
} from './util'

export default () => (tree, file) =>
  visit(tree, 'text', (node, _i, parent) => {
    if (!isRelativeFile(node.value) || !isTranscludable(node.value)) {
      return
    }

    const index = tree.children.indexOf(parent)

    if (index === -1) {
      return
    }

    const transcludedFile = path.join(file.cwd, node.value)

    let content = null
    try {
      content = fs.readFileSync(transcludedFile, 'utf8')
    } catch (e) {
      console.log(`Error transcluding ${transcludedFile}`)
    }

    if (content) {
      tree.children = [].concat(
        tree.children.slice(0, index),
        parse(content).children,
        tree.children.slice(index + 1)
      )
    }
  })

Tweet embedding

Fix key error

In the renderer we should be adding a key prop, we currently aren't resulting in the following error:

Warning: Each child in an array or iterator should have a unique "key" prop

Allow ability to pass scope to MDX document

It'd be nice to be able pass in additional components and props to the component scope.

import React from 'react'
import { Box } from './ui'
import Document from './doc.md'

export default () => <Document scope={{ title: 'Hello', Box }} />

# This is some markdown

That has `Box` and `title` in scope:

<Box>{title}</Box>

Custom jsx block

In certain cases it'd be nice to be able to render jsx components directly, the components to be rendered need to be provided in scope.

Proposed syntax:

[[jsx]]
| <MyComponent
|   with={some}
|   props={here}
| />

Another possible syntax:

Using code blocks with a ! postfix:

```.jsx!
<MyComponent
  with={some}
  props={here}
/>
\```

Add ability to define front matter inside code blocks for rendering jsx

```!jsx
---
foo: bar
---
<h1>{foo}</h1>
\```

Convert .md links to .html

inlineCode parsed as code

If you create a file like:

# heading

hello `test`

It'll parse single quoted lines as code blocks instead of inlineCode as defined in the spec. I'm not sure if this is an issue with remark or mdxast 🤔

Add ability to pass in additional remark plugins

Add option to bundle (for cli)

Stringify exports in a more robust way

We're getting a few parsing edge cases pop up for
more complex exports:

• #84
• #85

Perhaps we can slice the original file using the remark positioning metadata?