git.roojs.org Git - roojs1/blob - highlight/README.md

   1 # Highlight.js
   2
   3 [![Build Status](https://travis-ci.org/isagalaev/highlight.js.svg?branch=master)](https://travis-ci.org/isagalaev/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.4.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 ## License
 130
 131 Highlight.js is released under the BSD License. See [LICENSE][7] file
 132 for details.
 133
 134 ## Links
 135
 136 The official site for the library is at <https://highlightjs.org/>.
 137
 138 Further in-depth documentation for the API and other topics is at
 139 <http://highlightjs.readthedocs.io/>.
 140
 141 Authors and contributors are listed in the [AUTHORS.en.txt][8] file.
 142
 143 [1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
 144 [2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
 145 [3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
 146 [4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
 147 [5]: https://highlightjs.org/download/
 148 [6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
 149 [7]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
 150 [8]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.en.txt