Highlight

Advanced text highlighter based on regexes. Useful for todos, annotations, colors etc.

There are alternative extensions that you may be considering, like TODO Highlight, but this is more generic, this can apply different styles to different capturing groups within the same regex, and this is focused on doing only one thing and doing it well.

Install

Follow the instructions in the Marketplace, or run the following in the command palette:

ext install fabiospampinato.vscode-highlight

Commands

It adds 1 command to the command palette:

'Highlight: Force Decorate' // Explicitly force all editors to be re-decorated

Settings

{
  "highlight.decorations": { "rangeBehavior": 3 }, // Default decorations from which all others inherit from
  "highlight.regexFlags": "gi", // Default flags used when building the regexes
  "highlight.regexes": {}, // Object mapping regexes to options or an array of decorations to apply to the capturing groups
  "highlight.minDelay": 50, // Minimum number of milliseconds to wait before highlighting the document after a change, used for throttling
  "highlight.maxMatches": 250 // Maximum number of matches to decorate per regex, in order not to crash the app with accidental cathastropic regexes
}

An example configuration could be:

"highlight.regexes": {
  "(//TODO)(:)": [ // A regex will be created from this string, don't forget to double escape it
    { "color": "yellow" }, // Decoration options to apply to the first capturing group, in this case "//TODO"
    { "color": "red" } // Decoration options to apply to the second capturing group, in this case ":"
  ]
}

If you want to have different regex flags for different regexes, or if you want to apply the decorations on a per-language/file basis you'll have to express your configuration like this:

"highlight.regexes": {
  "(//TODO)(:)": { // A regex will be created from this string, don't forget to double escape it
    "regexFlags": "g", // Flags used when building this regex
    "filterLanguageRegex": "markdown", // Apply only if current file's language matches this regex. Requires double escaping
    "filterFileRegex": ".*\\.ext", // Apply only if the current file's path matches this regex. Requires double escaping
    "decorations": [ // Decoration options to apply to the capturing groups
      { "color": "yellow" }, // Decoration options to apply to the first capturing group, in this case "//TODO"
      { "color": "red" } // Decoration options to apply to the second capturing group, in this case ":"
    ]
  }
}

Decoration values can also include placeholders like $1 or $2 that will be replaced with the content of the respective capturing group, enabling complex use cases like CSS colors highlighting.

All the supported decoration options are defined here.

Warnings

1. Regexes need to be double-escaped, once for JSON and the second time for the regex itself.
2. All characters of the matched string must be wrapped in a capturing group.
3. For each capturing group a decorations options object must be provided (empty decorations are allowed: {}), otherwise the actual decorations will be misaligned.
4. Nested capturing groups are not supported.
5. If you want to match the start/end of a line make sure the regex has the "m" (multiline) flag.

Demo

Basic

The following configuration:

Transforms this:

Into this:

Advanced Todos

The following is the configuration I'm currently using for highlighting todos, it's much more robust than the previous demo configuration, and it supports JavaScript/HTML-style comments, urls, multiple todos in a single line, common templating languages, and Todo+-style tags.