Theme Guide

Key principle

Highlight.js themes are language agnostic. Instead of trying to make a rich set of highlightable classes look great in a handful of languages we have a limited set of classes that work well for many languages.

Hence, there are two important implications:

  • Highlight.js themes can tend to be minimalistic (this has improved over time).

  • It’s not always possible to exactly emulate themes from other highlighting engines.

Defining a theme

A theme is a single CSS file defining styles for the scopes listed in the scopes reference. The general guideline is to style the core/common set of classes, however an author may deliberately choose to exclude some (for example, .attr is usually left unstyled). Use our auto-check tool to provide additional guidance on this.

You are not required to invent a separate styling for every group of class names, it’s perfectly okay to group them:

.hljs-deletion {
  color: #800;

Use as few or as many unique style combinations as you want.

Auto-checking your theme

We provide a tool to auto-checking your theme to see that it provides good scope coverage.

./tools/checkTheme.js src/styles/your_theme.css

Follow the simple guidance provided to fix any issues.

Theming dos and don’ts

Don’t use:

  • non-standard borders/margin/paddings for the root container .hljs

  • specific font faces

  • font size, line height and anything that affects position and size of characters within the container

Okay to use:

  • colors (obviously!)

  • italic, bold, underlining, etc.

  • image backgrounds

These may seem arbitrary at first but it’s what has shown to make sense in practice.

There’s also a common set of rules that must to be defined for the root container verbatim:

.hljs {
  display: block;
  overflow-x: auto;
  padding: 0.5em;

If your theme lives within the core project you do not need to add these rules by hand as they are added by default during the build process.


One important caveat: don’t forget to style .subst. It’s used for parsed sections within strings and almost always should be reset to the default color:

.hljs-subst {
  color: black;


You should include a comment at the top of the CSS file with attribution and other meta data if necessary. The format is free:


Fancy style (c) John Smith <>


Also update with your contribution.

Send your contribution as a pull request on GitHub.