This issue serves as a collaborative space for outlining requirements for MDX support in Netlify CMS.

Related to #1776.

Motivation

Netlify CMS works alongside static site generators (SSG's), which cater heavily toward Markdown as a content format. MDX is a superset of Markdown that uses JSX components for dynamic content, an approach already made viable by JavaScript based SSG's like Gatsby and Next.js, and validated in many real world projects. Netlify CMS should serve as an enabler for MDX projects with non-technical content editors.

Design

MDX authoring will happen in the existing markdown widget. The widget has "Rich Text" and "Markdown" modes, the former providing a WYSIWYG experience and the latter providing direct editing of the underlying markdown. Both modes edit the same value and output Markdown. The Markdown editor also provides an extensible list of Editor Components, which are used to output shortcodes. This same mechanism should be used for JSX component authoring.

Imports

MDX support must be handled at the format level. Netlify CMS currently supports data files, such as JSON and YAML, as well as Markdown with frontmatter. MDX introduces import statements before the frontmatter that Netlify CMS will have to parse, or at a minimum, ignore.

Exports

If possible, export statements should be ignored through reads and writes, but not used in any way, nor made editable.

Registering Components

We can allow components to be registered using the existing registerEditorComponent method. A simplistic approach would be to accept a unique name and the related React component, and then match via tag name. This is similar to what Gatsby is doing. The downside to this approach is that component names must be unique across a project. We could use configuration to limit this to a per-collection requirement, but I suspect uniqueness across the project may be tolerable for our initial support model.

Potential registration example for this approach:

import CMS from 'netlify-cms'
import YouTube from 'src/components/YouTube'

{
  componentName: "YouTube",
  label: "YouTube",
  fields: [{ name: 'id', label: 'Youtube Video ID', widget: 'string' }],
  component: YouTube,
}

Previewing Components

The component passed in at registration would be used in the preview pane (and potentially in the control pane in the future!), but we can make getting started even simpler by not requiring a component at all. If an MDX component does not have a registered preview component, we can list the name and properties of the component in the preview pane instead as a basic representation of the content.

Babel standalone will be required for rendering components parsed from an MDX document, which I've found to work well for CMS preview purposes, even in terms of performance. Haven't tested on very large docs, though.

Document handling

The Netlify CMS Markdown widget uses a document model that's powered by Unified via a heavily customized Remark/Rehype implementation for WYSIWYG markdown editing with live HTML previews. The UI is built with Slate, with the widget transforming MDAST to Slate's AST and back as necessary. MDX is now a part of Unified, and work is underway to support an MDXAST format that is highly compatible with the MDAST and HAST formats already in use in Netlify CMS.

The packages in the MDX repository should provide what we need to parse to/from MDAST, but more research is required to fully determine the path forward.