Highlight CSS-Themes Examples

Written by Tristano Ajmone, Oct 24, 2017, last edited on Jun 13, 2018. This document is released under MIT License (MIT).

Latest theme boilerplates, v1.0 (2017/10/25):

All theme boilerplates are public domain.


Language definition files define the syntax of language elements. Colour themes define how these language elements should be formatted in the final highlighted document.

Highlight theme files are Lua files that can handle formatting for various output formats, including HTML. While Highlight themes support basic formatting (Colour, Bold, Italic, and Underline), when targeting HTML output you might desire finer control over styling, especially when working in a website, and thus opt to define your custom CSS themes — or use Sass, Less, Stylus, or some other language for compiling CSS.

In order to facilitate creating custom CSS Highlight themes, here you’ll find:

  1. Some introductory notes on how Highlight formats its HTML Output.
  2. A reference table listing the various language elements and their corresponding CSS classes.
  3. A Sass and a CSS boilerplate to start building you custom themes.

Notes on Highlight HTML Output

Highlight’s default behaviour for HTML output is to enclose the code block within a preformatted block with class hl (<pre class="hl">), and then enclose all the various language elements within <span> tags with the hl class along the element’s corresponding class.

NOTE: Highlight doesn’t nest <span> tags in its output! Before a new tag is opened, the previous one is always closed.

Example source:

# A very simple Python program
print("Hello World!")

Example HTML output:

<pre class="hl"><span class="hl slc"># A very simple Python program</span>
<span class="hl kwa">print</span><span class="hl opt">(</span><span class="hl str">&quot;Hello World!&quot;</span><span class="hl opt">)</span>

Line numbers too are handled via a span tag with lin class (<span class="hl lin">):

<pre class="hl"><span class="hl lin">    1 </span><span class="hl slc"># A very simple Python program</span>
<span class="hl lin">    2 </span><span class="hl kwa">print</span><span class="hl opt">(</span><span class="hl str">&quot;Hello World!&quot;</span><span class="hl opt">)</span>

Table of Language Elements’ CSS Classes

The CSS counterparts of a theme’s Default and Canvas definitions are the definitions of the <pre> tag with hl class:

Element CSS Description
Default pre.hl { ... } Attributes of unspecified text
Canvas pre.hl { background: ...; } Code block background properties

The rest of the language elements counterparts (including line numbers) concern <span> tags with the following classes:

Element CSS Description
Number .hl .num Numbers
Escape .hl .esc Escape sequences
Interpolation .hl .ipl Interpolation sequences
String .hl .str Strings
PreProcessor .hl .ppc Preprocessor directives
StringPreProc .hl .pps Strings within preprocessor directives
BlockComment .hl .com Block comments
LineComment .hl .slc Single-line comments
LineNum .hl .lin Line numbers
Operator .hl .opt Operators
Keywords>Id=1 .hl .kwa Keywords group 1 (a)
Keywords>Id=2 .hl .kwb Keywords group 2 (b)
Keywords>Id=3 .hl .kwc Keywords group 3 (c)
Keywords>Id=4 .hl .kwd Keywords group 4 (d)

NOTE: To define CSS Keywords groups above Id=4, just keep incrementing the last letter in the “.kw*” class name — Eg: .kwe, .kwf, .kwg, …, .kwz.

Sass/CSS Boilerplates

In this folder you’ll find two boilerplate files that you can use as a starting point to build your custom Highlight CSS themes:

These boilerplates are useful because they contain all the classes covering Highlight language elements, with comments remind their Lua counterparts names. By using a boilerplate, you’ll be reminded to cover all syntax elements, without the need to lookup any tables.

There is also an example HTML document showing how the CSS boilerplate looks like:


With the exception of this HTML document, all files in this folder are released into public domain under the terms of the Unlicense:


This documented was created using the GitHub Pandoc HTML5 Template, which is MIT Licensed:

Copyright (c) Tristano Ajmone, 2017 (github.com/tajmone/pandoc-goodies)
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
Copyright (c) 2017 GitHub Inc.

For full details about the license, see the comments in the HTML source of this document.