Style guide

Key principle

Highlight.js themes are language agnostic.

Instead of trying to make a rich set of highlightable classes look good in ahandful of languages we have a limited set of classes that work for alllanguages.

Hence, there are two important implications:

  • Highlight.js styles tend to be minimalistic.
  • It’s not possible to exactly emulate themes from other highlighting engines.

Defining a theme

A theme is a single CSS defining styles for class names listed in theclass reference. The general guideline is tostyle all available classes, however an author may deliberately choose toexclude some (for example, .attr is usually left unstyled).

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

  1. .hljs-string,
  2. .hljs-section,
  3. .hljs-selector-class,
  4. .hljs-template-variable,
  5. .hljs-deletion {
  6.   color: #800;
  7. }

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

Typography and layout 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 ofcharacters 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 inpractice.

There’s also a common set of rules that has to be defined for the rootcontainer verbatim:

  1. .hljs {
  2.   display: block;
  3.   overflow-x: auto;
  4.   padding: 0.5em;
  5. }

.subst

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

  1. .hljs,
  2. .hljs-subst {
  3.   color: black;
  4. }

Contributing

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

  1. /*
  2.  
  3. Fancy style (c) John Smith <email@domain.com>
  4.  
  5. */

If you’re a new contributor add yourself to the authors list in AUTHORS.*.txt(use either English and/or Russian version). Also update CHANGES.md with yourcontribution.

Send your contribution as a pull request on GitHub.