# `@mdx-js/language-server` [![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Sponsors][sponsors-badge]][collective] [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] A [language server][lsp] for [MDX][]. ## Contents * [What is this?](#what-is-this) * [When should I use this?](#when-should-i-use-this) * [Install](#install) * [Use](#use) * [Language server features](#language-server-features) * [Initialize Options](#initialize-options) * [Configuration](#configuration) * [TypeScript](#typescript) * [Plugins](#plugins) * [Editors](#editors) * [Emacs](#emacs) * [Neovim](#neovim) * [Visual Studio Code](#visual-studio-code) * [Compatibility](#compatibility) * [Security](#security) * [Contribute](#contribute) * [Sponsor](#sponsor) * [Changelog](#changelog) * [License](#license) ## What is this? This package provides a [language server][lsp] for [MDX][]. The language server provides editor support based on [Volar][]. This includes support for [TypeScript][] as well as some MDX specific features. ## When should I use this? You can use this package if you want to enhance your editor for [MDX][] files with features such as autocomplete and error diagnostics. Some editors can consume this package directly, others need a plugin in order to consume this package. ## Install In Node.js (version 16+), install with [npm][]: ```sh npm install @mdx-js/language-server ``` ## Use How to use this package depends on your editor integration. This package provides the `mdx-language-server` CLI. Because this is based on [`vscode-languageserver`][vscode-languageserver], the same transports are supported. ### Language server features This language server supports all features supported by [`volar-service-markdown`][volar-service-markdown] and [`volar-service-typescript`][volar-service-typescript], plus some additional features specific to MDX. #### Commands The language server supports the following [LSP commands][]: ##### `mdx.toggleDelete` Toggle delete syntax at the cursor position. It uses the `workspace/applyEdit` command to apply edits. ###### Arguments * `uri` — The URI of the document to apply changes to. * `range` — The current selection range of the user. ###### Returns `null` ##### `mdx.toggleEmphasis` Toggle emphasis syntax at the cursor position. It uses the `workspace/applyEdit` command to apply edits. ###### Arguments * `uri` — The URI of the document to apply changes to. * `range` — The current selection range of the user. ###### Returns `null` ##### `mdx.toggleInlineCode` Toggle inline code syntax at the cursor position. It uses the `workspace/applyEdit` command to apply edits. ###### Arguments * `uri` — The URI of the document to apply changes to. * `range` — The current selection range of the user. ###### Returns `null` ##### `mdx.toggleStrong` Toggle strong syntax at the cursor position. It uses the `workspace/applyEdit` command to apply edits. ###### Arguments * `uri` — The URI of the document to apply changes to. * `range` — The current selection range of the user. ###### Returns `null` ### Initialize Options MDX language server supports the following LSP initialization options: * `typescript.enabled` (`boolean`, default: `false`) — If true, enable TypeScript. * `typescript.tsdk` (`string`, required) — The path from which to load TypeScript. * `locale` (`string`, optional) — The locale to use for TypeScript error messages. ### Configuration MDX language server supports the following LSP configuration options: * `mdx.trace.server.verbosity` (`"off"` | `"messages"` | `"compact"` | `"verbose"`, default: `"off"`) — Trace MDX language server requests in the output console. * `mdx.trace.server.format` (`"text"` | `"json"`, default: `"text"`) — How to format traced MDX language server requests. * `mdx.validate.validateReferences` (`"ignore"` | `"hint"` | `"warning"` | `"error"`, default: `"warning"`) — Diagnostic level for invalid reference links, e.g. `[text][no-such-ref]`. * `mdx.validate.validateFragmentLinks` (`"ignore"` | `"hint"` | `"warning"` | `"error"`, default: `"warning"`) — Diagnostic level for fragments links to headers in the current file that don’t exist, e.g. `[text](#no-such-header)` * `mdx.validate.validateFileLinks` (`"ignore"` | `"hint"` | `"warning"` | `"error"`, default: `"warning"`) — Diagnostic level for links to local files that don’t exist, e.g. `[text](./no-such-file.png)`. * `mdx.validate.validateMarkdownFileLinkFragments` (`"ignore"` | `"hint"` | `"warning"` | `"error"`, default: `"warning"`) — Diagnostic level for the fragment part of links to other local markdown files, e.g. `[text](./no-such-file.png)`. * `mdx.validate.validateUnusedLinkDefinitions` (`"ignore"` | `"hint"` | `"warning"` | `"error"`, default: `"warning"`) — Diagnostic level for link definitions that aren’t used anywhere. `[never-used]: http://example.com`. * `mdx.validate.validateDuplicateLinkDefinitions` (`"ignore"` | `"hint"` | `"warning"` | `"error"`, default: `"warning"`) — Diagnostic level for duplicate link definitions. * `mdx.validate.ignoreLinks` (`Array`, optional) — Glob of links that should not be validated. ### TypeScript This extension offers type safety for MDX files based on TypeScript’s [types in JSDoc][jsdoc]. For MDX specific details, see the [TypeScript section](https://github.com/mdx-js/mdx-analyzer#typescript) of the repository readme. ### Plugins For information on plugin support, see the [Plugins section](https://github.com/mdx-js/mdx-analyzer#plugins) of the repository readme. ## Editors MDX language server can be integrated with any editor that supports [language servers][lsp]. Does your editor support MDX language server, but is it not in this list? Feel free to add it. ### Emacs Use [`lsp-mode`][lsp-mode] to use the MDX language server with Emacs. ### Neovim You can add MDX support to MDX via [`nvim-lspconfig`][nvim-lspconfig]. After installing MDX language server, add the language server setup to your `init.lua`. ```lua require'lspconfig'.mdx_analyzer.setup{} ``` For more details, see the [`nvim-lspconfig` MDX analyzer][nvim-lspconfig mdx-analyzer] documentation. ### Visual Studio Code Use [`unifiedjs.vscode-mdx`][vscode-mdx] to use the MDX language server with [Visual Studio Code][vscode]. ## Compatibility This project is compatible Node.js 20.19+. This project uses [`vscode-languageserver`][vscode-languageserver] 9, which implements language server protocol 3.17.4. It should work anywhere where LSP 3.6.0 or later is implemented. ## Security This package provides IntelliSense for [MDX][] files. Some IntelliSense features modify your source code, for example suggestions and automatic refactors. It is recommended to keep your source code under version control. ## Contribute See [§ Contribute][contribute] on our website for ways to get started. See [§ Support][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][sponsor] on our site for how to help financially.
Vercel

 Motif

 HashiCorp

 GitBook

 Gatsby
