A guide to building interactive documents with MDX.

MDX is a combination of Markdown and JSX, enabling you to seamlessly combine content with code. Here is a simple MDX document showing how code and content elegantly weave together:

A pie chart

import { useEffect, useRef } from "react"
import * as d3 from "d3"

# A pie chart

<Pie />

export const Pie = () => {
  const ref = useRef()
  useEffect(() => {
    const size = 200
    const data = [2, 4, 8, 10, 12]
    const svg =
      .attr("width", size)
      .attr("height", size)
    const g = svg.append("g")
      .attr("transform", `translate(${size / 2}, ${size / 2})`)
    const color = d3.scaleOrdinal(d3.schemeCategory10)
    const pie = d3.pie()
    const arc = d3.arc().innerRadius(0).outerRadius(size/2)
    const arcs = g.selectAll("arc")
      .attr("class", "arc")
      .attr("fill", (d, i) => color(i))
      .attr("d", arc)
  }, [])
  return <div ref={ref} />

Unlike a plain Markdown document, an MDX document is not static. In fact, it is a full-fledged JavaScript program. For instance, JavaScript variables and expressions are supported, as well as functions and JSX components.


With JSX, you can create components that encapsulate logic and state, and easily reuse them throughout your pages.

Read more about this in the JSX article →

ES module imports

Motif supports ES modules and URL imports, which allow you to bring in components and code from outside the document. This is convenient when you want to use the same component in several pages (such as a navigation bar), or if you want to use a JavaScript package from the Internet, such as React, D3.js or Luxon.

import DateTime from "luxon"
import Navbar from '@components/navbar'

<Navbar />

Today's date: {}


Every page on Motif is also a JSX component, so you can even use imports to include content from another page, so-called transclusions.

import Page1, { title } from "@pages/page1"

# {title}

<Page1 />

ES modules add incredible possibilities to your pages, as you can leverage the full power of the web ecosystem without any further setup. Read more about them in the ES Modules article →

You can read more about MDX on the official documentation.