MIGRATING.md

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 computes 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.

• If you did not use themes or languages beyond the default included set, no change is necessary.
• If you relied on the extensions plugin option to download extensions:
  • Find the extension source on GitHub, npm, or elsewhere. (Extensions listed on the Visual Studio Marketplace typically link to their GitHub repos.)
  • Ensure the license allows you to use the code on your site, and follow all license requirements.
  • Install or copy the extension into your project:
    • You can install from GitHub by running npm install owner-name/repo-name.
    • If you clone the source and build a .vsix, you can copy that file into your project.
    • Alternatively, you can copy the full extension source or clone as a submodule into your project.
  • Replace the extensions array with an array of strings specifying where to find each extension:
    • If you installed the extension into node_modules, use just the package name, e.g. extensions: ['oceanic-next']
    • If you copied the extension source or .vsix into your project, use an absolute path, e.g. extensions: [`${__dirname}/vendor/oceanic-next.vsix`, `${__dirname}/vendor/atom-one-dark`]
• If you used the extensionDataDirectory option, it should be unnecessary now, since all extensions are read from disk. You can specify a specific location for each extension by providing paths to the extensions array.

The colorTheme plugin option has been deprecated and replaced by the theme option.

• If you did not supply colorTheme, no change is necessary.
• If your colorTheme is a string, rename the colorTheme key to theme.
• If your colorTheme is an object:
  • Rename the defaultTheme key to default.
  • If present, rename the prefersDarkTheme to dark.
  • If you have a prefersLightTheme, replace it with an entry in the new media array. For example:

{
-  defaultTheme: 'Default Dark+',
-  prefersLightTheme: 'Solarized Light'
+  default: 'Default Dark+',
+  media: [{
+    match: '(prefers-color-scheme: light)',
+    theme: 'Solarized Light'
+  }]
}

The new theme option also supports some options that colorTheme did not; you can read about the full API in the README.

CSS variables and class names have changed

• If you wrote custom CSS targeting the class .vscode-highlight, replace that selector with .grvsc-container.
• If you wrote custom CSS targeting any other class beginning with .vscode-highlight, replace the .vscode-highlight prefix with .grvsc. For example, .vscode-highlight-line is now .grvsc-line.
• If you set any CSS variables, replace the --vscode-highlight prefix with --grvsc. For example, --vscode-highlight-border-radius is now --grvsc-border-radius.
• If you wrote custom CSS targeting a token class name beginning with .mtk, that was never intended to be supported! Consider using replaceColor instead, or file an issue if you think you have a compelling use case for writing custom token CSS.

Known issues

• Usage with gatsby-plugin-mdx requires gatsby-plugin-mdx@1.0.71 or later.