1 | # Highlight.js
|
2 |
|
3 | [![Build Status](https://travis-ci.org/highlightjs/highlight.js.svg?branch=master)](https://travis-ci.org/highlightjs/highlight.js) [![Greenkeeper badge](https://badges.greenkeeper.io/highlightjs/highlight.js.svg)](https://greenkeeper.io/) [![install size](https://packagephobia.now.sh/badge?p=highlight.js)](https://packagephobia.now.sh/result?p=highlight.js)
|
4 |
|
5 | Highlight.js is a syntax highlighter written in JavaScript. It works in
|
6 | the browser as well as on the server. It works with pretty much any
|
7 | markup, doesn’t depend on any framework, and has automatic language
|
8 | detection.
|
9 |
|
10 | #### Upgrading to Version 10
|
11 |
|
12 | Version 10 is one of the biggest releases in quite some time. If you're
|
13 | upgrading from version 9, there are some breaking changes and things you may
|
14 | want to double check first.
|
15 |
|
16 | Please read [VERSION_10_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/master/VERSION_10_UPGRADE.md) for high-level summary of breaking changes and any actions you may need to take. See [VERSION_10_BREAKING_CHANGES.md](https://github.com/highlightjs/highlight.js/blob/master/VERSION_10_BREAKING_CHANGES.md) for a more detailed list and [CHANGES.md](https://github.com/highlightjs/highlight.js/blob/master/CHANGES.md) to learn what else is new.
|
17 |
|
18 | ##### Support for older versions
|
19 |
|
20 | Please see [OLD_VERSIONS.md](https://github.com/highlightjs/highlight.js/blob/master/OLD_VERSIONS.md) for support information.
|
21 |
|
22 | ## Getting Started
|
23 |
|
24 | The bare minimum for using highlight.js on a web page is linking to the
|
25 | library along with one of the styles and calling [`initHighlightingOnLoad`][1]:
|
26 |
|
27 | ```html
|
28 | <link rel="stylesheet" href="/path/to/styles/default.css">
|
29 | <script src="/path/to/highlight.min.js"></script>
|
30 | <script>hljs.initHighlightingOnLoad();</script>
|
31 | ```
|
32 |
|
33 | This will find and highlight code inside of `<pre><code>` tags; it tries
|
34 | to detect the language automatically. If automatic detection doesn’t
|
35 | work for you, you can specify the language in the `class` attribute:
|
36 |
|
37 | ```html
|
38 | <pre><code class="html">...</code></pre>
|
39 | ```
|
40 |
|
41 | Classes may also be prefixed with either `language-` or `lang-`.
|
42 |
|
43 | ```html
|
44 | <pre><code class="language-html">...</code></pre>
|
45 | ```
|
46 |
|
47 | ### Plaintext and Disabling Highlighting
|
48 |
|
49 | To style arbitrary text like code, but without any highlighting, use the
|
50 | `plaintext` class:
|
51 |
|
52 | ```html
|
53 | <pre><code class="plaintext">...</code></pre>
|
54 | ```
|
55 |
|
56 | To disable highlighting of a tag completely, use the `nohighlight` class:
|
57 |
|
58 | ```html
|
59 | <pre><code class="nohighlight">...</code></pre>
|
60 | ```
|
61 |
|
62 | ### Supported Languages
|
63 |
|
64 | Highlight.js supports over 180 different languages in the core library. There are also 3rd party
|
65 | language plugins available for additional languages. You can find the full list of supported languages
|
66 | in [SUPPORTED_LANGUAGES.md][9].
|
67 |
|
68 | ## Custom Initialization
|
69 |
|
70 | When you need a bit more control over the initialization of
|
71 | highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
|
72 | functions. This allows you to control *what* to highlight and *when*.
|
73 |
|
74 | Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using
|
75 | vanilla JS:
|
76 |
|
77 | ```js
|
78 | document.addEventListener('DOMContentLoaded', (event) => {
|
79 | document.querySelectorAll('pre code').forEach((block) => {
|
80 | hljs.highlightBlock(block);
|
81 | });
|
82 | });
|
83 | ```
|
84 |
|
85 | You can use any tags instead of `<pre><code>` to mark up your code. If
|
86 | you don't use a container that preserves line breaks you will need to
|
87 | configure highlight.js to use the `<br>` tag:
|
88 |
|
89 | ```js
|
90 | hljs.configure({useBR: true});
|
91 |
|
92 | document.querySelectorAll('div.code').forEach((block) => {
|
93 | hljs.highlightBlock(block);
|
94 | });
|
95 | ```
|
96 |
|
97 | For other options refer to the documentation for [`configure`][4].
|
98 |
|
99 |
|
100 | ## Using with Vue.js
|
101 |
|
102 | Simply register the plugin with Vue:
|
103 |
|
104 | ```js
|
105 | Vue.use(hljs.vuePlugin);
|
106 | ```
|
107 |
|
108 | And you'll be provided with a `highlightjs` component for use
|
109 | in your templates:
|
110 |
|
111 | ```html
|
112 | <div id="app">
|
113 | <!-- bind to a data property named `code` -->
|
114 | <highlightjs autodetect :code="code" />
|
115 | <!-- or literal code works as well -->
|
116 | <highlightjs language='javascript' code="var x = 5;" />
|
117 | </div>
|
118 | ```
|
119 |
|
120 | ## Web Workers
|
121 |
|
122 | You can run highlighting inside a web worker to avoid freezing the browser
|
123 | window while dealing with very big chunks of code.
|
124 |
|
125 | In your main script:
|
126 |
|
127 | ```js
|
128 | addEventListener('load', () => {
|
129 | const code = document.querySelector('#code');
|
130 | const worker = new Worker('worker.js');
|
131 | worker.onmessage = (event) => { code.innerHTML = event.data; }
|
132 | worker.postMessage(code.textContent);
|
133 | });
|
134 | ```
|
135 |
|
136 | In worker.js:
|
137 |
|
138 | ```js
|
139 | onmessage = (event) => {
|
140 | importScripts('<path>/highlight.min.js');
|
141 | const result = self.hljs.highlightAuto(event.data);
|
142 | postMessage(result.value);
|
143 | };
|
144 | ```
|
145 |
|
146 | ## Node.js
|
147 |
|
148 | You can use highlight.js with node to highlight content before sending it to the browser.
|
149 | Make sure to use the `.value` property to get the formatted html.
|
150 | For more info about the returned object refer to the api docs https://highlightjs.readthedocs.io/en/latest/api.html
|
151 |
|
152 |
|
153 | ```js
|
154 | // require the highlight.js library, including all languages
|
155 | const hljs = require('./highlight.js');
|
156 | const highlightedCode = hljs.highlightAuto('<span>Hello World!</span>').value
|
157 | ```
|
158 |
|
159 | Or for a smaller footprint... load just the languages you need.
|
160 |
|
161 | ```js
|
162 | const hljs = require("highlight.js/lib/core"); // require only the core library
|
163 | // separately require languages
|
164 | hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));
|
165 |
|
166 | const highlightedCode = hljs.highlight('xml', '<span>Hello World!</span>').value
|
167 | ```
|
168 |
|
169 |
|
170 | ## ES6 Modules
|
171 |
|
172 | First, you'll likely install via `npm` or `yarn` -- see [Getting the Library](#getting-the-library) below.
|
173 |
|
174 | In your application:
|
175 |
|
176 | ```js
|
177 | import hljs from 'highlight.js';
|
178 | ```
|
179 |
|
180 | The default import imports all languages. Therefore it is likely to be more efficient to import only the library and the languages you need:
|
181 |
|
182 | ```js
|
183 | import hljs from 'highlight.js/lib/core';
|
184 | import javascript from 'highlight.js/lib/languages/javascript';
|
185 | hljs.registerLanguage('javascript', javascript);
|
186 | ```
|
187 |
|
188 | To set the syntax highlighting style, if your build tool processes CSS from your JavaScript entry point, you can also import the stylesheet directly as modules:
|
189 |
|
190 | ```js
|
191 | import hljs from 'highlight.js/lib/core';
|
192 | import 'highlight.js/styles/github.css';
|
193 | ```
|
194 |
|
195 |
|
196 | ## Getting the Library
|
197 |
|
198 | You can get highlight.js as a hosted, or custom-build, browser script or
|
199 | as a server module. Right out of the box the browser script supports
|
200 | both AMD and CommonJS, so if you wish you can use RequireJS or
|
201 | Browserify without having to build from source. The server module also
|
202 | works perfectly fine with Browserify, but there is the option to use a
|
203 | build specific to browsers rather than something meant for a server.
|
204 |
|
205 |
|
206 | **Do not link to GitHub directly.** The library is not supposed to work straight
|
207 | from the source, it requires building. If none of the pre-packaged options
|
208 | work for you refer to the [building documentation][6].
|
209 |
|
210 | **On Almond.** You need to use the optimizer to give the module a name. For
|
211 | example:
|
212 |
|
213 | ```bash
|
214 | r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
|
215 | ```
|
216 |
|
217 | ### CDN Hosted
|
218 |
|
219 | A prebuilt version of highlight.js bundled with many common languages is hosted by the following CDNs:
|
220 |
|
221 | **cdnjs** ([link](https://cdnjs.com/libraries/highlight.js))
|
222 |
|
223 | ```html
|
224 | <link rel="stylesheet"
|
225 | href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.3.2/styles/default.min.css">
|
226 | <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.3.2/highlight.min.js"></script>
|
227 | <!-- and it's easy to individually load additional languages -->
|
228 | <script charset="UTF-8"
|
229 | src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.3.2/languages/go.min.js"></script>
|
230 | ```
|
231 |
|
232 | **jsdelivr** ([link](https://www.jsdelivr.com/package/gh/highlightjs/cdn-release))
|
233 |
|
234 | ```html
|
235 | <link rel="stylesheet"
|
236 | href="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.3.2/build/styles/default.min.css">
|
237 | <script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.3.2/build/highlight.min.js"></script>
|
238 | ```
|
239 |
|
240 | **Note:** *The CDN-hosted `highlight.min.js` package doesn't bundle every language.* It would be
|
241 | very large. You can find our list "common" languages that we bundle by default on our [download page][5].
|
242 |
|
243 | ### Self Hosting
|
244 |
|
245 | The [download page][5] can quickly generate a custom bundle including only the languages you need.
|
246 |
|
247 | Alternatively, you can build a browser package from [source](#source):
|
248 |
|
249 | ```
|
250 | node tools/build.js -t browser :common
|
251 | ```
|
252 |
|
253 | See our [building documentation][6] for more information.
|
254 |
|
255 | **Note:** Building from source should always result in the smallest size builds. The website download page is optimized for speed, not size.
|
256 |
|
257 |
|
258 | #### Prebuilt CDN assets
|
259 |
|
260 | 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.
|
261 |
|
262 | 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.
|
263 |
|
264 |
|
265 | ### NPM / Node.js server module
|
266 |
|
267 | Highlight.js can also be used on the server. The package with all supported languages can be installed from NPM or Yarn:
|
268 |
|
269 | ```bash
|
270 | npm install highlight.js
|
271 | # or
|
272 | yarn add highlight.js
|
273 | ```
|
274 |
|
275 | Alternatively, you can build it from [source](#source):
|
276 |
|
277 | ```bash
|
278 | node tools/build.js -t node
|
279 | ```
|
280 |
|
281 | See our [building documentation][6] for more information.
|
282 |
|
283 |
|
284 | ### Source
|
285 |
|
286 | [Current source][10] is always available on GitHub.
|
287 |
|
288 |
|
289 | ## License
|
290 |
|
291 | Highlight.js is released under the BSD License. See [LICENSE][7] file
|
292 | for details.
|
293 |
|
294 |
|
295 | ## Links
|
296 |
|
297 | The official site for the library is at <https://highlightjs.org/>.
|
298 |
|
299 | Further in-depth documentation for the API and other topics is at
|
300 | <http://highlightjs.readthedocs.io/>.
|
301 |
|
302 | Authors and contributors are listed in the [AUTHORS.txt][8] file.
|
303 |
|
304 | [1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
|
305 | [2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
|
306 | [3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
|
307 | [4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
|
308 | [5]: https://highlightjs.org/download/
|
309 | [6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
|
310 | [7]: https://github.com/highlightjs/highlight.js/blob/master/LICENSE
|
311 | [8]: https://github.com/highlightjs/highlight.js/blob/master/AUTHORS.txt
|
312 | [9]: https://github.com/highlightjs/highlight.js/blob/master/SUPPORTED_LANGUAGES.md
|
313 | [10]: https://github.com/highlightjs/
|