Language definitions

Every language is defined as a set of tokens, which are expressed as regular expressions. For example, this is the language definition for CSS:

A regular expression literal is the simplest way to express a token. An alternative way, with more options, is by using an object literal. With that notation, the regular expression describing the token would be the pattern attribute:

...
'tokenname': {
	pattern: /regex/
}
...

So far the functionality is exactly the same between the short and extended notations. However, the extended notation allows for additional options:

inside

This property accepts another object literal, with tokens that are allowed to be nested in this token. This makes it easier to define certain languages. However, keep in mind that they’re slower and if coded poorly, can even result in infinite recursion. For an example of nested tokens, check out the Markup language definition:

lookbehind

This option mitigates JavaScript’s lack of lookbehind. When set to true, the first capturing group in the regex pattern is discarded when matching this token, so it effectively behaves as if it was lookbehind. For an example of this, check out the C-like language definition, in particular the comment and class-name tokens:

rest

Accepts an object literal with tokens and appends them to the end of the current object literal. Useful for referring to tokens defined elsewhere. For an example where rest is useful, check the Markup definitions above.

alias

This option can be used to define one or more aliases for the matched token. The result will be, that the styles of the token and its aliases are combined. This can be useful, to combine the styling of a well known token, which is already supported by most of the themes, with a semantically correct token name. The option can be set to a string literal or an array of string literals. In the following example the token name latex-equation is not supported by any theme, but it will be highlighted the same as a string.

{
	'latex-equation': {
		pattern: /\$(\\?.)*?\$/g,
		alias: 'string'
	}
}

greedy

This is a boolean attribute. It is intended to solve a common problem with patterns that match long strings like comments, regex or string literals. For example, comments are parsed first, but if the string /* foo */ appears inside a string, you would not want it to be highlighted as a comment. The greedy-property allows a pattern to ignore previous matches of other patterns, and overwrite them when necessary. Use this flag with restraint, as it incurs a small performance overhead. The following example demonstrates its usage:

'string': {
	pattern: /(["'])(\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/,
	greedy: true
}

Unless explicitly allowed through the inside property, each token cannot contain other tokens, so their order is significant. Although per the ECMAScript specification, objects are not required to have a specific ordering of their properties, in practice they do in every modern browser.

In most languages there are multiple different ways of declaring the same constructs (e.g. comments, strings, ...) and sometimes it is difficult or unpractical to match all of them with one single regular expression. To add multiple regular expressions for one token name an array can be used:

...
'tokenname': [ /regex0/, /regex1/, { pattern: /regex2/ } ]
...

Prism.languages.markup.style = {
	/* tokens */
};

Prism.languages.insertBefore('markup', 'cdata', {
	'style': {
		/* tokens */
	}
});

Writing plugins

Prism’s plugin architecture is fairly simple. To add a callback, you use Prism.hooks.add(hookname, callback). hookname is a string with the hook id, that uniquely identifies the hook your code should run at. callback is a function that accepts one parameter: an object with various variables that can be modified, since objects in JavaScript are passed by reference. For example, here’s a plugin from the Markup language definition that adds a tooltip to entity tokens which shows the actual character encoded:

Prism.hooks.add('wrap', function(env) {
	if (env.token === 'entity') {
		env.attributes['title'] = env.content.replace(/&/, '&');
	}
});

Of course, to understand which hooks to use you would have to read Prism’s source. Imagine where you would add your code and then find the appropriate hook. If there is no hook you can use, you may request one to be added, detailing why you need it there.

API documentation