Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mdx-js/mdx-analyzer

MDX extension for Visual Studio Code
https://github.com/mdx-js/mdx-analyzer

intellisense mdx mdx-js vscode vscode-extension vscode-mdx

Last synced: 4 days ago
JSON representation

MDX extension for Visual Studio Code

Host: GitHub
URL: https://github.com/mdx-js/mdx-analyzer
Owner: mdx-js
License: mit
Created: 2019-07-30T08:43:18.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2025-01-03T12:47:51.000Z (18 days ago)
Last Synced: 2025-01-10T14:08:12.543Z (11 days ago)
Topics: intellisense, mdx, mdx-js, vscode, vscode-extension, vscode-mdx
Language: JavaScript
Homepage: https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx
Size: 1.66 MB
Stars: 359
Watchers: 12
Forks: 21
Open Issues: 20
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

        # MDX Analyzer

[![Build][build-badge]][build]

[![Coverage][coverage-badge]][coverage]

[![Sponsors][sponsors-badge]][collective]

[![Backers][backers-badge]][collective]

[![Chat][chat-badge]][chat]

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

## Contents

* [Workspaces](#workspaces)

* [Use](#use)

  * [TypeScript](#typescript)

  * [Plugins](#plugins)

* [Contribute](#contribute)

* [Sponsor](#sponsor)

* [License](#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][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`:

```jsonc

{

  "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`][props].

For example:

```mdx

{/**

  * @typedef Props

  * @property {string} name

  *   Who to greet.

  */}

# Hello {props.name}

```

#### `MDXProvidedComponents`

The special type `MDXProvidedComponents` is used to determine which components

are [provided][provider].

For example:

```mdx

{/**

  * @typedef MDXProvidedComponents

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

  */}

```

You can also define this type externally, and import it into your MDX file.

Based on a [Next.js][next mdx] example:

```typescript

// 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:

```mdx

{/**

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

  */}

```

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][next mdx] example:

```typescript

// 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:

```mdx

```

### 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`][remark-mdx-frontmatter] are not

supported yet.

Support is tracked in

[#297](https://github.com/mdx-js/mdx-analyzer/issues/297).

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

```jsonc

{

  "compilerOptions": {

    // …

  },

  "mdx": {

    "plugins": [

      [

        "remark-frontmatter",

        ["toml", "yaml"]

      ],

      "remark-gfm"

    ]

  }

}

```

For a more complete list, see [remark plugins][].

## Contribute

See [§ Contribute][contribute] on our site for ways to get started.

See [§ Support][support] for ways to get help.

This project has a [code of conduct][coc].

By interacting with this repository, organization, or community you agree to

abide by its terms.

## Sponsor

See [§ Sponsor][sponsor] on our site for how to help financially.

  Vercel



  

  Motif



  

  HashiCorp



  

  GitBook



  

  Gatsby



  

  Netlify



  

  

  Coinbase



  

  ThemeIsle



  

  Expo



  

  Boost Note



  

  Markdown Space



  

  Holloway



  

  


  You?

  



## License

[MIT][] © [JounQin][]@[1stG.me][]

[`@mdx-js/language-server`]: https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server

[`@mdx-js/language-service`]: https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-service

[`@mdx-js/typescript-plugin`]: https://github.com/mdx-js/mdx-analyzer/tree/main/packages/typescript-plugin

[`vscode-mdx`]: https://github.com/mdx-js/mdx-analyzer/tree/main/packages/vscode-mdx

[1stg.me]: https://www.1stg.me

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[build-badge]: https://github.com/mdx-js/mdx-analyzer/workflows/main/badge.svg

[build]: https://github.com/mdx-js/mdx-analyzer/actions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[chat]: https://github.com/mdx-js/mdx/discussions

[coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md

[collective]: https://opencollective.com/unified

[contribute]: CONTRIBUTING.md

[coverage-badge]: https://img.shields.io/codecov/c/github/mdx-js/mdx-analyzer/main.svg

[coverage]: https://codecov.io/github/mdx-js/mdx-analyzer

[frontmatter]: https://github.com/remarkjs/remark-frontmatter

[gfm]: https://github.com/remarkjs/remark-gfm

[jounqin]: https://GitHub.com/JounQin

[jsdoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

[language server protocol]: https://microsoft.github.io/language-server-protocol/

[mdx]: https://github.com/mdx-js/mdx

[mit]: http://opensource.org/licenses/MIT

[next mdx]: https://nextjs.org/docs/pages/building-your-application/configuring/mdx

[props]: https://mdxjs.com/docs/using-mdx/#props

[provider]: https://mdxjs.com/docs/using-mdx/#mdx-provider

[remark plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md

[remark-mdx-frontmatter]: https://github.com/remcohaszing/remark-mdx-frontmatter

[sponsor]: https://mdxjs.com/community/sponsor/

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[support]: https://mdxjs.com/community/support/

[typescript plugin]: https://www.typescriptlang.org/tsconfig#plugins

[visual studio code]: https://code.visualstudio.com/

[volar]: https://volarjs.dev