-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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]>
- Loading branch information
1 parent
0bdaa18
commit 4ce88a1
Showing
99 changed files
with
37,294 additions
and
6,250 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
Oops, something went wrong.