MacRabbit

SyntaxThemes

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

Syntax Inspector

To find out what syntax zones you can target, choose Actions→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 to 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 install a syntax theme, copy the CSS file to this folder (you may need to create the folder if it does not exist):

~/Library/Application Support/Espresso/Themes

To access your Library folder in Lion, hold down option while you click the Go menu in the Finder, and then click the Library item. Alternatively, run this in Terminal to permanently unhide your Library:

chflags nohidden ~/Library

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 includes 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 might also need to specify which placeholder themes you are overriding:

/*
    @theme My Theme Name
    @override-placeholders identifier, other.identifier
*/ 

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

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 (this example zone will disable spell-check in all built-in languages and most Espresso 1-inspired themes):

apachecssjsphppythonrubytagsourcecodesource {
    spell
-checkdisabled;