1 | # Highlight.js
|
2 |
|
3 | [![latest version](https://badgen.net/npm/v/highlight.js?label=latest)](https://www.npmjs.com/package/highlight.js)
|
4 | [![license](https://badgen.net/github/license/highlightjs/highlight.js?color=cyan)](https://github.com/highlightjs/highlight.js/blob/main/LICENSE)
|
5 | [![install size](https://badgen.net/packagephobia/install/highlight.js?label=npm+install)](https://packagephobia.now.sh/result?p=highlight.js)
|
6 | ![minified](https://img.shields.io/github/size/highlightjs/cdn-release/build/highlight.min.js?label=minified)
|
7 | [![NPM downloads weekly](https://badgen.net/npm/dw/highlight.js?label=npm+downloads&color=purple)](https://www.npmjs.com/package/highlight.js)
|
8 | [![jsDelivr CDN downloads](https://badgen.net/jsdelivr/hits/gh/highlightjs/cdn-release?label=jsDelivr+CDN&color=purple)](https://www.jsdelivr.com/package/gh/highlightjs/cdn-release)
|
9 |
|
10 |
|
11 | ![build and CI status](https://badgen.net/github/checks/highlightjs/highlight.js/main?label=build)
|
12 | [![code quality](https://badgen.net/lgtm/grade/g/highlightjs/highlight.js/js?label=code+quality)](https://lgtm.com/projects/g/highlightjs/highlight.js/?mode=list)
|
13 | [![vulnerabilities](https://badgen.net/snyk/highlightjs/highlight.js)](https://snyk.io/test/github/highlightjs/highlight.js?targetFile=package.json)
|
14 | ![dev deps](https://badgen.net/david/dev/highlightjs/highlight.js?label=dev+deps)
|
15 |
|
16 |
|
17 | [![discord](https://badgen.net/badge/icon/discord?icon=discord&label&color=pink)](https://discord.gg/M24EbU7ja9)
|
18 | [![open issues](https://badgen.net/github/open-issues/highlightjs/highlight.js?label=issues)](https://github.com/highlightjs/highlight.js/issues)
|
19 | [![help welcome issues](https://badgen.net/github/label-issues/highlightjs/highlight.js/help%20welcome/open)](https://github.com/highlightjs/highlight.js/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+welcome%22)
|
20 | [![good first issue](https://badgen.net/github/label-issues/highlightjs/highlight.js/good%20first%20issue/open)](https://github.com/highlightjs/highlight.js/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
|
21 |
|
22 |
|
23 |
|
24 |
|
25 |
|
26 |
|
27 |
|
28 |
|
29 | Highlight.js is a syntax highlighter written in JavaScript. It works in
|
30 | the browser as well as on the server. It can work with pretty much any
|
31 | markup, doesn’t depend on any other frameworks, and has automatic language
|
32 | detection.
|
33 |
|
34 | **Contents**
|
35 |
|
36 | - [Basic Usage](#basic-usage)
|
37 | - [In the Browser](#in-the-browser)
|
38 | - [Plaintext Code Blocks](#plaintext-code-blocks)
|
39 | - [Ignoring a Code Block](#ignoring-a-code-block)
|
40 | - [Node.js on the Server](#nodejs-on-the-server)
|
41 | - [Supported Languages](#supported-languages)
|
42 | - [Custom Usage](#custom-usage)
|
43 | - [Using custom HTML](#using-custom-html)
|
44 | - [Using with Vue.js](#using-with-vuejs)
|
45 | - [Using Web Workers](#using-web-workers)
|
46 | - [Importing the Library](#importing-the-library)
|
47 | - [Node.js / `require`](#nodejs--require)
|
48 | - [ES6 Modules / `import`](#es6-modules--import)
|
49 | - [Getting the Library](#getting-the-library)
|
50 | - [Fetch via CDN](#fetch-via-cdn)
|
51 | - [cdnjs (link)](#cdnjs-link)
|
52 | - [jsdelivr (link)](#jsdelivr-link)
|
53 | - [unpkg (link)](#unpkg-link)
|
54 | - [Download prebuilt CDN assets](#download-prebuilt-cdn-assets)
|
55 | - [Download from our website](#download-from-our-website)
|
56 | - [Install via NPM package](#install-via-npm-package)
|
57 | - [Build from Source](#build-from-source)
|
58 | - [Requirements](#requirements)
|
59 | - [License](#license)
|
60 | - [Links](#links)
|
61 |
|
62 | ---
|
63 |
|
64 | #### Upgrading to Version 11
|
65 |
|
66 | As always, major releases do contain breaking changes which may require action from users. Please read [VERSION_11_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_11_UPGRADE.md) for a detailed summary of breaking changes and any actions you may need to take.
|
67 |
|
68 |
|
69 | #### Support for older versions <!-- omit in toc -->
|
70 |
|
71 | Please see [SECURITY.md](https://github.com/highlightjs/highlight.js/blob/main/SECURITY.md) for long-term support information.
|
72 |
|
73 | ---
|
74 |
|
75 | ## Basic Usage
|
76 | ### In the Browser
|
77 |
|
78 | The bare minimum for using highlight.js on a web page is linking to the
|
79 | library along with one of the themes and calling [`highlightAll`][1]:
|
80 |
|
81 | ```html
|
82 | <link rel="stylesheet" href="/path/to/styles/default.min.css">
|
83 | <script src="/path/to/highlight.min.js"></script>
|
84 | <script>hljs.highlightAll();</script>
|
85 | ```
|
86 |
|
87 | This will find and highlight code inside of `<pre><code>` tags; it tries
|
88 | to detect the language automatically. If automatic detection doesn’t
|
89 | work for you, or you simply prefer to be explicit, you can specify the language manually in the using the `class` attribute:
|
90 |
|
91 |
|
92 | ```html
|
93 | <pre><code class="language-html">...</code></pre>
|
94 | ```
|
95 |
|
96 | #### Plaintext Code Blocks
|
97 |
|
98 | To apply the Highlight.js styling to plaintext without actually highlighting it, use the `plaintext` language:
|
99 |
|
100 | ```html
|
101 | <pre><code class="language-plaintext">...</code></pre>
|
102 | ```
|
103 |
|
104 | #### Ignoring a Code Block
|
105 |
|
106 | To skip highlighting of a code block completely, use the `nohighlight` class:
|
107 |
|
108 | ```html
|
109 | <pre><code class="nohighlight">...</code></pre>
|
110 | ```
|
111 |
|
112 | ### Node.js on the Server
|
113 |
|
114 | The bare minimum to auto-detect the language and highlight some code.
|
115 |
|
116 | ```js
|
117 | // load the library and ALL languages
|
118 | hljs = require('highlight.js');
|
119 | html = hljs.highlightAuto('<h1>Hello World!</h1>').value
|
120 | ```
|
121 |
|
122 | To load only a "common" subset of popular languages:
|
123 |
|
124 | ```js
|
125 | hljs = require('highlight.js/lib/common');
|
126 | ```
|
127 |
|
128 | To highlight code with a specific language, use `highlight`:
|
129 |
|
130 | ```js
|
131 | html = hljs.highlight('<h1>Hello World!</h1>', {language: 'xml'}).value
|
132 | ```
|
133 |
|
134 | See [Importing the Library](#importing-the-library) for more examples of `require` vs `import` usage, etc. For more information about the result object returned by `highlight` or `highlightAuto` refer to the [api docs](https://highlightjs.readthedocs.io/en/latest/api.html).
|
135 |
|
136 |
|
137 |
|
138 | ## Supported Languages
|
139 |
|
140 | Highlight.js supports over 180 languages in the core library. There are also 3rd party
|
141 | language definitions available to support even more languages. You can find the full list of supported languages in [SUPPORTED_LANGUAGES.md][9].
|
142 |
|
143 | ## Custom Usage
|
144 |
|
145 | If you need a bit more control over the initialization of
|
146 | Highlight.js, you can use the [`highlightElement`][3] and [`configure`][4]
|
147 | functions. This allows you to better control *what* to highlight and *when*.
|
148 |
|
149 | For example, here’s the rough equivalent of calling [`highlightAll`][1] but doing the work manually instead:
|
150 |
|
151 | ```js
|
152 | document.addEventListener('DOMContentLoaded', (event) => {
|
153 | document.querySelectorAll('pre code').forEach((el) => {
|
154 | hljs.highlightElement(el);
|
155 | });
|
156 | });
|
157 | ```
|
158 |
|
159 | Please refer to the documentation for [`configure`][4] options.
|
160 |
|
161 |
|
162 | ### Using custom HTML
|
163 |
|
164 | We strongly recommend `<pre><code>` wrapping for code blocks. It's quite
|
165 | semantic and "just works" out of the box with zero fiddling. It is possible to
|
166 | use other HTML elements (or combos), but you may need to pay special attention to
|
167 | preserving linebreaks.
|
168 |
|
169 | Let's say your markup for code blocks uses divs:
|
170 |
|
171 | ```html
|
172 | <div class='code'>...</div>
|
173 | ```
|
174 |
|
175 | To highlight such blocks manually:
|
176 |
|
177 | ```js
|
178 | // first, find all the div.code blocks
|
179 | document.querySelectorAll('div.code').forEach(el => {
|
180 | // then highlight each
|
181 | hljs.highlightElement(el);
|
182 | });
|
183 | ```
|
184 |
|
185 | Without using a tag that preserves linebreaks (like `pre`) you'll need some
|
186 | additional CSS to help preserve them. You could also [pre and post-process line
|
187 | breaks with a plug-in][brPlugin], but *we recommend using CSS*.
|
188 |
|
189 | [brPlugin]: https://github.com/highlightjs/highlight.js/issues/2559
|
190 |
|
191 | To preserve linebreaks inside a `div` using CSS:
|
192 |
|
193 | ```css
|
194 | div.code {
|
195 | white-space: pre;
|
196 | }
|
197 | ```
|
198 |
|
199 |
|
200 | ### Using with Vue.js
|
201 |
|
202 | See [highlightjs/vue-plugin](https://github.com/highlightjs/vue-plugin) for a simple Vue plugin that works great with Highlight.js.
|
203 |
|
204 | An example of `vue-plugin` in action:
|
205 |
|
206 | ```html
|
207 | <div id="app">
|
208 | <!-- bind to a data property named `code` -->
|
209 | <highlightjs autodetect :code="code" />
|
210 | <!-- or literal code works as well -->
|
211 | <highlightjs language='javascript' code="var x = 5;" />
|
212 | </div>
|
213 | ```
|
214 |
|
215 | ### Using Web Workers
|
216 |
|
217 | You can run highlighting inside a web worker to avoid freezing the browser
|
218 | window while dealing with very big chunks of code.
|
219 |
|
220 | In your main script:
|
221 |
|
222 | ```js
|
223 | addEventListener('load', () => {
|
224 | const code = document.querySelector('#code');
|
225 | const worker = new Worker('worker.js');
|
226 | worker.onmessage = (event) => { code.innerHTML = event.data; }
|
227 | worker.postMessage(code.textContent);
|
228 | });
|
229 | ```
|
230 |
|
231 | In worker.js:
|
232 |
|
233 | ```js
|
234 | onmessage = (event) => {
|
235 | importScripts('<path>/highlight.min.js');
|
236 | const result = self.hljs.highlightAuto(event.data);
|
237 | postMessage(result.value);
|
238 | };
|
239 | ```
|
240 |
|
241 | ## Importing the Library
|
242 |
|
243 | First, you'll likely be installing the library via `npm` or `yarn` -- see [Getting the Library](#getting-the-library).
|
244 |
|
245 |
|
246 | ### Node.js / `require`
|
247 |
|
248 | Requiring the top-level library will load all languages:
|
249 |
|
250 | ```js
|
251 | // require the highlight.js library, including all languages
|
252 | const hljs = require('./highlight.js');
|
253 | const highlightedCode = hljs.highlightAuto('<span>Hello World!</span>').value
|
254 | ```
|
255 |
|
256 | For a smaller footprint, load our common subset of languages (the same set used for our default web build).
|
257 |
|
258 | ```js
|
259 | const hljs = require('highlight.js/lib/common');
|
260 | ```
|
261 |
|
262 | For the smallest footprint, load only the languages you need:
|
263 |
|
264 | ```js
|
265 | const hljs = require('highlight.js/lib/core');
|
266 | hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));
|
267 |
|
268 | const highlightedCode = hljs.highlight('<span>Hello World!</span>', {language: 'xml'}).value
|
269 | ```
|
270 |
|
271 |
|
272 | ### ES6 Modules / `import`
|
273 |
|
274 | *Note: You can also import directly from fully static URLs, such as our very own pre-built
|
275 | ES6 Module CDN resources. See [Fetch via CDN](#fetch-via-cdn) for specific examples.*
|
276 |
|
277 | The default import will register all languages:
|
278 |
|
279 | ```js
|
280 | import hljs from 'highlight.js';
|
281 | ```
|
282 |
|
283 | It is more efficient to import only the library and register the languages you need:
|
284 |
|
285 | ```js
|
286 | import hljs from 'highlight.js/lib/core';
|
287 | import javascript from 'highlight.js/lib/languages/javascript';
|
288 | hljs.registerLanguage('javascript', javascript);
|
289 | ```
|
290 |
|
291 | If your build tool processes CSS imports, you can also import the theme directly as a module:
|
292 |
|
293 | ```js
|
294 | import hljs from 'highlight.js';
|
295 | import 'highlight.js/styles/github.css';
|
296 | ```
|
297 |
|
298 |
|
299 | ## Getting the Library
|
300 |
|
301 | You can get highlight.js as a hosted, or custom-build, browser script or
|
302 | as a server module. Right out of the box the browser script supports
|
303 | both AMD and CommonJS, so if you wish you can use RequireJS or
|
304 | Browserify without having to build from source. The server module also
|
305 | works perfectly fine with Browserify, but there is the option to use a
|
306 | build specific to browsers rather than something meant for a server.
|
307 |
|
308 |
|
309 | **Do not link to GitHub directly.** The library is not supposed to work straight
|
310 | from the source, it requires building. If none of the pre-packaged options
|
311 | work for you refer to the [building documentation][6].
|
312 |
|
313 | **On Almond.** You need to use the optimizer to give the module a name. For
|
314 | example:
|
315 |
|
316 | ```bash
|
317 | r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
|
318 | ```
|
319 |
|
320 | ### Fetch via CDN
|
321 |
|
322 | A prebuilt version of Highlight.js bundled with many common languages is hosted by several popular CDNs.
|
323 | When using Highlight.js via CDN you can use Subresource Integrity for additional security. For details
|
324 | see [DIGESTS.md](https://github.com/highlightjs/cdn-release/blob/main/DIGESTS.md).
|
325 |
|
326 | #### cdnjs ([link](https://cdnjs.com/libraries/highlight.js))
|
327 |
|
328 | ##### Common JS <!-- omit in toc -->
|
329 |
|
330 | ```html
|
331 | <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/default.min.css">
|
332 | <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script>
|
333 | <!-- and it's easy to individually load additional languages -->
|
334 | <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/languages/go.min.js"></script>
|
335 | ```
|
336 |
|
337 | ##### ES6 Modules <!-- omit in toc -->
|
338 |
|
339 | ````html
|
340 | <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/dark.min.css">
|
341 | <script type="module">
|
342 | import hljs from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/es/highlight.min.js';
|
343 | // and it's easy to individually load additional languages
|
344 | import go from 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/es/languages/go.min.js';
|
345 | hljs.registerLanguage('go', go);
|
346 | </script>
|
347 |
|
348 | ````
|
349 |
|
350 |
|
351 | #### jsdelivr ([link](https://www.jsdelivr.com/package/gh/highlightjs/cdn-release))
|
352 |
|
353 | ##### Common JS <!-- omit in toc -->
|
354 |
|
355 | ```html
|
356 | <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.1/build/styles/default.min.css">
|
357 | <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.1/build/highlight.min.js"></script>
|
358 | <!-- and it's easy to individually load additional languages -->
|
359 | <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.1/build/languages/go.min.js"></script>
|
360 | ```
|
361 |
|
362 | ##### ES6 Modules <!-- omit in toc -->
|
363 |
|
364 | ```html
|
365 | <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.1/build/styles/default.min.css">
|
366 | <script type="module">
|
367 | import hljs from 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.1/build/es/highlight.min.js';
|
368 | // and it's easy to individually load additional languages
|
369 | import go from 'https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.5.1/build/es/languages/go.min.js';
|
370 | hljs.registerLanguage('go', go);
|
371 | </script>
|
372 | ```
|
373 |
|
374 | #### unpkg ([link](https://unpkg.com/browse/@highlightjs/cdn-assets/))
|
375 |
|
376 | ##### Common JS <!-- omit in toc -->
|
377 |
|
378 | ```html
|
379 | <link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.5.1/styles/default.min.css">
|
380 | <script src="https://unpkg.com/@highlightjs/cdn-assets@11.5.1/highlight.min.js"></script>
|
381 | <!-- and it's easy to individually load additional languages -->
|
382 | <script src="https://unpkg.com/@highlightjs/cdn-assets@11.5.1/languages/go.min.js"></script>
|
383 | ```
|
384 |
|
385 | ##### ES6 Modules <!-- omit in toc -->
|
386 |
|
387 | ```html
|
388 | <link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.5.1/styles/default.min.css">
|
389 | <script type="module">
|
390 | import hljs from 'https://unpkg.com/@highlightjs/cdn-assets@11.5.1/es/highlight.min.js';
|
391 | // and it's easy to individually load & register additional languages
|
392 | import go from 'https://unpkg.com/@highlightjs/cdn-assets@11.5.1/es/languages/go.min.js';
|
393 | hljs.registerLanguage('go', go);
|
394 | </script>
|
395 | ```
|
396 |
|
397 |
|
398 | **Note:** *The CDN-hosted `highlight.min.js` package doesn't bundle every language.* It would be
|
399 | very large. You can find our list of "common" languages that we bundle by default on our [download page][5].
|
400 |
|
401 | #### Download prebuilt CDN assets
|
402 |
|
403 | You can also download and self-host the same assets we serve up via our own CDNs. We publish those builds to the [cdn-release](https://github.com/highlightjs/cdn-release) GitHub repository. You can easily pull individual files off the CDN endpoints with `curl`, etc; if say you only needed `highlight.min.js` and a single CSS file.
|
404 |
|
405 | There is also an npm package [@highlightjs/cdn-assets](https://www.npmjs.com/package/@highlightjs/cdn-assets) if pulling the assets in via `npm` or `yarn` would be easier for your build process.
|
406 |
|
407 | ### Download from our website
|
408 |
|
409 | The [download page][5] can quickly generate a custom single-file minified bundle including only the languages you desire.
|
410 |
|
411 | **Note:** [Building from source](#build-from-source) can produce slightly smaller builds than the website download.
|
412 |
|
413 |
|
414 | ### Install via NPM package
|
415 |
|
416 | Our NPM package including all supported languages can be installed with NPM or Yarn:
|
417 |
|
418 | ```bash
|
419 | npm install highlight.js
|
420 | # or
|
421 | yarn add highlight.js
|
422 | ```
|
423 |
|
424 | Alternatively, you can build the NPM package from source.
|
425 |
|
426 |
|
427 | ### Build from Source
|
428 |
|
429 | The [current source code][10] is always available on GitHub.
|
430 |
|
431 | ```bash
|
432 | node tools/build.js -t node
|
433 | node tools/build.js -t browser :common
|
434 | node tools/build.js -t cdn :common
|
435 | ```
|
436 |
|
437 | See our [building documentation][6] for more information.
|
438 |
|
439 |
|
440 | ## Requirements
|
441 |
|
442 | 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:
|
443 |
|
444 | - Node.js >= 12.x
|
445 | - npm >= 6.x
|
446 |
|
447 | ## License
|
448 |
|
449 | Highlight.js is released under the BSD License. See our [LICENSE][7] file
|
450 | for details.
|
451 |
|
452 |
|
453 | ## Links
|
454 |
|
455 | The official website for the library is <https://highlightjs.org/>.
|
456 |
|
457 | Further in-depth documentation for the API and other topics is at
|
458 | <http://highlightjs.readthedocs.io/>.
|
459 |
|
460 | A list of the Core Team and contributors can be found in the [CONTRIBUTORS.md][8] file.
|
461 |
|
462 | [1]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightall
|
463 | [2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
|
464 | [3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightelement
|
465 | [4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure
|
466 | [5]: https://highlightjs.org/download/
|
467 | [6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
|
468 | [7]: https://github.com/highlightjs/highlight.js/blob/main/LICENSE
|
469 | [8]: https://github.com/highlightjs/highlight.js/blob/main/CONTRIBUTORS.md
|
470 | [9]: https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md
|
471 | [10]: https://github.com/highlightjs/
|