Requirements

Make sure you have the following programs installed:

  1. git
  2. nodejs

Start

First of all, let’s try to package this extension and install it to your vscode.

1
2
3
4
5
$ git clone --depth 1 https://github.com/sainnhe/gruvbox-material-vscode.git
$ cd gruvbox-material-vscode
$ npm install
$ npm run package
$ code --install-extension ./gruvbox-material-6.2.1.vsix

Now, use vscode to open this project and modify some code, then press F5 to start debugging.

The theme files

The most critical files for a theme extension are some json files located in /themes, they defined all the colors of a theme.

A theme file can be roughly divided into three parts:

For all available workbench colors, see this documentation.

To get current token of syntax highlighting or semantic highlighting, press Ctrl+Shift+P to open command panel and search for “Inspect Editor Tokens and Scopes”.

In this extension, the json files will be automatically generated when user configuration changes, so don’t keep your changes in the json files, but modify the typescript code instead.

Publishing

I’ve setup a github action for this repository that can publish this extension to vscode marketplace and open vsx registry automatically when a new tag is created. For example, to release v6.2.10, do something like this:

  1. Edit package.json and package-lock.json, modify the version field: "version": "6.2.10",
  2. Commit this change: $ git commit -am "release v6.2.10"
  3. Create a tag: $ git tag -a v1.2.0 and edit the tag message based on CHANGELOG.md
1
2
3
v6.2.10
- Publish to open vsx registry.
- Setup a pre-commit hook that can regenerate the theme file using default settings.
  1. Push the commit and tag to github: $ git push origin master v6.2.10

Some designs

There are 3 workbench styles available in this theme:

It’s highly recommended to try them first if you want to modify the code of a workbench style.

In addition, this theme is designed to be borderless, so please DO NOT add unnecessary borders.

There are 2 syntax highlighting logic available in this theme: default and colorful

In the default syntax highlighting logic, only minimum but necessary tokens will be colored, because if everything is special, then nothing is special.

Unnecessary tokens include: variables, properties, members, parameters, etc.

In contrast, in the colorful syntax highlighting logic, as many tokens as possible will be colored.

Note

  • I’ve setup 2 pre-commit hook, one of which is used to generate /themes/*.json automatically using default user settings. So when developing this extension, don’t care about how the themes files looks like but just focus on the typescript code.
  • DO NOT add new colors or modify existing colors in /src/palette. The current color palettes are very carefully designed and tested on several devices. If you do want to change the color palettes, create a new theme extension instead.
  • Don’t add new configuration options casually, there are already so many configuration options and too many options may confuse users.
  • Don’t forget to update the changelog.
  • Don’t forget to update italic syntax file if the syntax source code is modified.
  • Comments including {{{ or }}} are vim fold markers, I use them to fold the code in vim, so don’t delete them.