A plugin for Sublime Text 2/3 for highlighting text with pretty colours.

• The easiest way is through Package Control (Shift+Ctrl+P > Install Package > Synesthesia).
• Alternatively, clone this repository into Packages/synesthesia.

• Open the Command Palette (Shift+Ctrl+P) and select New Highlighting Scheme.
• Save the file as Hello World.json.
• Select Compile Highlighting Scheme from the Command Palette.
• Select Set Syntax: Hello World from the Command Palette. Voila!
• To change keywords or colours, simply compile again.

This plugin provides a quick and lightweight way to highlight text with different colours.

It takes a highlighting scheme, which is a description of words to highlight and how they should look, and generates all the necessary configuration files for Sublime to render them that way.

This is essentially an abstraction for creating a language definition, but much easier to use: you don't have to deal with all that complexity if all you need is to bring attention to a few terms in your text, colour a log file, etc.

The rest of this readme thoroughly documents all the options you can use. You may also wish to browse the examples in Packages/synesthesia/include.

• Ad-hoc highlighting of text. This plugin is a quick and lightweight way to draw attention to important articles in your text. A few example uses:
  • Highlighting keywords in log files
  • Drawing attention to characters or locations in writing
  • Visualising colours (check out Pretty.json)
  • Lightweight markup (check out MarkdownEditing for Markdown)
  • Quick-and-dirty way to add keywords to existing language definitions
• This plugin is not an easier way to specify syntax highlighting for a programming language. A list of regular expressions isn't a great way to handle most programming languages. Making syntax highlighting easier is the niche AAAPackageDev fills.

Keyword colours are specified as RGB in hexadecimal form (#rrggbb). We can also use colour names, like blue or red; a list of these can be found here.

Two additional colour types are available: random and auto. random will give a random colour on every compile, while the colour that auto generates is fixed. Both will only generate nice bright colours.

{
	'keywords': {
		'roses': '#ff0000',
		'violets': 'blue',
		'lazy?': 'random',
		'no problem!': 'auto'
	}
}

Options can be specified instead of a colour name or value:

{
	'keywords': {
		'something': {
			'colour': 'plum',
			'background': 'blue',
			'bold': true,
			'italics': true,
			'whole-word': true,
			'case-insensitive': true
		}
	}
}

• All fields are optional, including colour.
• background controls the background colour of highlighted keywords. It's used the same way colour is.
• whole-word will make sure only whole occurrences of keywords are matched. If set to true, the 'java' in 'javascript' won't be coloured.

Keywords are specified using Oniguruma regular expressions, which is what Sublime uses under the hood. Don't worry if you aren't familiar with these: alphanumeric strings are valid regexes, so you don't need to be an expert to use this plugin.

We may find ourselves always wanting to highlight the same things. For example, we want ERROR to appear red, in bold font, whether in upper case or lower. It can be tiresome to define it again and again.

That's where this option comes in. Highlighting schemes can be mixed into others with include, so we can easily separate and combine them:

{
	'include': ['LightMarkdown'],
	'keywords': {
		...
	}
}

This will cause the keywords and colours in LightMarkdown.json to be copied into the current scheme on compile.

Here's how Synesthesia will search for schemes to mix in:

• The directory that the current scheme is in will first be checked for the mixins specified.
• If a mixin can't be found there, Packages/synesthesia/include will be checked next.
• Dependencies will be resolved recursively, depth-first, in the order they are specified. Circular dependencies are prevented.
• If a keyword has appeared before, it won't be overridden should it appear again in a later-loaded dependency.

File extensions for highlighting schemes go under extensions. This is so they apply automatically when files of the type are opened.

{
	'extensions': ['txt', 'md'],
	'keywords': {...}
}

By default, txt and md will be used.

{
	'autocompletion': true,
	'keywords': {...}
}

If set to true, Sublime's autocompletion will be enabled in the generated language definition.

{
	'keywords': {
		...
	},
	'settings': {
		'font_face': 'Open Sans'
	}
}

Other settings for the generated language definition go here.

To remove highlighting schemes, select Remove Highlighting Scheme from the Command Palette.

Don't delete the files manually. Sublime Text will complain about that, and you might have to reinstall the package to fix the resulting errors.

Creating new language definitions for our highlighting schemes keeps things cleanly separated, but sometimes that's not what we want. For example, you might want to have regular JavaScript syntax highlighting and just highlight // TODO-style comments in a different colour. Maybe you use this plugin for writing and would like all the features of MarkdownEditing's awesome langauge definition together with your highlighted words.

The deriving option handles these cases.

This section is a little more involved. It may be helpful to give these articles on how language grammars, scopes, and scope selectors work in TextMate/Sublime a quick read.

deriving allows us to extend an existing language definition; instead of generating a new language, we're going to open the existing one and just drop our additions inside.

{
    "deriving": {
        "tmLanguage": "Markdown",
        "tmTheme": "MarkdownEditor-Dark",
        "sublime-settings": "Markdown",
        "tmLanguage_scope": "repository.inline"
    },
    "keywords": {
    	...
    }
}

Here's an example using the MarkdownEditing language definition. All fields are required.

First we must get hold of three files from the package:

• Language definition (.tmLanguage)
• Colour theme (.tmTheme)
• Settings (.sublime-settings)

These are the files we will extend. They will be searched for in the directory that the current scheme is in, then Packages/synesthesia.

To locate them you may have to look inside your .sublime-package files.

deriving will insert the new keywords under the repository of the existing tmLanguage file; this way they can be easily referenced and used throughout it.

Finally, it will make the existing language definition aware of the additions by inserting references to them into the appropriate places. In this case that's repository.inline (this is nonstandard notation, as it denotes a path in the tmTheme file rather than a scope). inline is the scope for all of the inline text you see in Markdown documents, so that's where our additions will surface. You might have to poke around the .tmTheme file to figure out the best or most general location for this. This differs between language definitions so it unfortunately cannot be done automatically.

Compiling a highlighting scheme generates three files:

• Language definition (.tmLanguage)
• Colour theme (.tmTheme)
• Settings (.sublime-settings)

The first two work in tandem, specifying a mini-language consisting of the user's keywords, along with a colour theme designed specifically for that mini-language. The settings file glues them together, causing Sublime Text to associate the theme with the mini-language. All this is done via Sublime Text's built-in mechanisms for syntax highlighting, so it's robust and stable.

Other plugins for highlighting arbitrary words do so either via named regions or by mutating the current colour theme.

• The first method doesn't interact well with live editing and is limited to only changing the background colour of text.
• The second provides a slightly higher level of flexibility (for example, there may be no need to switch to a different language) but is much more complex implementation-wise. It also may not play nice with all language definitions and colour schemes.

The method used in this plugin, while static, is great for live editing and is much simpler to manage. Interactions with other language definitions are also made explicit. I see it as the middle ground between these approaches.

MIT