Editor setup

Open your MyST project, or a folder holding several, as the workspace. See Finding the project for which project each file belongs to. If warnings don’t show up, see Troubleshooting.

VS Code¶

Install the MyST Language Server extension. It runs a bundled copy of this server for Markdown files and notebook Markdown cells, and installs MyST Syntax for highlighting. MyST Author adds a live preview on top of it.

JupyterLab¶

MyST Author’s JupyterLab extension runs this server for Markdown files and notebook cells.

For Markdown files only, you can register the server with jupyterlab-lsp instead, in jupyter_server_config.py:

c.LanguageServerManager.language_servers = {
    "mystmd-lsp": {
        "version": 2,
        "argv": ["mystmd-lsp", "--stdio"],
        "languages": ["markdown"],
        "mime_types": ["text/markdown", "text/x-markdown"],
        "display_name": "mystmd-lsp",
    }
}

The repository’s Binder config is a working copy of this, on the demo project.

jupyterlab-lsp doesn’t send notebook Markdown cells to a language server, so cells only get this server through MyST Author.

Other editors¶

Install the server (see Install), then point your editor’s LSP client at mystmd-lsp --stdio for Markdown files. The configurations below use myst.yml as the root marker, so the editor sends the project folder as the workspace folder and the server starts mystmd there. Project-wide completion and warnings appear once its first build finishes.

Neovim 0.11 or newer:

vim.lsp.config('mystmd', {
  cmd = { 'mystmd-lsp', '--stdio' },
  filetypes = { 'markdown' },
  root_markers = { 'myst.yml' },
})
vim.lsp.enable('mystmd')

Helix, in languages.toml:

[language-server.mystmd-lsp]
command = "mystmd-lsp"
args = ["--stdio"]

[[language]]
name = "markdown"
language-servers = ["mystmd-lsp"]
roots = ["myst.yml"]

language-servers replaces Helix’s default Markdown servers, so list them too if you use one.

If you write an LSP client that pulls diagnostics, its document selector must include notebook cells. In VS Code that is { notebook: { notebookType: 'jupyter-notebook' }, language: 'markdown' }. Without it, open cells only get diagnostics from workspace pulls.