Upgrading to Highlight.js v11.0

Overview of Breaking Changes

Welcome to version 11.0. This a major release and therefore contains breaking changes. Below is a complete list of those such changes.

Built-in set of "Common" Languages

The default highlight.min.js build removes a few less popular grammars:

If you need any of these, you can always create a custom build.

Ref: https://github.com/highlightjs/highlight.js/issues/2848

Language Files

This would matter if you are requiring any of these files directly (via Node.js or CDN).

Language Aliases

This would matter if you are using these aliases.

You can of course re-register any of these aliases easily if necessary. For example to restore the PHP aliases:

hljs.registerAliases(["php3","php4","php5","php6","php7","php8"],{ languageName: "php" })

Styles and CSS

Grammar Scopes

Behavioral changes

API changes

The new call signature is highlight(code, {options}). (see docs)

Code using the old API:

// highlight(language, code, ignoreIllegals, continuation)
highlight("javascript", "var a = 5;", true)

...would be upgraded to the newer API as follows:

// highlight(code, {language, ignoreIllegals})
highlight("var a = 5;", {language: "javascript", ignoreIllegals: true})

The new API purposely does not support continuation as this is only intended for internal library usage.

Use highlightAll() instead. (see docs) The old functions are now simply aliases of highlightAll(). The new function may be called before or after the DOM is loaded and should do the correct thing in all cases, replacing the need for the previous individual functions.

Note: highlightAll() does not guard against calling itself repeatedly as the previous functions did. Your code should be careful to avoid doing this.

Use highlightElement() instead. (see docs) This is merely a naming change.

Note: The object literal passed to the before:highlightElement callback now passes the element in the el key vs the block key.

Changes to Result Data

This behavior was inconsistent before. Sometimes [name] class would be added, sometimes the alias name would be added, something no class would be added. now language-[name] is always added. This also affects sublanguage span tags which now also include the language- prefix.

Feature Removal

An example:

<pre><code class="lang-js">
var a = 4;
<span class="yellow">var a = 4;</span>
</code></pre>

Unescaped HTML like this will now be ignored (stripped before highlighting) and a warning will be logged to the console. All HTML to be highlighted should be properly escaped to avoid potential HTML/JS injection attacks.

This function was deprecated in v10.2. It is not our goal to provide random string utilities. You may need to provide your own replacement Ref: #2534

This rule was too broad for bring inclusion in core and has been removed.

Use the new keywords.$pattern instead.

Before:

{
  keywords: "do.it start.now begin.later end.immediately"
  lexemes: /[a-z.]+/
}

After:

{
  keywords: {
    $pattern: /[a-z.]+/
    keyword: "do.it start.now begin.later end.immediately",
  }
}

This may required converting your keywords key into an object if it's not already (as shown above).

Use the new END_SAME_AS_BEGIN mode rule/function instead.

This configuration option was deprecated in v10.1. Use a plugin or preferably simply CSS white-space: pre. Ref: #2559

This configuration option was deprecated in v10.5. Use a plugin or pre-render content instead with desired spacing. Ref: #2874

Small Things

Upgrading from Version 9.x

If you're upgrading all the way from version 9 it may still be helpful to review all the breaking changes in version 10 as well: