Configuration

The server has a few command-line flags, and reads your project’s myst.yml.

mystmd-lsp --stdio [--root=path/to/project] [--content-server=URL] [--no-myst] [--execute]

To run it with your own node, use the installed package’s dist/server.cjs, which is the whole server in one file.

• --root: use one project at this folder for every document, instead of finding each document’s project (see Finding the project).

• --content-server: the URL of a myst start --headless content server you already run for the --root project. The server uses it instead of starting its own.

• --no-myst: don’t start mystmd.

• --execute: when the server starts mystmd, run code cells and inline {eval} expressions too (myst start --execute). This runs the project’s code, and needs Jupyter.

Asking where the project is¶

Clients that build on this server can send the request myst/project once the server is initialized.

params: { uri?: string }
result: { root?: string; contentServer?: string; page?: boolean }

With a uri, the answer describes that document:

• root is the document’s project folder.

• contentServer is mystmd’s URL, if the server runs one.

• page says whether mystmd builds the document.

A document with no project gets {}. Without a uri, the answer describes the --root project, or is {} when there is no --root. MyST Author’s VS Code extension sends this request for each document, to point its preview at the same mystmd.

Starting mystmd¶

See How it works for when the server starts mystmd. When the server starts mystmd, mystmd runs the project’s plugins and writes _build/, like any myst start. Plugins can run any code. If your editor can’t mark folders as trusted, start the server with --no-myst for folders you do not trust.

If you start mystmd yourself and pass its address with --content-server, run it as HOST=127.0.0.1 myst start --headless and pass http://127.0.0.1:<port>. Without HOST, myst start listens on localhost, which can resolve to IPv6 only. To run a myst that isn’t on your PATH, set the MYST_BIN environment variable to its path.

Finding the project¶

A document’s project is the nearest myst.yml at or above the document’s folder, no higher than the workspace folder that contains it. So nothing above the folder you opened is picked up. A folder can hold several projects. The server starts a separate mystmd and index for each one when the first document in it opens. A document outside every workspace folder, or with no myst.yml between it and its workspace folder, has no project and gets no features.

A document gets features only if it’s a page of its project, one that mystmd builds. mystmd decides what counts, including through project.toc and project.exclude. That way the editor and the build agree. Until the first build is indexed, any Markdown file or notebook under the project folder counts as a page. If mystmd doesn’t run, that fallback stays the rule.

--root replaces all of this with one project at that folder, with or without a myst.yml. A myst.yml created after the server started, or a workspace folder added later, isn’t picked up until the server restarts (in VS Code, reload the window).

What it reads from myst.yml¶

The server reads the bibliography, external references and plugins from myst.yml. It re-reads them when myst.yml or a .bib file changes, if your editor supports file watching.

• project.bibliography: the .bib files for citations. Without it, every .bib file in the project is used, as in mystmd.

• project.references: the keys for external references.

• project.plugins: the directives and roles of JavaScript plugins, for completion.

Semantic token colours¶

The server tags each reference with its target’s kind as a semantic token, so you can colour references by kind. The kinds are listed in semanticTokensLegend in src/service.ts. In VS Code, references are coloured like (label)= targets until you colour them yourself. To colour references to figures in VS Code, set "editor.semanticTokenColorCustomizations": { "rules": { "label.figure": "#2a9d8f" } }. References to other kinds keep the (label)= colour.