|
108
|
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 ## Tab replacement
|
|
|
37
|
|
|
38 You can replace TAB ('\x09') characters used for indentation in your code
|
|
|
39 with some fixed number of spaces or with a `<span>` to give them special
|
|
|
40 styling:
|
|
|
41
|
|
|
42 ```html
|
|
|
43 <script type="text/javascript">
|
|
|
44 hljs.tabReplace = ' '; // 4 spaces
|
|
|
45 // ... or
|
|
|
46 hljs.tabReplace = '<span class="indent">\t</span>';
|
|
|
47
|
|
|
48 hljs.initHighlightingOnLoad();
|
|
|
49 </script>
|
|
|
50 ```
|
|
|
51
|
|
|
52 ## Custom initialization
|
|
|
53
|
|
|
54 If you use different markup for code blocks you can initialize them manually
|
|
|
55 with `highlightBlock(code, tabReplace, useBR)` function. It takes a DOM element
|
|
|
56 containing the code to highlight and optionally a string with which to replace
|
|
|
57 TAB characters.
|
|
|
58
|
|
|
59 Initialization using, for example, jQuery might look like this:
|
|
|
60
|
|
|
61 ```javascript
|
|
|
62 $(document).ready(function() {
|
|
|
63 $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
|
|
|
64 });
|
|
|
65 ```
|
|
|
66
|
|
|
67 You can use `highlightBlock` to highlight blocks dynamically inserted into
|
|
|
68 the page. Just make sure you don't do it twice for already highlighted
|
|
|
69 blocks.
|
|
|
70
|
|
|
71 If your code container relies on `<br>` tags instead of line breaks (i.e. if
|
|
|
72 it's not `<pre>`) pass `true` into the third parameter of `highlightBlock`
|
|
|
73 to make highlight.js use `<br>` in the output:
|
|
|
74
|
|
|
75 ```javascript
|
|
|
76 $('div.code').each(function(i, e) {hljs.highlightBlock(e, null, true)});
|
|
|
77 ```
|
|
|
78
|
|
|
79
|
|
|
80 ## Heuristics
|
|
|
81
|
|
|
82 Autodetection of a code's language is done using a simple heuristic:
|
|
|
83 the program tries to highlight a fragment with all available languages and
|
|
|
84 counts all syntactic structures that it finds along the way. The language
|
|
|
85 with greatest count wins.
|
|
|
86
|
|
|
87 This means that in short fragments the probability of an error is high
|
|
|
88 (and it really happens sometimes). In this cases you can set the fragment's
|
|
|
89 language explicitly by assigning a class to the `<code>` element:
|
|
|
90
|
|
|
91 ```html
|
|
|
92 <pre><code class="html">...</code></pre>
|
|
|
93 ```
|
|
|
94
|
|
|
95 You can use class names recommended in HTML5: "language-html",
|
|
|
96 "language-php". Classes also can be assigned to the `<pre>` element.
|
|
|
97
|
|
|
98 To disable highlighting of a fragment altogether use "no-highlight" class:
|
|
|
99
|
|
|
100 ```html
|
|
|
101 <pre><code class="no-highlight">...</code></pre>
|
|
|
102 ```
|
|
|
103
|
|
|
104
|
|
|
105 ## Export
|
|
|
106
|
|
|
107 File export.html contains a little program that allows you to paste in a code
|
|
|
108 snippet and then copy and paste the resulting HTML code generated by the
|
|
|
109 highlighter. This is useful in situations when you can't use the script itself
|
|
|
110 on a site.
|
|
|
111
|
|
|
112
|
|
|
113 ## Meta
|
|
|
114
|
|
|
115 - Version: 7.0
|
|
|
116 - URL: http://softwaremaniacs.org/soft/highlight/en/
|
|
|
117 - Author: Ivan Sagalaev (<maniac@softwaremaniacs.org>)
|
|
|
118
|
|
|
119 For the license terms see LICENSE files.
|
|
|
120 For the list of contributors see AUTHORS.en.txt file.
|
