[Theme Maint] Write up on changes for theme maintainers

I’m going to use this issue to track items that theme maintainers may want to keep in mind when updating their themes for v11 and beyond. Each of the below items should be expanded into a brief explanation.

Overall Intention

Please skim #2500 and #2521 if you have time. The idea is higher fidelity highlighting and more nuanced highlighted (when possible). Often there are things we could easily highlight but we have chosen not to in the past (operators, punctuation, properties, function dispatch, etc)… we’d like to start highlighting those things going forward when it makes sense to do so.

We’re also open to feedback on these things as there is still wiggle room in the v11 window on how some of these things will land. (particularly exactly how the new tiered scopes shake out)

Newer scopes

We’ve recently added:

• property
• punctuation
• operator
• variable.language
• title.function
• title.class
• title.class.inherited
• char.escape

// > is an operator
// ( and ) are punctuation
// player, score, and enemy are properties
if (state.player.score > state.enemy.score) {
  // ...
}

You can see GitHub itself highlighting the operator and properties.

Please see our CSS Class reference. This is part of our higher fidelity goals. A theme that highlights these items should feel more “complete”. If your theme purposely choses to opt-out you should provide an empty rule so our theme checker knows you purposely don’t want to highlight these. Example:

.hljs-property {} /* do not highlight */

Do not worry about any wasted space - these things will be minified/stripped at build time.

New tiered scopes

To add more nuance (#2521) we have added tiered scopes. For things that are pure renamings the core team can handle those… such as say if we decided to rename meta-keyword to meta.keyword. But sometimes the changes are a bit broader. This allows for more nuance in parsing (and possibly also more nuance in coloring).

Instead of just a string in the future we might easily have:

• string.unquoted
• string.quoted
• string.quoted.triple

If you’ve worked with TextMate grammars this should be immediately familiar.

A theme can provide coloring for just string at the top-level or it could get as nuanced as it wants. Note: It will of course take time for grammars to support this additional nuance and there will be some discovery on how much nuance is good to have. This is why I say themes may require some degree of “maintenance” as time goes on.

• Larger discussion also going on with the Prism team: https://github.com/PrismJS/prism/issues/2849

Deprecation of class and function for indicating definitions

According to our docs these are support to be used fo class and function definitions… but they have been used (and abused) rather inconsistently so they are being deprecated in core.

• Sometimes they would cover the definition only (the idea)
• Sometimes they wrap a whole function (we generally want to avoid this, it results in complex grammars)
• Sometimes they are used to signify function name

This can result in some themes & grammar combos looking funny and large swaths of unintended highlighting. Going forward it’s recommended that class and function simply not be highlighted at the top-level. And the recommendation for grammars is that they not emit these top-level scopes at all.

.hljs-class {} /* do not highlight */
.hljs-function {} /* do not highlight */

This should be fine for v10 support as well. Grammars using function to indicate a function name are considered broken and should instead by updated.

Deprecation of class > title and function > title for titles

We’re trying to simplify grammars where possible to be flatter… where-as before you may have had a nested scope… now you would instead have a flatter tree but with parts of the match have tiered scopes. Often then can significantly reduce the complexity of a grammar, but with exactly or almost the same fidelity of highlighting.

Before (note the “class” class wrapping the whole start of the class):

<span class="hljs-class">
    <span class="hljs-keyword">class</span>
    <span class="hljs-title">Person</span>
</span> {
  // ...
}

Which you might have targeted with the selector .hljs-class .hljs-title.

In the future (no wrapper):

<span class="hljs-keyword">class</span>
<span class="hljs-title class_">Person</span> {

Which you would target with a .hljs-title.class_ selector.

Supporting v10 and v11 simultaneously.

Generally that simply means supporting old and new scope selectors. This is desirable for the immediate future, perhaps until v12.

/* Title of a function */
.hljs-function .hljs-title { } /* Highlight.js v10 */
.hljs-title.function_ { } /* Highlight.js v11 */
.hljs-title.function_.call__ { } /* Highlight.js v11 */

Note the single underscore _ in function_ and the double in call__. Please see our CSS Class reference for documentation on how tiered scopes work.

Adding metadata.

Theme meta-data should lead the CSS and look something like:

/*!
   Theme: Name of theme
   Description: Optional description of the theme
   Author: Name <[e-mail]>
   Maintainer: @githubhandle
   Website: [canonical URL of theme]
   License: [if anything other than BSD-3-clause]
   Updated: [when the theme was last reviewed/updated]

  Other general unstructured comments may follow here.
*/

At a minimum the following should be provided:

• Theme:
• Author: if known
• Maintainer:
• Website: (if there is a canonical source of the theme elsewhere)
• Updated:

Sample:

/*!
   Theme: An Old Hope – Star Wars Syntax
   Author: (c) Gustavo Costa <[e-mail]>
   Maintainer: @gusbemacbe
   Updated: 2021-03-22

   Original theme - Ocean Dark Theme – by https://github.com/gavsiu
   Based on Jesse Leite's Atom syntax theme 'An Old Hope'
   https://github.com/JesseLeite/an-old-hope-syntax-atom
 */

The new ./tools/checkTheme utility.

Our new theme checked can tell you what your theme might be missing. You simply pass the filename of a theme to it. This tool is brand new and likely to improve with time.

Example:

# ./tools/checkTheme.js src/styles/dark.css
Missing selector .hljs-tag
<snip>
Theme does not fully support Templates/HTML/XML, etc..

Missing selector .hljs-number
<snip>
Theme does not fully support program code.

[joshgoebel]

@Hirse See 9f52d99e

[joshgoebel]

Our default theme is pretty boring and doesn’t really change much. I did just add operator and punctuation to it and some purposeful “opt-outs” to make the new theme checker happy.