Repository files navigation

Highlight.js is a syntax highlighter written in JavaScript. It works inthe browser as well as on the server. It can work with pretty much anymarkup, doesn’t depend on any other frameworks, and has automatic languagedetection.

Contents

• Basic Usage
  • In the Browser
    • Plaintext Code Blocks
    • Ignoring a Code Block
  • Node.js on the Server
• Supported Languages
• Custom Usage
  • Using custom HTML
  • Using with Vue.js
  • Using Web Workers
• Importing the Library
  • Node.js CommonJS Modules /require
  • Node.js ES6 Modules /import
  • Browser ES6 Modules
• Getting the Library
  • Fetch via CDN
    • cdnjs (link)
    • jsdelivr (link)
    • unpkg (link)
  • Download prebuilt CDN assets
  • Download from our website
  • Install via NPM package
  • Build from Source
• Requirements
• License
• Links

As always, major releases do contain breaking changes which may require action from users. Please readVERSION_11_UPGRADE.md for a detailed summary of breaking changes and any actions you may need to take.

Please seeSECURITY.md for long-term support information.

The bare minimum for using highlight.js on a web page is linking to thelibrary along with one of the themes and callinghighlightAll:

<linkrel="stylesheet"href="/path/to/styles/default.min.css"><scriptsrc="/path/to/highlight.min.js"></script><script>hljs.highlightAll();</script>

This will find and highlight code inside of<pre><code> tags; it triesto detect the language automatically. If automatic detection doesn’twork for you, or you simply prefer to be explicit, you can specify the language manually by using theclass attribute:

<pre><codeclass="language-html">...</code></pre>

To apply the Highlight.js styling to plaintext without actually highlighting it, use theplaintext language:

<pre><codeclass="language-plaintext">...</code></pre>

To skip highlighting of a code block completely, use thenohighlight class:

<pre><codeclass="nohighlight">...</code></pre>

The bare minimum to auto-detect the language and highlight some code.

// load the library and ALL languageshljs=require('highlight.js');html=hljs.highlightAuto('<h1>Hello World!</h1>').value

To load only a "common" subset of popular languages:

hljs=require('highlight.js/lib/common');

To highlight code with a specific language, usehighlight:

html=hljs.highlight('<h1>Hello World!</h1>',{language:'xml'}).value

SeeImporting the Library for more examples ofrequire vsimport usage, etc. For more information about the result object returned byhighlight orhighlightAuto refer to theapi docs.

Highlight.js supports over 180 languages in the core library. There are also 3rd partylanguage definitions available to support even more languages. You can find the full list of supported languages inSUPPORTED_LANGUAGES.md.

If you need a bit more control over the initialization ofHighlight.js, you can use thehighlightElement andconfigurefunctions. This allows you to better controlwhat to highlight andwhen.

For example, here’s the rough equivalent of callinghighlightAll but doing the work manually instead:

document.addEventListener('DOMContentLoaded',(event)=>{document.querySelectorAll('pre code').forEach((el)=>{hljs.highlightElement(el);});});

Please refer to the documentation forconfigure options.

We strongly recommend<pre><code> wrapping for code blocks. It's quitesemantic and "just works" out of the box with zero fiddling. It is possible touse other HTML elements (or combos), but you may need to pay special attention topreserving linebreaks.

Let's say your markup for code blocks uses divs:

<divclass='code'>...</div>

To highlight such blocks manually:

// first, find all the div.code blocksdocument.querySelectorAll('div.code').forEach(el=>{// then highlight eachhljs.highlightElement(el);});

Without using a tag that preserves linebreaks (likepre) you'll need someadditional CSS to help preserve them. You could alsopre and post-process linebreaks with a plug-in, butwe recommend using CSS.

To preserve linebreaks inside adiv using CSS:

div.code {white-space: pre;}

Seehighlightjs/vue-plugin for a simple Vue plugin that works great with Highlight.js.

An example ofvue-plugin in action:

<divid="app"><!-- bind to a data property named `code` --><highlightjsautodetect:code="code"/><!-- or literal code works as well --><highlightjslanguage='javascript'code="var x = 5;"/></div>

You can run highlighting inside a web worker to avoid freezing the browserwindow while dealing with very big chunks of code.

In your main script:

addEventListener('load',()=>{constcode=document.querySelector('#code');constworker=newWorker('worker.js');worker.onmessage=(event)=>{code.innerHTML=event.data;}worker.postMessage(code.textContent);});

In worker.js:

onmessage=(event)=>{importScripts('<path>/highlight.min.js');constresult=self.hljs.highlightAuto(event.data);postMessage(result.value);};

First, you'll likely be installing the library vianpm oryarn -- seeGetting the Library.

Requiring the top-level library will load all languages:

// require the highlight.js library, including all languagesconsthljs=require('./highlight.js');consthighlightedCode=hljs.highlightAuto('<span>Hello World!</span>').value

For a smaller footprint, load our common subset of languages (the same set used for our default web build).

consthljs=require('highlight.js/lib/common');

For the smallest footprint, load only the languages you need:

consthljs=require('highlight.js/lib/core');hljs.registerLanguage('xml',require('highlight.js/lib/languages/xml'));consthighlightedCode=hljs.highlight('<span>Hello World!</span>',{language:'xml'}).value

The default import will register all languages:

importhljsfrom'highlight.js';

It is more efficient to import only the library and register the languages you need:

