Contributing

Layout¶

• packages/server: the mystmd-lsp npm package. npm run build bundles src into dist/server.cjs.

• packages/vscode: the VS Code extension, which copies that bundle in at build time. Its activate() returns { client, server }, the language client and the path of the server script, for extensions that build on it. MyST Author uses the client to ask where the project is, and runs the script again with --root and --content-server for its own editors.

• demo: a MyST project that walks through each feature.

• docs: this site.

• .devcontainer and binder: the Codespaces and Binder configs, which open the demo with the extension and with jupyterlab-lsp.

The root package.json is private and runs each command in every package, so the commands below work from the repository root. Paths like src/service.ts in these docs are inside packages/server.

MyST Author is one client of this server. See how the repositories fit together for what lives where.

Set up¶

You need Node 22.18 or newer, since the tests run the TypeScript source directly. From the repository root:

npm ci
npm test # builds first
npm run test:mystmd # also runs the tests that start mystmd
npm run typecheck
npm run conformance # compares the reference regexes with mystmd (see Conformance below)

npm test skips the tests that start mystmd, so it passes without a working mystmd. npm run test:mystmd runs them, and fails if mystmd doesn’t start. CI runs test:mystmd, typecheck and conformance, and packages the VS Code extension.

Try your build¶

Run npm run demo:copy, then open /tmp/mystmd-lsp-demo in an editor set up as in Editor setup, with node <absolute path to packages/server/dist/server.cjs> --stdio as the command instead of mystmd-lsp --stdio. The demo walks through each feature, and works on a copy so demo/ isn’t edited. In VS Code, point the MyST Language Server extension’s mystmdLsp.serverPath setting at your packages/server/dist/server.cjs.

Code map¶

• src/syntax.ts: finds reference syntax in text.

• src/index-targets.ts: collects reference targets from an mdast tree.

• src/project.ts: the project index, from the content server’s pages and the open documents.

• src/root.ts: finds a document’s project, with the workspace folder as the ceiling, and reads its myst.yml.

• src/xref.ts: external project inventories and xref: resolution.

• src/cite.ts: reads the project’s .bib files.

• src/kinds.ts: the completion icon for each kind of target.

• src/service.ts: the features (completion, hover, diagnostics, ...) without an LSP connection, so tests can call them directly.

• src/server.ts: the LSP wiring.

• mystmd-client, a separate package: the mystmd parser with its default extensions (parse), a client for the content server (content-server), and a launcher for myst start (start).

Tests sit next to the code they cover, as *.test.ts. To add a feature, such as a new diagnostic:

1. Put the logic in src/service.ts, and add a test to service.test.ts beside it. To run one file, use node --test src/service.test.ts in packages/server.

2. Wire it up in server.ts.

3. Document it in Features, and add a line to the README’s “What you get” only if it’s a new kind of feature.

Conformance¶

References come from regexes. Replacing the reference regexes says why, and what a parser would need to replace them.

npm run conformance checks that the regexes find the same references and label definitions as mystmd’s parser, on the myst-spec examples. It fails on a difference that isn’t in known at the top of scripts/conformance.ts, or on one in known that no longer differs.

To also run it on your own projects, point MYST_CORPUS at a folder:

MYST_CORPUS=path/to/projects npm run conformance

This reads every .md file and the Markdown cells of every .ipynb file, skipping hidden files, node_modules and _build. Corpus differences are reported but don’t fail the run.

Kept in sync by hand¶

Change these together:

• .github/workflows/test.yml and the commands under Set up.

• The mystmd version here and the myst-parser version that mystmd-client pins, listed in mystmd-client’s README.

• What the VS Code extension’s activate returns, under Layout, and what MyST Author’s extension reads from it.

Docs¶

The docs are a MyST site in docs/. Each fact has one home, so change it there rather than repeating it:

• Features and Configuration are the reference.

• Editor setup has the setup for each kind of client, so add new clients there.

• The README only has what a visitor to the repository needs, and the home page of this site includes it.

Run npm run docs:live to preview the site, and npm run docs to build it. The site deploys to GitHub Pages when main changes.

Releasing¶

Each package is released on its own, with its own version. The extension bundles the server from the working tree, so a server change usually means releasing both.

1. Run npm version <version> --no-git-tag-version -w packages/<name>.

2. Commit the changes to that package.json and package-lock.json. Push to main.

3. Run the Release workflow (.github/workflows/release.yml) from the Actions tab and pick the package, or run gh workflow run release.yml -f package=<name>.

It publishes the package at the version in its package.json. Then it tags the commit, mystmd-lsp-v<version> for the server or vscode-v<version> for the extension, and creates a GitHub release with generated notes. Edit the release afterwards to replace the notes with ones from github-activity. Publishing the server needs npm’s trusted publisher set up for release.yml. Publishing the extension needs the VSCE_PAT and OVSX_PAT secrets of the myst-author publisher, on the Marketplace and on Open VSX. MyST Author picks up new releases through its dependencies.