Mercurial > eldonilo > lightstring

comparison console/lib/highlight/README.md @ 108:5cb4733c5189

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
many api changes
author Sonny Piers <sonny@fastmail.net>
date Fri, 13 Jul 2012 15:26:18 +0200
parents
children
comparison
equal deleted inserted replaced
107:704ce44c1a22 108:5cb4733c5189
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.