{"id":26696096,"url":"https://github.com/executablebooks/myst-vs-code","last_synced_at":"2025-12-30T01:30:31.664Z","repository":{"id":39879032,"uuid":"248136424","full_name":"executablebooks/myst-vs-code","owner":"executablebooks","description":"A syntax highlighter for the MyST Markdown format","archived":false,"fork":false,"pushed_at":"2023-03-06T10:42:00.000Z","size":4956,"stargazers_count":35,"open_issues_count":29,"forks_count":15,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-09-05T02:40:09.837Z","etag":null,"topics":["markdown","myst","textmate-grammar"],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/executablebooks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-18T04:14:35.000Z","updated_at":"2024-03-17T20:22:51.000Z","dependencies_parsed_at":"2023-02-08T04:01:56.662Z","dependency_job_id":null,"html_url":"https://github.com/executablebooks/myst-vs-code","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fmyst-vs-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fmyst-vs-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fmyst-vs-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fmyst-vs-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/executablebooks","download_url":"https://codeload.github.com/executablebooks/myst-vs-code/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245727694,"owners_count":20662555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","myst","textmate-grammar"],"created_at":"2025-03-26T20:01:02.807Z","updated_at":"2025-12-30T01:30:31.636Z","avatar_url":"https://github.com/executablebooks.png","language":"TypeScript","funding_links":[],"categories":["Tools"],"sub_categories":["Syntax Highlighters"],"readme":"# MyST-Markdown VS Code Extension\n\n[![VS Marketplace][vs-market-badge]][vs-market-link]\n[![Github-CI][github-ci-badge]][github-ci-link]\n\nThe official [MyST (Markedly Structured Text)](https://myst-parser.readthedocs.io) VS Code extension, for extending the Markdown language.\n\nThis extension extends VS Code's Markdown language with the following features:\n\n- Extended syntax highlighting\n- Hover information and auto-completion for roles and directives\n- Extended preview rendering\n- Code snippets for role and directive definitions\n\ninjects additional elements into the base markdown syntax highlighting grammar, and adds additional language support for MyST specific elements.\n\n- [MyST-Markdown VS Code Extension](#myst-markdown-vs-code-extension)\n  - [Features](#features)\n    - [Syntax Highlighting](#syntax-highlighting)\n    - [Hover and Autocompletion](#hover-and-autocompletion)\n    - [Preview Enhancement](#preview-enhancement)\n      - [CSS Styling](#css-styling)\n      - [A note on dollar-math](#a-note-on-dollar-math)\n  - [Working with Markdown](#working-with-markdown)\n  - [Contributing](#contributing)\n    - [Manual testing](#manual-testing)\n    - [Building the grammar and snippet assets](#building-the-grammar-and-snippet-assets)\n    - [Unit and integration testing](#unit-and-integration-testing)\n    - [Linting](#linting)\n    - [Publishing to VS Marketplace](#publishing-to-vs-marketplace)\n  - [Acknowledgements](#acknowledgements)\n\n## Features\n\n### Syntax Highlighting\n\n\u003cimg width=\"500\" alt=\"screenshot\" src=\"https://raw.githubusercontent.com/executablebooks/myst-vs-code/master/images/Screenshot.png\"\u003e\n\nEmbedded code blocks/cells can be utilised in their native language:\n\n\u003cimg width=\"500\" alt=\"screenshot\" src=\"https://raw.githubusercontent.com/executablebooks/myst-vs-code/master/images/embedded-code.gif\"\u003e\n\n### Hover and Autocompletion\n\nDirective completion and hover is available for all built-in sphinx directives:\n\n\u003cimg width=\"500\" alt=\"screenshot\" src=\"https://raw.githubusercontent.com/executablebooks/myst-vs-code/master/images/directive-completion.gif\"\u003e\n\n\u003cimg width=\"500\" alt=\"screenshot\" src=\"https://raw.githubusercontent.com/executablebooks/myst-vs-code/master/images/directive-hover.gif\"\u003e\n\nSnippet completions are also available for a number of Sphinx directives:\n\n\u003cimg width=\"500\" alt=\"screenshot\" src=\"https://raw.githubusercontent.com/executablebooks/myst-vs-code/master/images/snippet-completion.gif\"\u003e\n\n### Preview Enhancement\n\nThis extension enhances VS Code's built-in Markdown previewer\n([see this guide for info](https://code.visualstudio.com/api/extension-guides/markdown-extension)), to properly render MyST syntax like directives and other extensions.\n\n\u003cimg width=\"500\" alt=\"screenshot\" src=\"https://raw.githubusercontent.com/executablebooks/myst-vs-code/master/images/preview.gif\"\u003e\n\nIf you encounter any issues with this, you can disable it with the `myst.preview.enable` [configuration setting][vscode-settings] (and please report it).\n\nYou can add MyST syntax extensions with the `myst.preview.extensions` [configuration setting][vscode-settings]. Available extensions:\n\n- `amsmath`: Parse AMS LaTeX math environments\n- `deflist`: Parse definition lists\n- `dollarmath`: Parse dollar-delimited math (on by default)\n- `tasklist`: Parse GitHub style task lists\n\nNote after changing this setting you should reload the VS Code window.\n\n#### CSS Styling\n\nPrincipally the stylings from [markdown-it-docutils](https://github.com/executablebooks/markdown-it-docutils) are used.\n\nThe colors are in light mode by default, switching to the dark mode when set by the users operating system.\nSee the [`prefers-color-scheme` documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) for details.\n\n#### A note on dollar-math\n\nFrom VS Code version `v1.58.0`, VS Code natively supports dollar math rendering ([see here](https://code.visualstudio.com/updates/v1_58#_math-formula-rendering-in-the-markdown-preview)).\nUsing the `dollarmath` extension overrides this with some slightly different parsing rules (e.g. dollarmath allows `$$` display math in inline contexts and also labels: `$$a=1$$ (label)`).\n\nIf there are still any incompatibilities you can turn off the native support with `markdown.math.enabled` [configuration setting][vscode-settings].\n\n## Working with Markdown\n\nHere are some useful editor keyboard shortcuts:\n\n- Split the editor (`Cmd+\\` on macOS or `Ctrl+\\` on Windows and Linux)\n- Toggle preview (`Shift+CMD+V` on macOS or `Shift+Ctrl+V` on Windows and Linux)\n- Press `Ctrl+Space` (Windows, Linux) or `Cmd+Space` (macOS) to see a list of Markdown snippets\n\nFor more information:\n\n- [Visual Studio Code's Markdown Support](http://code.visualstudio.com/docs/languages/markdown)\n- [Markdown Syntax Reference](https://help.github.com/articles/markdown-basics/)\n\n## Contributing\n\nThe main grammar is stored in `syntaxes/myst.tmLanguage`. This file is generated from `myst.tmLanguage.base.yaml`.\n\nSee [this guide on textmate bundles](https://macromates.com/manual/en/language_grammars), the [VS Code Syntax Highlight guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide), and the [extension API](https://code.visualstudio.com/api) for more help.\n\n### Manual testing\n\nTo launch a local version of the extension in VS Code, first ensure the extension build is updated:\n\n```console\n$ npm run build\n```\n\nNow select the `Launch Extension` configuration in the VS Code `Run and Debug` side panel.\nTo launch a development version of the extension in VS Code, press `F5`.\n\n### Building the grammar and snippet assets\n\nThe grammar is written as a [Jinja template](https://jinja.palletsprojects.com) YAML file,\nwith the templates and default variables stored in `template/`\n\nTo generate the asset files (grammar and snippets):\n\n```bash\n$ npm ci\n$ npm run build:assets\n```\n\nor with python:\n\n```bash\n$ pip install yaml jinja2\n$ python src/build.py\n```\n\n### Unit and integration testing\n\nThe test suite is split into:\n\n- 'integration' tests, which require VS Code to be launched, and\n- 'unit' tests, which can be run in the standard fashion with [mocha](https://mochajs.org)\n\nYou can run them on the CLI with `npm test`, or separately:\n\n```bash\n$ npm run pretest\n$ npm run test:unit\n$ npm run test:integration\n```\n\nRunning from the CLI will download and launch a specific version of VS Code (see `src/test/runIntergration.ts`).\n\nNote though, that running integration tests from within VS Code may error (see [Testing extensions tips](https://code.visualstudio.com/api/working-with-extensions/testing-extension#using-insiders-version-for-extension-development)).\nIn this case you can run the tests directly through the `Debug Launcher` in the side panel (see `.vscode/launch.json`). The output can be viewed in the debug console.\n\nThe highlighting test cases are stored as markdown files under `test_static/colorize-fixtures`.\nGrammar test results are stored under `test_static/colorize-results`, which are automatically generated/updated from the fixtures.\nNote though that the fixture results can change between VS Code versions, so you should use the version specified in `src/test/runIntergration.ts`.\n\n### Linting\n\n```bash\n$ npm run lint\n```\n\nand to auto-fix lints:\n\n```bash\n$ npm run lint:fix\n```\n\n### Publishing to VS Marketplace\n\nThe publishing of the package should be done *via* the Github Actions CI:\n\n1. Bump the version with npm, e.g. `npm version patch -m \"🚀 RELEASE: v%s\"` (major/minor/patch based on [semantic versioning](https://semver.org/))\n2. Push the commit and tag generated by npm (`git push --follow-tags`)\n3. This should trigger the CI action and the `publish` step, check it runs correctly.\n4. Create a GitHub release, pointing to the tag created by npm.\n\nSee also: \u003chttps://code.visualstudio.com/api/working-with-extensions/publishing-extension#publishing-extensions\u003e, and the [ExecutableBookProject publisher organization](https://dev.azure.com/ExecutableBookProject).\n\n## Acknowledgements\n\nTesting originally adapted from [vscode-markdown-tm-grammar](https://github.com/microsoft/vscode-markdown-tm-grammar/tree/59a5962e4775bf96484bba64c5322422b555a40d).\n\nVS Code Markdown extension exemplars were taken from [vscode/extensions/markdown-math](https://github.com/microsoft/vscode/blob/main/extensions/markdown-math).\n\n[vs-market-badge]: https://vsmarketplacebadge.apphb.com/version/ExecutableBookProject.myst-highlight.svg \"Current Release\"\n[vs-market-link]: https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight\n[github-ci-badge]: https://img.shields.io/github/workflow/status/executablebooks/myst-vs-code/Github-CI?label=Github-CI\n[github-ci-link]: https://github.com/executablebooks/myst-vs-code/actions\n[vscode-settings]: https://code.visualstudio.com/docs/getstarted/settings\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexecutablebooks%2Fmyst-vs-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexecutablebooks%2Fmyst-vs-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexecutablebooks%2Fmyst-vs-code/lists"}