highlight.js/README.md

   1 # Highlight.js
   2
   3 Highlight.js highlights syntax in code examples on blogs, forums and,
   4 in fact, on any web page. It's very easy to use because it works
   5 automatically: finds blocks of code, detects a language, highlights it.
   6
   7 Autodetection can be fine tuned when it fails by itself (see "Heuristics").
   8
   9
  10 ## Basic usage
  11
  12 Link the library and a stylesheet from your page and hook highlighting to
  13 the page load event:
  14
  15 ```html
  16 <link rel="stylesheet" href="styles/default.css">
  17 <script src="highlight.pack.js"></script>
  18 <script>hljs.initHighlightingOnLoad();</script>
  19 ```
  20
  21 This will highlight all code on the page marked up as `<pre><code> .. </code></pre>`.
  22 If you use different markup or need to apply highlighting dynamically, read
  23 "Custom initialization" below.
  24
  25 - You can download your own customized version of "highlight.pack.js" or
  26   use the hosted one as described on the download page:
  27   <http://softwaremaniacs.org/soft/highlight/en/download/>
  28
  29 - Style themes are available in the download package or as hosted files.
  30   To create a custom style for your site see the class reference in the file
  31   [classref.txt][cr] from the downloaded package.
  32
  33 [cr]: http://github.com/isagalaev/highlight.js/blob/master/classref.txt
  34
  35
  36 ## node.js
  37
  38 Highlight.js can be used under node.js. The package with all supported languages is
  39 installable from NPM:
  40
  41     npm install highlight.js
  42
  43 Alternatively, you can build it from the source with only languages you need:
  44
  45     python tools/build.py -tnode lang1 lang2 ..
  46
  47 Using the library:
  48
  49 ```javascript
  50 var hljs = require('highlight.js');
  51
  52 // If you know the language
  53 hljs.highlight(lang, code).value;
  54
  55 // Automatic language detection
  56 hljs.highlightAuto(code).value;
  57 ```
  58
  59 ## Tab replacement
  60
  61 You can replace TAB ('\x09') characters used for indentation in your code
  62 with some fixed number of spaces or with a `<span>` to give them special
  63 styling:
  64
  65 ```html
  66 <script type="text/javascript">
  67   hljs.tabReplace = '    '; // 4 spaces
  68   // ... or
  69   hljs.tabReplace = '<span class="indent">\t</span>';
  70
  71   hljs.initHighlightingOnLoad();
  72 </script>
  73 ```
  74
  75 ## Custom initialization
  76
  77 If you use different markup for code blocks you can initialize them manually
  78 with `highlightBlock(code, tabReplace, useBR)` function. It takes a DOM element
  79 containing the code to highlight and optionally a string with which to replace
  80 TAB characters.
  81
  82 Initialization using, for example, jQuery might look like this:
  83
  84 ```javascript
  85 $(document).ready(function() {
  86   $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
  87 });
  88 ```
  89
  90 You can use `highlightBlock` to highlight blocks dynamically inserted into
  91 the page. Just make sure you don't do it twice for already highlighted
  92 blocks.
  93
  94 If your code container relies on `<br>` tags instead of line breaks (i.e. if
  95 it's not `<pre>`) pass `true` into the third parameter of `highlightBlock`
  96 to make highlight.js use `<br>` in the output:
  97
  98 ```javascript
  99 $('div.code').each(function(i, e) {hljs.highlightBlock(e, null, true)});
 100 ```
 101
 102
 103 ## Heuristics
 104
 105 Autodetection of a code's language is done using a simple heuristic:
 106 the program tries to highlight a fragment with all available languages and
 107 counts all syntactic structures that it finds along the way. The language
 108 with greatest count wins.
 109
 110 This means that in short fragments the probability of an error is high
 111 (and it really happens sometimes). In this cases you can set the fragment's
 112 language explicitly by assigning a class to the `<code>` element:
 113
 114 ```html
 115 <pre><code class="html">...</code></pre>
 116 ```
 117
 118 You can use class names recommended in HTML5: "language-html",
 119 "language-php". Classes also can be assigned to the `<pre>` element.
 120
 121 To disable highlighting of a fragment altogether use "no-highlight" class:
 122
 123 ```html
 124 <pre><code class="no-highlight">...</code></pre>
 125 ```
 126
 127
 128 ## Export
 129
 130 File export.html contains a little program that allows you to paste in a code
 131 snippet and then copy and paste the resulting HTML code generated by the
 132 highlighter. This is useful in situations when you can't use the script itself
 133 on a site.
 134
 135
 136 ## Meta
 137
 138 - Version: 7.3
 139 - URL:     http://softwaremaniacs.org/soft/highlight/en/
 140 - Author:  Ivan Sagalaev (<maniac@softwaremaniacs.org>)
 141
 142 For the license terms see LICENSE files.
 143 For the list of contributors see AUTHORS.en.txt file.