Netlify

 Coinbase

 ThemeIsle

 Expo

 Boost Note

 Markdown Space

 Holloway

You?

## Changelog Detailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.md). ## License [MIT][] © [Remco Haszing][author] [author]: https://github.com/remcohaszing [backers-badge]: https://opencollective.com/unified/backers/badge.svg [build]: https://github.com/mdx-js/mdx-analyzer/actions [build-badge]: https://github.com/mdx-js/mdx-analyzer/workflows/main/badge.svg [chat]: https://github.com/mdx-js/mdx/discussions [chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg [code of conduct]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md [collective]: https://opencollective.com/unified [contribute]: https://mdxjs.com/community/contribute/ [coverage]: https://codecov.io/github/mdx-js/mdx-analyzer [coverage-badge]: https://img.shields.io/codecov/c/github/mdx-js/mdx-analyzer/main.svg [downloads]: https://www.npmjs.com/package/@mdx-js/language-server [downloads-badge]: https://img.shields.io/npm/dm/@mdx-js/language-server.svg [jsdoc]: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html [lsp]: https://microsoft.github.io/language-server-protocol [lsp commands]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#command [lsp-mode]: https://github.com/emacs-lsp/lsp-mode [mdx]: https://mdxjs.com [mit]: LICENSE [npm]: https://docs.npmjs.com/cli/install [nvim-lspconfig]: https://github.com/neovim/nvim-lspconfig [nvim-lspconfig mdx-analyzer]: https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#mdx_analyzer [sponsor]: https://mdxjs.com/community/sponsor/ [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg [support]: https://mdxjs.com/community/support/ [typescript]: https://typescriptlang.org [volar]: https://volarjs.dev [volar-service-markdown]: https://github.com/volarjs/services/tree/master/packages/markdown [volar-service-typescript]: https://github.com/volarjs/services/tree/master/packages/typescript [vscode]: https://code.visualstudio.com [vscode-languageserver]: https://github.com/microsoft/vscode-languageserver-node/tree/main/server [vscode-mdx]: https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx