gatsby-remark-vscode


A syntax highlighting plugin for Gatsby that uses VS Code’s extensions, themes, and highlighting engine. Any language and theme VS Code supports, whether built-in or via a third-party extension, can be rendered on your Gatsby site.

Includes OS dark mode support 🌙

v3 is out now! 🎉

If you’re updating from v2.x.x (or v1), see MIGRATING.md. New features are line numbers and diff highlighting (thanks @janosh for the latter!).

Table of contents

- Why gatsby-remark-vscode?
- Getting started
- Multi-theme support
- Built-in languages and themes
- Languages
- Themes
- Using languages and themes from an extension
- Styles
- Class names
- Variables
- Tweaking or replacing theme colors
- Extra stuff
- Inline code highlighting
- Line highlighting
- Line numbers
- Diff highlighting
- Using different themes for different code fences
- Arbitrary code fence options
- Usage as a remark plugin without Gatsby
- Options reference
- Contributing

Why gatsby-remark-vscode?

JavaScript syntax highlighting libraries that were designed to run in the browser, like Prism, have to make compromises given the constraints of their intended environment. Since they get downloaded and executed whenever a user visits a page, they have to be ultra-fast and ultra-lightweight. Your Gatsby app, on the other hand, renders to HTML at build-time in Node, so these constraints don’t apply. So why make tradeoffs that don’t buy you anything? There’s no reason why the syntax highlighting on your blog should be any less sophisticated than the syntax highlighting in your code editor. And since VS Code is built with JavaScript and CSS, is open source, and has a rich extension ecosystem, it turns out that it’s pretty easy to use its highlighting engine and extensions and get great results. A few examples of where gatsby-remark-vscode excels:

| Scenario | Others | gatsby-remark-vscode |
|-------------------------|------------------------|----------------------|
| Embedded languages | ![][embedded-others] | ![][embedded-own]
| Complex TypeScript | ![][typescript-others] | ![][typescript-own]
| Tricky template strings | ![][templates-others] | ![][templates-own]
| Uncommon languages | ![][solidity-others] | ![][solidity-own]

Getting started

Install the package:

``bash
npm install --save gatsby-remark-vscode
`

Add to your gatsby-config.js:

`js
{
// ...
plugins: [{
resolve: gatsby-transformer-remark,
options: {
plugins: [{
resolve: gatsby-remark-vscode,
options: {
theme: 'Abyss' // Or install your favorite theme from GitHub
}
}]
}
}]
}
`

Write code examples in your markdown file as usual:

``md
`js
this.willBe(highlighted);
`
``

Multi-theme support

You can select different themes to be activated by media query or by parent selector (e.g. a class or data attribute on the html or body element).

$3

`js
{
theme: {
default: 'Solarized Light',
dark: 'Monokai Dimmed'
}
}
`

$3

`js
{
theme: {
default: 'Solarized Light',
parentSelector: {
// Any CSS selector will work!
'html[data-theme=dark]': 'Monokai Dimed',
'html[data-theme=hc]': 'My Cool Custom High Contrast Theme'
}
}
}
`

$3

The dark option is shorthand for a general-purpose media option that can be used to match any media query:

`js
{
theme: {
default: 'Solarized Light',
media: [{
// Longhand for dark option.
// Don’t forget the parentheses!
match: '(prefers-color-scheme: dark)',
theme: 'Monokai Dimmed'
}, {
// Proposed in Media Queries Level 5 Draft
match: '(prefers-contrast: high)',
theme: 'My Cool Custom High Contrast Theme'
}, {
match: 'print',
theme: 'My Printer Friendly Theme???'
}]
}
}
`

Built-in languages and themes

The following languages and themes can be used without installing third-party extensions:

$3

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. You could also check the built-in grammar manifest for an exact list of mappings.

$3

Pro tip: a good way to preview themes is by flipping through them in VS Code. Here’s the list of included ones:

- Abyss
- Dark+ (default dark)
- Light+ (default light)
- Dark (Visual Studio)
- Light (Visual Studio)
- High Contrast
- Kimbie Dark
- Monokai Dimmed
- Monokai
- Quiet Light
- Red
- Solarized Dark
- Solarized Light
- Tomorrow Night Blue

Using languages and themes from an extension

If you want to use a language or theme not included by default, the recommended approach is to npm install it from GitHub, provided its license permits doing so. For example, you can use robb0wen/synthwave-vscode by running

`bash
npm install robb0wen/synthwave-vscode
`

Then, in gatsby-config.js, use the options

`js
{
theme: SynthWave '84, // From package.json: contributes.themes[0].label
extensions: ['synthwave-vscode'] // From package.json: name
}
`

You can also clone an extension into your project, or build a .vsix file from its source, and specify its path in extensions:

`js
{
theme: {
default: 'My Custom Theme',
dark: 'My Custom Dark Theme'
},
extensions: ['./vendor/my-custom-theme', './vendor/my-custom-dark-theme.vsix']
}
`

Styles

The CSS for token colors and background colors is generated dynamically from each theme you use and included in the resulting HTML. However, you’ll typically want at least a small amount of additional styling to handle padding and horizontal scrolling. These minimal additional styles are included alongside the dynamically generated token CSS by default, but can be disabled by setting the injectStyles option to false. If you prefer bundling the styles through your app’s normal asset pipeline, you can simply import the CSS file:

`js
import 'gatsby-remark-vscode/styles.css';
`

$3

The generated HTML has ample stable class names, and you can add your own with the wrapperClassName and getLineClassName option. All (non-token-color) included styles have a single class name’s worth of specificity, so it should be easy to override the built-in styles.

$3

The styles also include a few CSS variables you can define to override defaults. The included CSS is written as:

`css
.grvsc-container {
padding-top: var(--grvsc-padding-top, var(--grvsc-padding-v, 1rem));
padding-bottom: var(--grvsc-padding-bottom, var(--grvsc-padding-v, 1rem));
border-radius: var(--grvsc-border-radius, 8px);
}

.grvsc-line {
padding-left: var(--grvsc-padding-left, var(--grvsc-padding-h, 1.5rem));
padding-right: var(--grvsc-padding-right, var(--grvsc-padding-h, 1.5rem));
}

/ See “Line Highlighting” section for details /
.grvsc-line-highlighted {
background-color: var(--grvsc-line-highlighted-background-color, transparent);
box-shadow: inset var(--grvsc-line-highlighted-border-width, 4px) 0 0 0 var(--grvsc-line-highlighted-border-color, transparent);
}
`

The padding values are written with cascading fallbacks. As an example, let’s consider the top and bottom padding of .grvsc-container. Each is set to its own CSS variable, --grvsc-padding-top and --grvsc-padding-bottom, respectively. Neither of these is defined by default, so it uses the value of its fallback, which is another CSS variable, --grvsc-padding-v, with another fallback, 1rem. Since --grvsc-padding-v is also not defined by default, both padding properties will evaluate to the final fallback, 1rem.

So, if you want to adjust the vertical padding, you could add the following to your own CSS:

`css
:root {
--grvsc-padding-v: 20px; / Adjust padding-top and padding-bottom /
}
`

If you want to adjust the padding-top or padding-bottom independently, you can use those variables:

`css
:root {
--grvsc-padding-top: 24px; / Adjust padding-top by itself /
}
`

$3

Since the CSS for token colors is auto-generated, it’s fragile and inconvenient to try to override colors by writing more specific CSS. Instead, you can use the replaceColor option to replace any value specified by the theme with another valid CSS value. This is especially handy for replacing static colors with variables if you want to support a “dark mode” for your site:

`js
{
replaceColor: oldColor => ({
'#ff0000': 'var(--red)',
'#00ff00': 'var(--green)',
'#0000ff': 'var(--blue)',
})[oldColor.toLowerCase()] || oldColor
}
`

Extra stuff

$3

To highlight inline code spans, add an inlineCode key to the plugin options and choose a marker string:

`js
{
inlineCode: {
marker: '•'
}
}
`

Then, in your Markdown, you can prefix code spans by the language name followed by the marker string to opt into highlighting that span:

`md
Now you can highlight inline code: js•Array.prototype.concat.apply([], array).
`

The syntax theme defaults to the one selected for code blocks, but you can control the inline code theme independently:

`js
{
theme: 'Default Dark+',
inlineCode: {
marker: '•',
theme: {
default: 'Default Light+',
dark: 'Default Dark+'
}
}
}
`

See inlineCode in the options reference for more API details.

$3

gatsby-remark-vscode offers the same line-range-after-language-name strategy of highlighting or emphasizing lines as gatsby-remark-prismjs:

Comment directives are also supported:

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);
--grvsc-line-highlighted-border-color: rgba(255, 255, 255, 0.5);
--grvsc-line-highlighted-border-width: 2px;
}
`

$3

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