Introduction

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.

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>
</pre>

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>
</pre>

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:

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

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:

• hl-theme-boilerplate.scss — The Sass SCSS boilerplate.
• hl-theme-boilerplate.css — The CSS boilerplate (built by compiling the previous file).

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:

• example.html

Unlicense

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

• http://unlicense.org

Credits

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.