This repository contains the code to provide editor tooling support for MDX.
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.
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
}
}
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}
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:
{/**
* @typedef {import('../mdx-components.js').MDXProvidedComponents} MDXProvidedComponents
*/}
<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" />
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.
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.
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? |