v3 (#108)

* Add concept of gutter cells

* Adjust rendering and styling

* Finish layout, add test, make it work with line highlighting

* Fix copy and paste

* Update alpha publishing to point to v3 branch

* Update other v2 reference

* Another 2

* Add diff highlighting line transformer (#88)

* fix typo in CONTRIBUTING.md

* fix formatting error preventing tests in src/utils.js

* wip: diff line transformer draft implementation

* add diff line transformer integration test

* diffLineTransformer return new v3 gutterCells prop

* readme fix typo

* pick default red/green colors for diff line highlighting

* fix diffLineTransformer.schemaExtension,  avoid mutating input params

* don't require diff lines to start with +/-

* Update tests, fix type errors

* Remove postfix space requirement

Co-authored-by: Andrew Branch <[email protected]>

* Add GraphQL testing infrastructure

* Update workflows and CONTRIBUTING.md

* Add missing proc.kill

* Ignore tty message?

* Remove meta from test query because apparently languageId isn’t stable

* Totally ignore tty error

* Update snapshot

* Shallow checkout vscode

* Pick a reasonable default for line highlight color based on theme background color (#106)

* Detect dark themes by luminance

* Fix dependencies

* Update README

* Update MIGRATING

* Add test, adjust light default color

* Ignore report.html

* Don’t cache in GraphQL tests

* Officially deprecate `codeFenceNode`

* Add line number docs

* Add diff highlighting docs

* Remove old `colorTheme` option

* Update baselines

Co-authored-by: Janosh Riebesell <[email protected]>

Author: andrewbranch

.github/workflows/main.yml

@@ -30,9 +30,9 @@ jobs:
       with:
         node-version: ${{ matrix.node }}
     - name: install
-      run: npm ci
+      run: yarn install --frozen-lockfile
     - name: test
-      run: npm test
+      run: yarn test
   publish:
     if: github.event_name == 'release'
     needs: build_test
@@ -45,9 +45,9 @@ jobs:
         node-version: '12'
         registry-url: 'https://registry.npmjs.org'
     - name: install
-      run: npm ci
+      run: yarn install --frozen-lockfile
     - name: build
-      run: npm run build
+      run: yarn build
     - name: publish production
       run: npm publish
       env:
@@ -64,9 +64,9 @@ jobs:
         node-version: '12'
         registry-url: 'https://registry.npmjs.org'
     - name: install
-      run: npm ci
+      run: yarn install --frozen-lockfile
     - name: build
-      run: npm run build
+      run: yarn build
     - name: publish alpha
       run: |
         version=`node .github/workflows/getVersion.js 3.0.0`

.gitignore

@@ -71,4 +71,4 @@ lib/extensions
 # Autogenerated content
 lib/grammars
 lib/themes
-test/integration/viewer/report.html
+test/html/viewer/report.html

CONTRIBUTING.md

@@ -10,20 +10,22 @@ PRs introducing new ideas are always welcome, but might be declined if opened wi
 
 ## Local development setup
 
-Prerequisites: development is supported on the current [Node LTS](https://nodejs.org/).
+Prerequisites: development is supported on the current [Node LTS](https://nodejs.org/). Yarn is probably required to run all tests correctly, because npm fails to deduplicate certain dependencies which causes issues for running the GraphQL tests.
 
 1. Fork and clone the repo.
-2. Run `npm install`
+2. Run `yarn`
 
-Running `npm install` should automatically initialize or update the [vscode](./vscode) submodule, generate `src/graphql/schema.d.ts`, and populate [`lib/grammars`](lib/grammars) and [`lib/themes`](lib/themes). If any of these things are missing, you’ll errors when you try to run things later. You can rerun these steps with `npm run build`.
+Running `yarn` should automatically initialize or update the [vscode](./vscode) submodule, generate `src/graphql/schema.d.ts`, and populate [`lib/grammars`](lib/grammars) and [`lib/themes`](lib/themes). If any of these things are missing, you’ll get errors when you try to run things later. You can rerun these steps with `yarn build`.
 
 ## Tests
 
-To run tests, run `npm test`. You can use Jest CLI options after a `--` separator. For example, to run just the test named “code-fence-meta”, use `npm test -- -t code-fence-meta`.
+To run tests, run `yarn test`. You can use any Jest CLI options. For example, to run just the test named “code-fence-meta”, use `yarn test -t code-fence-meta`.
 
-Most tests are either Jest snapshot tests or HTML baseline tests against a known-good source ([`test/integration/cases/baselines`](test/integration/cases/baselines)). To update the snapshots and baselines, run `npm test -- -u`.
+Most tests are either Jest snapshot tests or HTML baseline tests against a known-good source ([`test/html/cases/baselines`](test/html/baselines)). To update the snapshots and baselines, run `yarn test -u`.
 
-Most new tests can be integration tests. To write one, create a new folder in `test/integration/cases`, then put a Markdown file named `test.md` inside. If you want to run the plugin with custom options, place an `options.js` file whose `module.exports` is the options object to be passed to the plugin. Then, when you next run `npm test`, the baseline will be created and opened in a browser so you can view the resulting HTML. If it looks right, commit it and you’re done. If it looks wrong, you can overwrite the bad baseline by running `npm test -- -u -t name-of-test` after you’ve made changes to fix your code.
+Most new tests can be baseline tests. To write one, create a new folder in `test/cases`, then put a Markdown file named `test.md` inside. If you want to run the plugin with custom options, place an `options.js` file whose `module.exports` is the options object to be passed to the plugin. Then, when you next run `yarn test`, the baseline will be created and opened in a browser so you can view the resulting HTML. If it looks right, commit it and you’re done. If it looks wrong, you can overwrite the bad baseline by running `yarn test -u -t name-of-test` after you’ve made changes to fix your code.
+
+Tests inside `test/cases` also generate a snapshot of a GraphQL query for the structured syntax highlighting data the plugin generates. The snapshot has a lot of data, so if you’re adding a new test case, don’t worry about manually inspecting every line of the added snapshot. They exist mostly to detect regressions, so if the snapshot looks plausibly correct, go ahead and commit it.
 
 ## Debugging
 
@@ -34,7 +36,7 @@ VS Code launch scripts have been provided, so you can debug the tests or the [ex
 When you’ve made changes you’re happy with, ensure that you have
 
 - Added a test if appropriate,
-- Formatted your changes through Prettier with `npm run format`,
+- Formatted your changes through Prettier with `yarn format`,
 - Maintained good JSDoc type annotations to the best of your ability.
 
-This project is written in plain JavaScript, but uses TypeScript to type-check via JSDoc annotations. After tests, type checking runs (and can be run alone with `npm run check`). If types are new to you, or you have trouble getting type checking to pass, that’s ok! I’ll help you in your PR if necessary. Type checking is a great way to catch errors early, but I don’t want it to be an impediment for anyone’s contribution.
+This project is written in plain JavaScript, but uses TypeScript to type-check via JSDoc annotations. After tests, type checking runs (and can be run alone with `yarn check`). If types are new to you, or you have trouble getting type checking to pass, that’s ok! I’ll help you in your PR if necessary. Type checking is a great way to catch errors early, but I don’t want it to be an impediment for anyone’s contribution.

MIGRATING.md

@@ -1,5 +1,17 @@
 # Migration Guide
 
+## v2 → v3
+
+### Line highlighting is visible without custom CSS.
+
+Previously, the default line highlight background color was `transparent`, which meant a color had to be set with a CSS variable by the user. The reason for this limitation was that there is no sensible default that works for both light themes and dark themes, as a light highlight would be invisible on white, and a dark highlight would be invisible on black. As of v3, the plugin the luminance of each theme’s background color and selects a translucent white or translucent black highlight color as a default.
+
+This is unlikely to break existing sites, as the CSS variables continue to work as a customization. However, as part of upgrading to v3, you may be able to remove the variables you set if you’re happy with the new defaults. If, for some reason, you were relying on the old behavior of an invisible default, sorry, don’t do that 🤷🏻‍♂️
+
+### The `codeFenceNode` property of option callback arguments is deprecated.
+
+The `theme` and `wrapperClassName` plugin options accept a callback function that receives an object with a `codeFenceNode` containing the original Remark MDAST node for the code block currently being highlighted. That property has been renamed `node`. I’m like a million percent sure nobody uses this, but if I don’t say it here, someone will complain when I remove it in 4.0.
+
 ## v1 → v2
 
 ### Extensions are no longer downloaded automatically.
@@ -49,4 +61,4 @@ The new `theme` option also supports some options that `colorTheme` did not; you
 
 ### Known issues
 
-- Usage with [gatsby-plugin-mdx](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx) requires [email protected] or later.
+- Usage with [gatsby-plugin-mdx](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx) requires [email protected] or later.

README.md

@@ -26,6 +26,8 @@ If you’re updating from v1.x.x to v2.x.x, see [MIGRATING.md](./MIGRATING.md).
 - [Extra stuff](#extra-stuff)
   - [Inline code highlighting](#inline-code-highlighting)
   - [Line highlighting](#line-highlighting)
+  - [Line numbers](#line-numbers)
+  - [Diff highlighting](#diff-highlighting)
   - [Using different themes for different code fences](#using-different-themes-for-different-code-fences)
   - [Arbitrary code fence options](#arbitrary-code-fence-options)
 - [Options reference](#options-reference)
@@ -199,7 +201,7 @@ The following languages and themes can be used without [installing third-party e
 
 </details>
 
-Language names are resolve case-insensitively by any aliases and file extensions listed in the grammar’s metadata. For example, a code fence with C++ code in it can use [any of these language codes](https://github.com/Microsoft/vscode/blob/da3c97f3668393ebfcb9f8208d7616018d6d1859/extensions/cpp/package.json#L20-L21). You could also check the [built-in grammar manifest](https://unpkg.com/[email protected]/lib/grammars/manifest.json) for an exact list of mappings.
+Language names are resolved case-insensitively by any aliases and file extensions listed in the grammar’s metadata. For example, a code fence with C++ code in it can use [any of these language codes](https://github.com/Microsoft/vscode/blob/da3c97f3668393ebfcb9f8208d7616018d6d1859/extensions/cpp/package.json#L20-L21). You could also check the [built-in grammar manifest](https://unpkg.com/[email protected]/lib/grammars/manifest.json) for an exact list of mappings.
 
 ### Themes
 
@@ -357,6 +359,12 @@ See [`inlineCode`](#inlinecode) in the options reference for more API details.
 
 `gatsby-remark-vscode` offers the same line-range-after-language-name strategy of highlighting or emphasizing lines as [gatsby-remark-prismjs](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-prismjs):
 
+<table>
+<thead><tr><th>Markdown</th><th>Rendered result</th></thead>
+<tbody>
+<tr>
+<td>
+
 ````md
 ```js{1,3-5}
 this.isLine(1); // highlighted
@@ -367,8 +375,24 @@ this.isLine(5); // highlighted
 ```
 ````
 
+</td>
+<td>
+
+![][line-highlighting-meta]
+
+</td>
+</tr>
+</tbody>
+</table>
+
 Comment directives are also supported:
 
+<table>
+<thead><tr><th>Markdown</th><th>Rendered result</th></thead>
+<tbody>
+<tr>
+<td>
+
 ````md
 ```js
 function constant(value) {
@@ -387,24 +411,114 @@ const zero = [0, 1, 2, 3, 4, 5]
 ```
 ````
 
-You need to pick your own background color, and optionally a left border width and color, for the highlighted lines. This can be done by setting CSS variables:
+</td>
+<td>
+
+![][line-highlighting-comment]
+
+</td>
+</tr>
+</tbody>
+</table>
+
+You can customize the default background color and left border width and color for the highlighted lines by setting CSS variables:
 
 ```css
 :root {
-  --grvsc-line-highlighted-background-color: rgba(255, 255, 255, 0.2); /* default: transparent */
-  --grvsc-line-highlighted-border-color: rgba(255, 255, 255, 0.5); /* default: transparent */
-  --grvsc-line-highlighted-border-width: 2px; /* default: 4px */
+  --grvsc-line-highlighted-background-color: rgba(255, 255, 255, 0.2);
+  --grvsc-line-highlighted-border-color: rgba(255, 255, 255, 0.5);
+  --grvsc-line-highlighted-border-width: 2px;
 }
 ```
 
-or by setting custom styles on the lines:
+### Line numbers
 
-```css
-.grvsc-container .grvsc-line-highlighted {
-  background-color: rgba(255, 255, 255, 0.2);
-  box-shadow: inset 2px 0 0 0 rgba(255, 255, 255, 0.5);
+With code fence info:
+
+````md
+```js {numberLines}
+import * as React from 'react';
+
+React.createElement('span', {});
+```
+````
+
+![Rendered result of the example code above][line-numbering-with-code-fence-info]
+
+With code fence info specifying a starting line:
+
+````md
+```js {numberLines: 21}
+  return 'blah';
+```
+````
+
+![Rendered result of the example code above][line-numbering-starting-line]
+
+With a comment:
+
+````md
+```ts
+function getDefaultLineTransformers(pluginOptions, cache) {
+  return [
+    one, // L4
+    two,
+    three
+  ];
 }
 ```
+````
+
+![Rendered result of the example code above][line-numbering-with-a-comment]
+
+With both:
+
+````md
+```ts {numberLines}
+import * as React from 'react';
+
+// ...
+
+function SomeComponent(props) { // L29
+  return <div />;
+}
+```
+````
+
+![Rendered result of the example code above][line-numbering-with-both]
+
+The line number cell’s styling can be overridden on the `.grvsc-line-number` class.
+
+### Diff highlighting
+
+You can combine syntax highlighting with diff highlighting:
+
+<table>
+<thead><tr><th>Markdown</th><th>Rendered result</th></thead>
+<tbody>
+<tr>
+<td>
+
+````md
+```ts {diff}
+function add(x, y) {
+-  return x + x;
++  return x + y;
+}
+```
+````
+
+</td>
+<td>
+
+![][diff-highlighting]
+
+</td>
+</tr>
+</tbody>
+</table>
+
+The highlight color can be customized with the CSS variables `--grvsc-line-diff-add-background-color` and `--grvsc-line-diff-del-background-color`. The default color is static and might not be accessible with all syntax themes. Consider contrast ratios and choose appropriate colors when using this feature.
 
 ### Using different themes for different code fences
 
@@ -424,10 +538,10 @@ Line numbers and ranges aren’t the only things you can pass as options on your
 
 ```js
 {
-  theme: ({ parsedOptions, language, markdownNode, codeFenceNode }) => {
+  theme: ({ parsedOptions, language, markdownNode, node }) => {
     // 'language' is 'jsx', in this case
     // 'markdownNode' is the gatsby-transformer-remark GraphQL node
-    // 'codeFenceNode' is the Markdown AST node of the current code fence
+    // 'node' is the Markdown AST node of the current code fence
     // 'parsedOptions' is your parsed object that looks like this:
     // {
     //   theme: 'Monokai',
@@ -436,7 +550,7 @@ Line numbers and ranges aren’t the only things you can pass as options on your
     // }
     return parsedOptions.theme || 'Dark+ (default dark)';
   },
-  wrapperClassName: ({ parsedOptions, language, markdownNode, codeFenceNode }) => '';
+  wrapperClassName: ({ parsedOptions, language, markdownNode, node }) => '';
 }
 ```
 
@@ -550,3 +664,10 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for development instructions.
 [templates-own]: https://user-images.githubusercontent.com/3277153/56853802-5e847e00-68c8-11e9-8468-dedcd8bcab78.png
 [solidity-others]: https://user-images.githubusercontent.com/3277153/56853799-5e847e00-68c8-11e9-8895-535d9e0d555c.png
 [solidity-own]: https://user-images.githubusercontent.com/3277153/56853800-5e847e00-68c8-11e9-9c83-5e76146d5e46.png
+[line-highlighting-meta]: https://user-images.githubusercontent.com/3277153/86545712-6fc21500-bee5-11ea-8a83-71d04f595ef4.png
+[line-highlighting-comment]: https://user-images.githubusercontent.com/3277153/86545710-6e90e800-bee5-11ea-9f4d-33278d9312d7.png
+[line-numbering-with-a-comment]: https://user-images.githubusercontent.com/3277153/87123264-3ff37400-c23b-11ea-8ae6-80cbfcf6b6a0.png
+[line-numbering-with-code-fence-info]: https://user-images.githubusercontent.com/3277153/87122757-5ea53b00-c23a-11ea-8fbc-c85917433345.png
+[line-numbering-with-both]: https://user-images.githubusercontent.com/3277153/87122755-5ea53b00-c23a-11ea-8fe8-144aea7aa952.png
+[line-numbering-starting-line]: https://user-images.githubusercontent.com/3277153/87122747-5c42e100-c23a-11ea-9a06-923c699c0a0b.png
+[diff-highlighting]: https://user-images.githubusercontent.com/3277153/87123984-aa58e400-c23c-11ea-87b3-3f66afcd795d.png