importhljsfrom'highlight.js/lib/core';importjavascriptfrom'highlight.js/lib/languages/javascript';hljs.registerLanguage('javascript',javascript);

If your build tool processes CSS imports, you can also import the theme directly as a module:

importhljsfrom'highlight.js';import'highlight.js/styles/github.css';

Note: For now you'll want to install@highlightjs/cdn-assets package instead ofhighlight.js.SeeDownload prebuilt CDN assets

To import the library and register only those languages that you need:

importhljsfrom'./assets/js/@highlightjs/cdn-assets/es/core.js';importjavascriptfrom'./assets/js/@highlightjs/cdn-assets/es/languages/javascript.min.js';hljs.registerLanguage('javascript',javascript);

To import the library and register all languages:

importhljsfrom'./assets/js/@highlightjs/cdn-assets/es/highlight.js';

Note: The path to these files will vary depending on where you have installed/copied themwithin your project or site. The above path is only an example.

You can also useimportmap to import in similar way as Node:

<scripttype="importmap">{"imports":{"@highlightjs":"./assets/js/@highlightjs/cdn-assets/es/"}}</script>

Use the above code in your HTML. After that, your JavaScript can import using the named key fromyourimportmap, for example@highlightjs in this case:

importhljsfrom'@highlightjs/core.js';importjavascriptfrom'@highlightjs/languages/javascript.min.js';hljs.registerLanguage('javascript',javascript);

Note: You can also import directly from fully static URLs, such as our very own pre-built ES6 Module CDN resources. SeeFetch via CDN for specific examples.

You can get highlight.js as a hosted, or custom-build, browser script oras a server module. Right out of the box the browser script supportsboth AMD and CommonJS, so if you wish you can use RequireJS orBrowserify without having to build from source. The server module alsoworks perfectly fine with Browserify, but there is the option to use abuild specific to browsers rather than something meant for a server.

Do not link to GitHub directly. The library is not supposed to work straightfrom the source, it requires building. If none of the pre-packaged optionswork for you refer to thebuilding documentation.

On Almond. You need to use the optimizer to give the module a name. Forexample:

r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js

A prebuilt version of Highlight.js bundled with many common languages is hosted by several popular CDNs.When using Highlight.js via CDN you can use Subresource Integrity for additional security. For detailsseeDIGESTS.md.

<linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/default.min.css"><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script><!-- and it's easy to individually load additional languages --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/languages/go.min.js"></script>

<linkrel="stylesheet"href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/dark.min.css"><scripttype="module">importhljsfrom'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/es/highlight.min.js';//  and it's easy to individually load additional languagesimportgofrom'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/es/languages/go.min.js';hljs.registerLanguage('go',go);</script>

<linkrel="stylesheet"href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/default.min.css"><scriptsrc="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/highlight.min.js"></script><!-- and it's easy to individually load additional languages --><scriptsrc="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/languages/go.min.js"></script>

<linkrel="stylesheet"href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/styles/default.min.css"><scripttype="module">importhljsfrom'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/es/highlight.min.js';//  and it's easy to individually load additional languagesimportgofrom'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.11.1/build/es/languages/go.min.js';hljs.registerLanguage('go',go);</script>

<linkrel="stylesheet"href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/default.min.css"><scriptsrc="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/highlight.min.js"></script><!-- and it's easy to individually load additional languages --><scriptsrc="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/languages/go.min.js"></script>

<linkrel="stylesheet"href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/default.min.css"><scripttype="module">importhljsfrom'https://unpkg.com/@highlightjs/cdn-assets@11.11.1/es/highlight.min.js';//  and it's easy to individually load & register additional languagesimportgofrom'https://unpkg.com/@highlightjs/cdn-assets@11.11.1/es/languages/go.min.js';hljs.registerLanguage('go',go);</script>

Note:The CDN-hostedhighlight.min.js package doesn't bundle every language. It would bevery large. You can find our list of "common" languages that we bundle by default on ourdownload page.

You can also download and self-host the same assets we serve up via our own CDNs. We publish those builds to thecdn-release GitHub repository. You can easily pull individual files off the CDN endpoints withcurl, etc; if say you only neededhighlight.min.js and a single CSS file.

There is also an npm package@highlightjs/cdn-assets if pulling the assets in vianpm oryarn would be easier for your build process.

Thedownload page can quickly generate a custom single-file minified bundle including only the languages you desire.

Note:Building from source can produce slightly smaller builds than the website download.

Our NPM package including all supported languages can be installed with NPM or Yarn:

npm install highlight.js# oryarn add highlight.js

There is also another npm package@highlightjs/cdn-assets that contains prebuilt CDN assets includingES6 Modules that can be imported in browser:

npm install @highlightjs/cdn-assets# oryarn add @highlightjs/cdn-assets

Alternatively, you can build the NPM package from source.

Thecurrent source code is always available on GitHub.

node tools/build.js -t nodenode tools/build.js -t browser :commonnode tools/build.js -t cdn :common

See ourbuilding documentation for more information.

Highlight.js works on all modern browsers and currently supported Node.js versions. You'll need the following software to contribute to the core library:

• Node.js >= 12.x
• npm >= 6.x

Highlight.js is released under the BSD License. See ourLICENSE filefor details.

The official website for the library ishttps://highlightjs.org/.

Further in-depth documentation for the API and other topics is athttp://highlightjs.readthedocs.io/.

A list of the Core Team and contributors can be found in theCONTRIBUTORS.md file.