✨ NEW: Use external markdown-it plugins

.eslintrc.yaml

@@ -15,28 +15,17 @@ parserOptions:
   ecmaVersion: 2018
   project: "./tsconfig.eslint.json"
 rules:
-  # TODO turn the following on after updating repo
-  "@typescript-eslint/naming-convention": "off"
+
+  # these are related to using any
   "@typescript-eslint/no-unsafe-member-access": "off"
   "@typescript-eslint/no-unsafe-assignment": "off"
-  "@typescript-eslint/no-floating-promises": "off"
   "@typescript-eslint/restrict-template-expressions": "off"
-  "@typescript-eslint/no-unsafe-return": "off"
   "@typescript-eslint/explicit-module-boundary-types": "off"
-  "@typescript-eslint/restrict-plus-operands": "off"
-  "@typescript-eslint/no-unsafe-call": "off"
-  "@typescript-eslint/ban-types": "off"
-  # end TODO
+  "@typescript-eslint/no-explicit-any": "off"
+
   no-undef: "off"
   no-unused-vars: "off"
   no-constant-condition: "off"
-  "@typescript-eslint/ban-ts-comment": error
-  "@typescript-eslint/prefer-interface": "off"
-  "@typescript-eslint/explicit-function-return-type": "off"
-  "@typescript-eslint/explicit-member-accessibility": "off"
-  "@typescript-eslint/indent": "off"
-  "@typescript-eslint/interface-name-prefix": "off"
-  "@typescript-eslint/no-use-before-define": "off"
   "@typescript-eslint/type-annotation-spacing":
     - error
     - before: false
@@ -52,10 +41,6 @@ rules:
   prefer-arrow-callback:
     - error
     - allowUnboundThis: false
-  "@typescript-eslint/no-parameter-properties": "off"
-  "@typescript-eslint/no-explicit-any": "off"
-  "@typescript-eslint/no-inferrable-types": "off"
-  "@typescript-eslint/prefer-regexp-exec": "off"
   "@typescript-eslint/no-empty-function": "off"
   "@typescript-eslint/no-misused-promises":
     - error

.github/workflows/ci.yml

@@ -53,13 +53,11 @@ jobs:
       uses: actions/setup-node@v1
       with:
         node-version: ${{ matrix.node-version }}
-    - name: Compile
+    - name: Build Package
       run: |
         npm ci
-        npm run compile
-    - name: Build Grammar
-      run: npm run build
-      # TODO test built files don't change after this?
+        npm run build
+      # TODO test built grammar files don't change after this?
     - name: Run tests
       uses: GabrielBB/xvfb-action@v1.0
       with:
@@ -78,4 +76,4 @@ jobs:
       with:
         args: "publish -p $VSCE_TOKEN"
       env:
-        VSCE_TOKEN: ${{ secrets.VSCE_PUB }}
+        VSCE_TOKEN: ${{ secrets.VSCE_PUB }}

.gitignore

@@ -1,6 +1,8 @@
 out
 node_modules
+.DS_Store
 .vscode-test/
 *.vsix
 .eslintcache
 .vscode/
+_archive/

.vscodeignore

@@ -6,6 +6,7 @@ src/**
 vsc-extension-quickstart.md
 **/tsconfig.json
 **/tslint.json
