pkgs/misc/documentation-highlighter/README.md

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