MyST Author is built from several repositories that are each useful on their own. This page is the source of truth for how they relate. Each repository documents its own interface.
What each one owns¶
| Repository | Owns | Useful on its own to |
|---|---|---|
| mystmd | What MyST means: parsing, transforms, builds, and the content server | Everyone |
| mystmd-lsp | What an editor knows about a MyST project: references, labels, completion, hover, warnings | Any LSP editor (VS Code, Neovim, Helix) |
| mystmd-client | Starting mystmd, reading its content server, and parsing one page the way mystmd does | Any tool that runs mystmd or parses a single page |
| myst-syntax | Highlighting MyST syntax, for CodeMirror and TextMate, and the VS Code and JupyterLab extensions that ship it | Anyone who wants MyST highlighted in VS Code, JupyterLab, CodeMirror, or Shiki |
| myst-parser-unified | Parsing MyST with micromark, with line and column positions on every node | People using the unified Markdown tools (remark), and mystmd as a possible future parser |
myst-author packages/preview | Rendering a page, live preview in CodeMirror, and choosing between the fast and built preview | Anyone embedding a MyST preview, once it’s published |
| myst-author hosts | Running mystmd and the language server where no extension does, and anything that depends on the editor, such as documents, opening files and commands | People who want an editor |
Each host, the web editor, VS Code or JupyterLab, starts mystmd and the language server its own way, as Architecture describes.
Nothing depends on myst-parser-unified yet.
It’s a candidate to replace the parser that mystmd-lsp and the preview use.
mystmd-lsp’s design notes list what a parser must provide to replace its regexes.
Its drop-in mystParse matches mystmd’s tree on nearly every MyST example in myst-spec.
Where a feature goes¶
Put each feature in the lowest repository that can hold it:
mystmd, if it’s about what MyST means or what a build contains. Write it up as an upstream proposal and work around it until it lands.
mystmd-lsp, if an editor needs to know it. Every LSP editor then gets it, not just MyST Author’s hosts.
myst-syntax, if it’s about how MyST source looks.
packages/preview, if it’s about how MyST renders. The web editor, JupyterLab and the VS Code live editor all share it.A host, only for what depends on that editor (see Adding a host).
Keeping them independent¶
Repositories depend on each other only through published packages and extensions, never by path.
A rule that one repository relies on is part of the other’s documented interface. For example, MyST Author follows preview links through mystmd-lsp’s workspace symbols, so mystmd-lsp documents how it names them.
When repositories recognise the same syntax, each one follows mystmd’s rule and names where it lives, instead of copying another repository.