myst-language-support

The official MyST (Markedly Structured Text) Textmate grammar, and VS Code extension, for extending the markdown language.

This extension injects additional elements into the base markdown syntax highlighting grammar, and adds additional language support for MyST specific elements.

Important This extension is a work in progress, and future changes are likely.

• myst-language-support
  • Features
    • Syntax Highlighting
    • Hover and Autocompletion
    • Preview Enhancement
  • Working with Markdown
  • Contributing
    • Building the Grammar
    • Testing
    • Linting
    • Publishing to VS Marketplace
  • Acknowledgements

Features

Syntax Highlighting

Embedded code blocks/cells can be utilised in their native language:

Hover and Autocompletion

Directive completion and hover is available for all built-in sphinx directives:

Snippet completions are also available for a number of Sphinx directives:

Preview Enhancement

This extension enhances VS Code's built-in Markdown previewer (see this guide for info), to properly render nested admonitions, and code directives, etc.

If you encounter any issues with this, you can disable it with the myst.preview.enable configuration option (and please report it).

Working with Markdown

Here are some useful editor keyboard shortcuts:

• Split the editor (Cmd+\ on macOS or Ctrl+\ on Windows and Linux)
• Toggle preview (Shift+CMD+V on macOS or Shift+Ctrl+V on Windows and Linux)
• Press Ctrl+Space (Windows, Linux) or Cmd+Space (macOS) to see a list of Markdown snippets

For more information:

• Visual Studio Code's Markdown Support
• Markdown Syntax Reference

Contributing

The main grammar is stored in syntaxes/myst.tmLanguage. This file is generated from myst.tmLanguage.base.yaml.

See this guide on textmate bundles and the VS Code guide for more help.

Building the Grammar

The grammar is written as a jinja template YAML file, with the templates and default variables stored in template/

To generate the main grammar with javascript:

$ npm ci
$ npm run compile
$ npm run build

or with python:

$ pip install yaml jinja2
$ python src/build.py

Snippets are also built in the same manner.

Testing

To run the full test suite:

$ npm test

The test suite is split into 'integration' tests, which require VS Code to be launched, and 'standalone' tests, which can be run in the standard fashion with mocha.

$ npm run pretest
$ node ./out/test/runIntergration.js
$ ./node_modules/mocha/bin/mocha --ui tdd out/test/standalone/

The highlighting test cases are stored as markdown files under test_static/colorize-fixtures. Grammar test results are stored under test_static/colorize-results, which are automatically generated from the fixtures.

To visualise the grammar in VS Code, select the Launch Extension configuration in the VS Code debugger and run. To launch a development version of the extension in VS Code, press F5.

See also VS Code Testing Extension Guide

Linting

$ npm run lint

and to auto-fix lints:

$ npm run lint:fix

Publishing to VS Marketplace

The publishing of the package should be done via the Github Actions CI. To trigger a release, bump the version in package.json, and create a new release tag on Github starting with release, e.g. release-0.9.4.

See: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#publishing-extensions

Acknowledgements

Testing originally adapted from vscode-markdown-tm-grammar.