Syntax Themes

Espresso syntax themes are CSS files with some special comment metadata. Just like regular style sheets, syntax themes contain rules that apply to certain zones in the document. Instead of targeting the web page DOM, however, Espresso's selectors are used to target syntax zones in your documents.

There are two types of themes: user themes (one of which is chosen by the user in the Colors preferences), and placeholder themes that add default syntax coloring for a language defined by a third-party plug-in.

Syntax Inspector

To find out what syntax zones you can target, choose Help ⟩ Show Syntax Inspector. The Syntax Inspector will show you all of the syntax zones in the frontmost document, and will highlight the zone your cursor is in (you can also click a zone to highlight it in the document and see exactly what is included in that zone).

You can also use the Syntax Inspector's filter box to test out particular selectors to make sure that they only capture the zones you want to target.

Because Espresso updates syntax coloring in live time, you can open your active syntax theme and use the syntax inspector to see what a zone name is and immediately see your changes when you modify the theme.

Installing themes

To open your Themes folder, choose Espresso ⟩ Preferences... (command ,), click the Colors tab, and then click the Reveal In Finder button (for custom themes, this will open the Themes folder itself in the Finder; for the bundled Tutti Colori theme, it will highlight the Themes folder in the Finder).

To install a syntax theme, copy the CSS file to your Themes folder.

The next time you launch Espresso after copying a theme file to the Themes folder, you can select the theme in the Colors preferences.

Metadata comments

In order to identify your theme to Espresso, you need to include a metadata comment at the very top of the theme:

/*
	@theme My Theme Name
*/

If you are creating a user theme (one installed in the Themes folder above), then you will also need to specify which placeholder themes you are overriding:

/*
	@theme My Theme Name
	@override-placeholders css, less, php, apache, markdown
*/

You will need to look up the identifiers to override depending on which languages you want to support in your theme. For third-party plug-ins, right click the plug-in in the Finder, choose Show Package Contents, open the CSS file in PlaceholderThemes, and check the @placeholder value in the metadata comment.

For first-party languages, here is a list of placeholder theme identifiers.

If you are developing a placeholder theme to add default coloring for a new language to Espresso, then you will use a slightly different metadata comment:

/*
	@theme Language Placeholder Name
	@placeholder language.identifier
*/

Special selectors and properties

Espresso themes offer the following non-standard selector and properties that allow you to change default colors for the document itself:

:document-base {
	color: #000000;
	background-color: #FFFFFF;
	insertion-point-color: #000000;
	selection-background-color: default;
	current-line-background-color: #fff8dd;
}

Please note that developers of placeholder themes absolutely should not style the :document-base! This property is only appropriate in the user theme, because it modifies the look for all languages across the app.

You can also use a special spell-check property to disable automatic spell-checking in certain zones:

tag, source, sourcecode {
	spell-check: disabled;
}