1 | # Highlight.js
|
2 |
|
3 | [![Build Status](https://travis-ci.org/highlightjs/highlight.js.svg?branch=master)](https://travis-ci.org/highlightjs/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 | ## Getting Started
|
11 |
|
12 | The bare minimum for using highlight.js on a web page is linking to the
|
13 | library along with one of the styles and calling
|
14 | [`initHighlightingOnLoad`][1]:
|
15 |
|
16 | ```html
|
17 | <link rel="stylesheet" href="/path/to/styles/default.css">
|
18 | <script src="/path/to/highlight.pack.js"></script>
|
19 | <script>hljs.initHighlightingOnLoad();</script>
|
20 | ```
|
21 |
|
22 | This will find and highlight code inside of `<pre><code>` tags; it tries
|
23 | to detect the language automatically. If automatic detection doesn’t
|
24 | work for you, you can specify the language in the `class` attribute:
|
25 |
|
26 | ```html
|
27 | <pre><code class="html">...</code></pre>
|
28 | ```
|
29 |
|
30 | The list of supported language classes is available in the [class
|
31 | reference][2]. Classes can also be prefixed with either `language-` or
|
32 | `lang-`.
|
33 |
|
34 | To disable highlighting altogether use the `nohighlight` class:
|
35 |
|
36 | ```html
|
37 | <pre><code class="nohighlight">...</code></pre>
|
38 | ```
|
39 |
|
40 | ## Custom Initialization
|
41 |
|
42 | When you need a bit more control over the initialization of
|
43 | highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
|
44 | functions. This allows you to control *what* to highlight and *when*.
|
45 |
|
46 | Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using
|
47 | jQuery:
|
48 |
|
49 | ```javascript
|
50 | $(document).ready(function() {
|
51 | $('pre code').each(function(i, block) {
|
52 | hljs.highlightBlock(block);
|
53 | });
|
54 | });
|
55 | ```
|
56 |
|
57 | You can use any tags instead of `<pre><code>` to mark up your code. If
|
58 | you don't use a container that preserve line breaks you will need to
|
59 | configure highlight.js to use the `<br>` tag:
|
60 |
|
61 | ```javascript
|
62 | hljs.configure({useBR: true});
|
63 |
|
64 | $('div.code').each(function(i, block) {
|
65 | hljs.highlightBlock(block);
|
66 | });
|
67 | ```
|
68 |
|
69 | For other options refer to the documentation for [`configure`][4].
|
70 |
|
71 |
|
72 | ## Web Workers
|
73 |
|
74 | You can run highlighting inside a web worker to avoid freezing the browser
|
75 | window while dealing with very big chunks of code.
|
76 |
|
77 | In your main script:
|
78 |
|
79 | ```javascript
|
80 | addEventListener('load', function() {
|
81 | var code = document.querySelector('#code');
|
82 | var worker = new Worker('worker.js');
|
83 | worker.onmessage = function(event) { code.innerHTML = event.data; }
|
84 | worker.postMessage(code.textContent);
|
85 | })
|
86 | ```
|
87 |
|
88 | In worker.js:
|
89 |
|
90 | ```javascript
|
91 | onmessage = function(event) {
|
92 | importScripts('<path>/highlight.pack.js');
|
93 | var result = self.hljs.highlightAuto(event.data);
|
94 | postMessage(result.value);
|
95 | }
|
96 | ```
|
97 |
|
98 |
|
99 | ## Getting the Library
|
100 |
|
101 | You can get highlight.js as a hosted, or custom-build, browser script or
|
102 | as a server module. Right out of the box the browser script supports
|
103 | both AMD and CommonJS, so if you wish you can use RequireJS or
|
104 | Browserify without having to build from source. The server module also
|
105 | works perfectly fine with Browserify, but there is the option to use a
|
106 | build specific to browsers rather than something meant for a server.
|
107 | Head over to the [download page][5] for all the options.
|
108 |
|
109 | **Don't link to GitHub directly.** The library is not supposed to work straight
|
110 | from the source, it requires building. If none of the pre-packaged options
|
111 | work for you refer to the [building documentation][6].
|
112 |
|
113 | **The CDN-hosted package doesn't have all the languages.** Otherwise it'd be
|
114 | too big. If you don't see the language you need in the ["Common" section][5],
|
115 | it can be added manually:
|
116 |
|
117 | ```html
|
118 | <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/languages/go.min.js"></script>
|
119 | ```
|
120 |
|
121 | **On Almond.** You need to use the optimizer to give the module a name. For
|
122 | example:
|
123 |
|
124 | ```
|
125 | r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
|
126 | ```
|
127 |
|
128 |
|
129 | ### CommonJS
|
130 |
|
131 | You can import Highlight.js as a CommonJS-module:
|
132 |
|
133 | ```bash
|
134 | npm install highlight.js --save
|
135 | ```
|
136 |
|
137 | In your application:
|
138 |
|
139 | ```javascript
|
140 | import hljs from 'highlight.js';
|
141 | ```
|
142 |
|
143 | The default import imports all languages! Therefore it is likely to be more efficient to import only the library and the languages you need:
|
144 |
|
145 | ```javascript
|
146 | import hljs from 'highlight.js/lib/highlight';
|
147 | import javascript from 'highlight.js/lib/languages/javascript';
|
148 | hljs.registerLanguage('javascript', javascript);
|
149 | ```
|
150 |
|
151 |
|
152 | ## License
|
153 |
|
154 | Highlight.js is released under the BSD License. See [LICENSE][7] file
|
155 | for details.
|
156 |
|
157 | ## Links
|
158 |
|
159 | The official site for the library is at <https://highlightjs.org/>.
|
160 |
|
161 | Further in-depth documentation for the API and other topics is at
|
162 | <http://highlightjs.readthedocs.io/>.
|
163 |
|
164 | Authors and contributors are listed in the [AUTHORS.en.txt][8] file.
|
165 |
|
166 | [1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
|
167 | [2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
|
168 | [3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
|
169 | [4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
|
170 | [5]: https://highlightjs.org/download/
|
171 | [6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
|
172 | [7]: https://github.com/highlightjs/highlight.js/blob/master/LICENSE
|
173 | [8]: https://github.com/highlightjs/highlight.js/blob/master/AUTHORS.en.txt
|