MDX Analyzer

This repository contains the code to provide editor tooling support for MDX.

Workspaces

This repository contains the following workspaces:

@mdx-js/language-service provides utilities to integrate MDX into
Volar.
@mdx-js/language-server provides an MDX language server using the
Language Server Protocol.
@mdx-js/typescript-plugin provides a TypeScript plugin to integrate
MDX in TypeScript editors.
vscode-mdx integrates the MDX language server into
Visual Studio Code, but also provides some Visual Studio Code specific
features such as syntax highlighting.

Use

TypeScript

MDX doesn’t support TypeScript syntax, but it does support types in JSDoc.

MDX type checking support is similar to JavaScript support. By default, type hints are subtle. To enable strict type checking, you need to specify mdx.checkMdx in tsconfig.json:

{
  "compilerOptions": {
    // …
  },
  "mdx": {
    // Enable strict type checking in MDX files.
    "checkMdx": true
  }
}

`Props`

The Props type is a special type which is used to determine the type used for props. For example:

{/**
  * @typedef Props
  * @property {string} name
  *   Who to greet.
  */}

# Hello {props.name}

`MDXProvidedComponents`

The special type MDXProvidedComponents is used to determine which components are provided. For example:

{/**
  * @typedef MDXProvidedComponents
  * @property {typeof import('../components/Planet.js').Planet} Planet
  */}

<Planet name="Earth" />

You can also define this type externally, and import it into your MDX file. Based on a Next.js example:

// mdx-components.ts
import { Planet } from './components/Planet.js'

const components = {
  Planet
}

export type MDXProvidedComponents = typeof components

export function useMDXComponents(): MDXProvidedComponents {
  return components
}

Then in your MDX file:

{/**
  * @import {MDXProvidedComponents} from '../mdx-components.js'
  */}

<Planet name="Earth" />

Another alternative is to define the MDXProvidedComponents type globally. This way you don’t have to define MDXProvidedComponents in each MDX file. Based on a Next.js example:

// mdx-components.ts
import { Planet } from './components/Planet.js'

const components = {
  Planet
}

declare global {
  type MDXProvidedComponents = typeof components
}

export function useMDXComponents(): MDXProvidedComponents {
  return components
}

Now you can write the following MDX with full type safety anywhere:

<Planet name="Earth" />

Plugins

This extension supports remark parser plugins. Plugins can be defined in an array of strings or string / options tuples. These plugins can be defined in tsconfig.json and will be resolved relative to that file. Transformers such as remark-mdx-frontmatter are not supported yet. Support is tracked in #297.

For example, to support frontmatter with YAML and TOML and GFM:

{
  "compilerOptions": {
    // …
  },
  "mdx": {
    "plugins": [
      [
        "remark-frontmatter",
        ["toml", "yaml"]
      ],
      "remark-gfm"
    ]
  }
}

For a more complete list, see remark plugins.