MDX Analyzer

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

Contents

• Workspaces
• Use
  • TypeScript
  • Plugins
• Contribute
• Sponsor
• License

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.

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.

License

MIT © JounQin@1stG.me