+**/.eslintcache
 **/*.map
 **/*.ts
 _archive/**

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Change Log
+
+## v0.11.0 - 2021-07-10
+
+This version marks a complete re-write of the Markdown preview extension, to more fully support the MyST syntax:
+
+- Full rendering of many common directives, including: all core admonitions, `image`, `figure`, `code`, `code-block`, `code-cell`, `list-table`.
+- Fixes previous issues with admonition renderings.
+- Support for MyST syntax extensions via the `myst.preview.extensions` [configuration setting][vscode-settings]: `amsmath`, `colon_fence`, `deflist`, `dollarmath` (default), `tasklist`
+
+See the README for more details!
+
+Under the hood, the version also marks a large number of changes, to improve the maintenance and documentation of the extension, and to use a number of new external markdown-it plugin libraries, such as [markdown-it-docutils](https://github.com/executablebooks/markdown-it-docutils).
+
+[vscode-settings]: https://code.visualstudio.com/docs/getstarted/settings

README.md

@@ -1,24 +1,31 @@
-# myst-language-support
+# MyST-Markdown VS Code Extension
 
 [![VS Marketplace][vs-market-badge]][vs-market-link]
 [![Github-CI][github-ci-badge]][github-ci-link]
 
-The official [MyST (Markedly Structured Text)](https://myst-parser.readthedocs.io) Textmate grammar, and VS Code extension, for extending the markdown language.
+The official [MyST (Markedly Structured Text)](https://myst-parser.readthedocs.io) 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.
+This extension extends VS Code's Markdown language with the following features:
 
-**Important** This extension is a work in progress, and future changes are likely.
+- Extended syntax highlighting
+- Hover information and auto-completion for roles and directives
+- Extended preview rendering
+- Code snippets for role and directive definitions
 
-- [myst-language-support](#myst-language-support)
+injects additional elements into the base markdown syntax highlighting grammar, and adds additional language support for MyST specific elements.
+
+- [MyST-Markdown VS Code Extension](#myst-markdown-vs-code-extension)
   - [Features](#features)
     - [Syntax Highlighting](#syntax-highlighting)
     - [Hover and Autocompletion](#hover-and-autocompletion)
     - [Preview Enhancement](#preview-enhancement)
+      - [CSS Styling](#css-styling)
+      - [A note on dollar-math](#a-note-on-dollar-math)
   - [Working with Markdown](#working-with-markdown)
   - [Contributing](#contributing)
-    - [Building the Grammar](#building-the-grammar)
-    - [Testing](#testing)
+    - [Manual testing](#manual-testing)
+    - [Building the grammar and snippet assets](#building-the-grammar-and-snippet-assets)
+    - [Unit and integration testing](#unit-and-integration-testing)
     - [Linting](#linting)
     - [Publishing to VS Marketplace](#publishing-to-vs-marketplace)
   - [Acknowledgements](#acknowledgements)
@@ -27,67 +34,96 @@ and adds additional language support for MyST specific elements.
 
 ### Syntax Highlighting
 
-<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-highlight-grammar/master/images/Screenshot.png">
+<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-language-support/master/images/Screenshot.png">
 
 Embedded code blocks/cells can be utilised in their native language:
 
-<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-highlight-grammar/master/images/embedded-code.gif">
+<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-language-support/master/images/embedded-code.gif">
 
 ### Hover and Autocompletion
 
 Directive completion and hover is available for all built-in sphinx directives:
 
-<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-highlight-grammar/master/images/directive-completion.gif">
+<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-language-support/master/images/directive-completion.gif">
 
-<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-highlight-grammar/master/images/directive-hover.gif">
+<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-language-support/master/images/directive-hover.gif">
 
 Snippet completions are also available for a number of Sphinx directives:
 
-<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-highlight-grammar/master/images/snippet-completion.gif">
+<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-language-support/master/images/snippet-completion.gif">
 
 ### Preview Enhancement
 
 This extension enhances VS Code's built-in Markdown previewer
-([see this guide for info](https://code.visualstudio.com/api/extension-guides/markdown-extension)),
-to properly render nested admonitions, and code directives, etc.
+([see this guide for info](https://code.visualstudio.com/api/extension-guides/markdown-extension)), to properly render MyST syntax like directives and other extensions.
+
+<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-language-support/master/images/preview.gif">
+
+If you encounter any issues with this, you can disable it with the `myst.preview.enable` [configuration setting][vscode-settings] (and please report it).
+
+You can add MyST syntax extensions with the `myst.preview.extensions` [configuration setting][vscode-settings]. Available extensions:
+
+- `amsmath`: Parse AMS LaTeX math environments
+- `deflist`: Parse definition lists
+- `dollarmath`: Parse dollar-delimited math (on by default)
+- `tasklist`: Parse GitHub style task lists
+
+Note after changing this setting you should reload the VS Code window.
+
+#### CSS Styling
 
-<img width="500" alt="screenshot" src="https://raw.githubusercontent.com/ExecutableBookProject/myst-highlight-grammar/master/images/preview.gif">
+Principally the stylings from [markdown-it-docutils](https://github.com/executablebooks/markdown-it-docutils) are used.
 
-If you encounter any issues with this, you can disable it
-with the `myst.preview.enable` configuration option
-(and please report it).
+The colors are in light mode by default, switching to the dark mode when set by the users operating system.
+See the [`prefers-color-scheme` documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) for details.
+
+#### A note on dollar-math
+
+From 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)).
+Using 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)`).
+
+If there are still any incompatibilities you can turn off the native support with `markdown.math.enabled` [configuration setting][vscode-settings].
 
 ## 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
+- 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](http://code.visualstudio.com/docs/languages/markdown)
-* [Markdown Syntax Reference](https://help.github.com/articles/markdown-basics/)
+- [Visual Studio Code's Markdown Support](http://code.visualstudio.com/docs/languages/markdown)
+- [Markdown Syntax Reference](https://help.github.com/articles/markdown-basics/)
 
 ## 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](https://macromates.com/manual/en/language_grammars) and
-[the VS Code guide](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide) for more help.
+See [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.
+
+### Manual testing
+
+To launch a local version of the extension in VS Code, first ensure the extension build is updated:
+
+```console
+$ npm run build
+```
+
+Now select the `Launch Extension` configuration in the VS Code `Run and Debug` side panel.
+To launch a development version of the extension in VS Code, press `F5`.
 
-### Building the Grammar
+### Building the grammar and snippet assets
 
-The grammar is written as a [jinja template](https://jinja.palletsprojects.com) YAML file,
+The grammar is written as a [Jinja template](https://jinja.palletsprojects.com) YAML file,
 with the templates and default variables stored in `template/`
 
-To generate the main grammar with javascript:
+To generate the asset files (grammar and snippets):
 
 ```bash
 $ npm ci
-$ npm run compile
-$ npm run build
+$ npm run build:assets
 ```
 
 or with python:
@@ -97,34 +133,29 @@ $ pip install yaml jinja2
 $ python src/build.py
 ```
 
-Snippets are also built in the same manner.
+### Unit and integration testing
 
-### Testing
+The test suite is split into:
 
-To run the full test suite:
-
-```bash
-$ npm test
-```
+- 'integration' tests, which require VS Code to be launched, and
+- 'unit' tests, which can be run in the standard fashion with [mocha](https://mochajs.org)
 
-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](https://mochajs.org).
+You can run them on the CLI with `npm test`, or separately:
 
 ```bash
 $ npm run pretest
-$ node ./out/test/runIntergration.js
-$ ./node_modules/mocha/bin/mocha --ui tdd out/test/standalone/
+$ npm run test:unit
+$ npm run test:integration
 ```
 
-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/updated from the fixtures.
+Running from the CLI will download and launch a specific version of VS Code (see `src/test/runIntergration.ts`).
 
-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`.
+Note 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)).
+In 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.
 
-See also [VS Code Testing Extension Guide](https://code.visualstudio.com/api/working-with-extensions/testing-extension)
+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/updated from the fixtures.
+Note though that the fixture results can change between VS Code versions, so you should use the version specified in `src/test/runIntergration.ts`.
 
 ### Linting
 
@@ -140,16 +171,23 @@ $ 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`.
+The publishing of the package should be done *via* the Github Actions CI.
+To trigger a release:
+
+1. Bump the version with npm, e.g. `npm version patch -m "🚀 RELEASE: v%s"` (major/minor/patch based on [semantic versioning](https://semver.org/))
+2. Push the commit and tag generated by npm (`git push --follow-tags`)
+3. 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
+See also: <https://code.visualstudio.com/api/working-with-extensions/publishing-extension#publishing-extensions>
 
 ## Acknowledgements
 
 Testing originally adapted from [vscode-markdown-tm-grammar](https://github.com/microsoft/vscode-markdown-tm-grammar/tree/59a5962e4775bf96484bba64c5322422b555a40d).
 
+VS Code Markdown extension exemplars were taken from [vscode/extensions/markdown-math](https://github.com/microsoft/vscode/blob/main/extensions/markdown-math).
+
 [vs-market-badge]: https://vsmarketplacebadge.apphb.com/version/ExecutableBookProject.myst-highlight.svg "Current Release"
 [vs-market-link]: https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight
-[github-ci-badge]: https://img.shields.io/github/workflow/status/ExecutableBookProject/myst-highlight-grammar/Github-CI?label=Github-CI
-[github-ci-link]: https://github.com/ExecutableBookProject/myst-highlight-grammar/actions
+[github-ci-badge]: https://img.shields.io/github/workflow/status/ExecutableBookProject/myst-language-support/Github-CI?label=Github-CI
+[github-ci-link]: https://github.com/ExecutableBookProject/myst-language-support/actions
+[vscode-settings]: https://code.visualstudio.com/docs/getstarted/settings