VS Code Markdown Language Server

0.5.0-alpha.13 verified Sat Apr 25 auth: no javascript

The `vscode-markdown-languageserver` is a Node.js-based language server providing rich Markdown language support, including features like link completions, smart folding, document and workspace symbol navigation, document linking, renaming across files, code actions (e.g., organizing link definitions), and pull diagnostics for link validation. Currently at version `0.5.0-alpha.13`, it is actively developed, serving as the backend for VS Code's native Markdown capabilities. It operates as a standalone executable, communicating via the Language Server Protocol (LSP). The server leverages the `vscode-markdown-languageservice` for its core logic, which is recommended for developers needing a direct library for Markdown processing rather than a full LSP server. Its release cadence is tied to VS Code's development, with an 'alpha' tag signifying ongoing evolution and potential API changes.

Common errors

error Error: Connection got disposed. ↓

cause The language server process terminated unexpectedly, or the client-server IPC connection was broken. This often happens due to unhandled exceptions in the server, incorrect LSP message formatting, or port/pipe conflicts.

fix

Check the server's standard output/error streams for detailed crash logs. Ensure the client is correctly spawning and maintaining the IPC channel (e.g., stdio, pipe). Verify node is available in the server's execution environment path.

error No completion items / diagnostics / references found, even for valid Markdown. ↓

cause The client may not be sending the correct `InitializeParams` or `DidChangeConfiguration` notifications, leading the server to operate with default or incorrect settings, or failing to recognize Markdown files.

fix

Ensure that InitializeParams.initializationOptions.markdownFileExtensions is set to include all relevant file extensions (e.g., ['md', 'mdown']). Verify workspace/didChangeConfiguration notifications are sent with the markdown settings as described in the README (e.g., markdown.validate.enabled: true).

error Cannot find module 'vscode-markdown-languageservice' or similar dependency error upon server startup. ↓

cause The `vscode-markdown-languageserver` package was installed without its production dependencies, or the Node.js environment cannot resolve the internal dependency path.

fix

Ensure npm install (or yarn install) was run in the directory where vscode-markdown-languageserver is a dependency. If installing globally or linking, verify that the node_modules structure correctly allows the server to find its internal vscode-markdown-languageservice dependency. This typically implies a fresh npm install for the project using the language server.

Warnings

breaking The package is currently in 'alpha' (`0.5.0-alpha.13`) and explicitly states 'This is still in development.' APIs are subject to change without strict adherence to semantic versioning until a stable 1.0 release. ↓

fix Monitor GitHub repository (`microsoft/vscode`) and `vscode-markdown-languageserver` npm releases for breaking changes. Consider pinning exact versions in `package.json` for stability in production environments.

gotcha This package is a Language Server, designed to run as a separate process and communicate via LSP. It is not intended for direct use as a library to process Markdown files programmatically. For library-level Markdown functionality, use `vscode-markdown-languageservice`. ↓

fix If you need to parse, validate, or work with Markdown ASTs directly in your application, import and use `vscode-markdown-languageservice`. If you are building an editor integration, you should either spawn this server as a child process or host it programmatically via LSP.

gotcha The server has 'not yet been tested with other clients' besides VS Code. While it implements the standard LSP, full compatibility with non-VS Code clients (e.g., Neovim, Sublime Text) is not guaranteed and may require custom client-side configuration or workarounds. ↓

fix Thoroughly test integration with your specific LSP client. Review client-side initialization options (`markdownFileExtensions`) and server settings (`markdown.suggest.paths.enabled`, `markdown.validate.enabled`) as documented in the README, as these are crucial for proper functionality.

gotcha LSP servers, including this one, run in separate processes. While beneficial for performance isolation, this can lead to increased memory consumption if many language servers are active, even when files are not actively being edited. ↓

fix Be mindful of system resource usage, especially in environments with many different language servers. Clients can implement strategies to start/stop servers on demand rather than keeping them perpetually active, though this requires custom client-side logic.

Install

npm install vscode-markdown-languageserver

yarn add vscode-markdown-languageserver

pnpm add vscode-markdown-languageserver

Imports

startServer
wrong
```
import { startServer } from 'vscode-markdown-languageserver';
```
correct
```
import { startServer } from 'vscode-markdown-languageserver/lib/node/server';
```
The primary entry point for programmatically starting the language server. It's found in a deeper path as the main package export often points to the executable. Direct CJS `require` is generally not recommended for modern Node.js applications and this package is designed for ESM or TypeScript environments.
Connection
```
import { Connection, createConnection, ProposedFeatures, TextDocuments } from 'vscode-languageserver/node';
```
While `Connection` is not directly exported by `vscode-markdown-languageserver`, it is the fundamental type from `vscode-languageserver/node` that `startServer` expects. Developers integrating the server typically create and manage this connection.
InitializeParams
```
import type { InitializeParams } from 'vscode-languageserver-protocol';
```
This type, from the LSP protocol, defines the initialization options (like `markdownFileExtensions`) and client capabilities that the client sends to the server. While not exported by this package, understanding it is crucial for configuring the server.

Quickstart

This quickstart demonstrates how to programmatically set up and start the `vscode-markdown-languageserver` using `vscode-languageserver/node`. It initializes a connection, configures document synchronization, declares server capabilities, and then calls `startServer` to activate the Markdown language features, illustrating a basic LSP host.

import { createConnection, ProposedFeatures, TextDocuments, Connection } from 'vscode-languageserver/node';
import { TextDocument } from 'vscode-languageserver-textdocument';
import { startServer } from 'vscode-markdown-languageserver/lib/node/server';

// Create a connection for the server. The connection uses Node's IPC as a transport.
const connection: Connection = createConnection(ProposedFeatures.all);

// Create a simple text document manager.
const documents: TextDocuments<TextDocument> = new TextDocuments(TextDocument);

connection.onInitialize((params) => {
  console.log('Markdown Language Server Initialized', params);
  // Client can send initialization options, e.g., for file extensions
  if (params.initializationOptions) {
    console.log('Received initialization options:', params.initializationOptions);
  }
  return {
    capabilities: {
      textDocumentSync: documents.syncKind,
      completionProvider: { resolveProvider: true },
      documentSymbolProvider: true,
      foldingRangeProvider: true,
      documentLinkProvider: { resolveProvider: true },
      referencesProvider: true,
      definitionProvider: true,
      renameProvider: { prepareProvider: true },
      codeActionProvider: true,
      // The server will pull diagnostics
      diagnosticProvider: {
        interFileDependencies: true,
        workspaceDiagnostics: true,
      },
      // Custom messages are also supported
      executeCommandProvider: {
        commands: ['markdown/getReferencesToFileInWorkspace', 'markdown/getEditForFileRenames']
      }
    },
  };
});

connection.onInitialized(() => {
  console.log('Markdown Language Server Fully Initialized');
  // Register for configuration changes if the client supports it
  connection.client.register({
    method: 'workspace/didChangeConfiguration'
  });
});

// Listen for text document changes
documents.listen(connection);

// Start the actual Markdown language server logic
startServer(connection);

// Listen on the connection
connection.listen();

console.log('Markdown Language Server is listening...');