1# Highlight.js
2
3Highlight.js highlights syntax in code examples on blogs, forums and
4in fact on any web pages. It's very easy to use because it works
5automatically: finds blocks of code, detects a language, highlights it.
6
7Autodetection can be fine tuned when it fails by itself (see "Heuristics").
8
9## Installation and usage
10
11Downloaded package includes file "highlight.pack.js" which is a full compressed
12version of the library intended to use in production. All uncompressed source
13files are also available, feel free to look into them!
14
15The script is installed by linking to a single file and making a single
16initialization call:
17
18    <script type="text/javascript" src="highlight.pack.js"></script>
19    <script type="text/javascript">
20      hljs.initHighlightingOnLoad();
21    </script>
22
23Also you can replaces TAB ('\x09') characters used for indentation in your code
24with some fixed number of spaces or with a `<span>` to set them special styling:
25
26    <script type="text/javascript">
27      hljs.tabReplace = '    '; // 4 spaces
28      // ... or
29      hljs.tabReplace = '<span class="indent">\t</span>';
30
31      hljs.initHighlightingOnLoad();
32    </script>
33
34Despite highlight.pack.js already includes only those languages that you need sometimes
35you may want to further constrain a set of languages used on a page by listing them as
36parameters to initialization:
37
38    <script type="text/javascript">
39      hljs.initHighlightingOnLoad('html', 'css');
40    </script>
41
42A full list of available classes is below ("Languages").
43
44Then the script looks in your page for fragments `<pre><code>...</code></pre>`
45that are used traditionally to mark up code examples. Their content is
46marked up by logical pieces with defined class names. The classes are
47used to actually style the code elements:
48
49    .comment {
50      color: gray;
51    }
52
53    .keyword {
54      font-weight: bold;
55    }
56
57    .python .string {
58      color: blue;
59    }
60
61    .html .atribute .value {
62      color: green;
63    }
64
65Highligt.js comes with several style themes located in "styles" directory that
66can be used directly or as a base for your own experiments.
67
68### WordPress plugin
69
70Generally installing highlight.js in a [WordPress][wp] blog is no different
71than for any other web page. However it can also be installed as a plugin.
72This is useful if your blog is located on a shared hosting and you don't
73have a permission to edit template and style files. Or it may be more convenient
74to you this way.
75
76To install the plugin copy the whole directory with highlight.js to the
77WordPress plugins directory. After this you can activate and deactivate it
78from the Plugins panel. There is also a page "highlight.js" under the Options
79menu where you can set a list of languages and style rules. Insanely convenient :-)
80
81[wp]: http://wordpress.org/
82
83
84## Export
85
86File export.html contains a little program that shows and allows to copy and paste
87an HTML code generated by the highlighter for any code snippet. This can be useful
88in situations when one can't use the script itself on a site.
89
90
91## Languages
92
93This is a full list of available classes corresponding to languages'
94syntactic structures. In parentheses after language names are identifiers
95used as class names in `<code>` element.
96
97Python ("python"):
98
99  keyword          keyword
100  built_in         built-in objects (None, False, True and Ellipsis)
101  number           number
102  string           string (of any type)
103  comment          comment
104  decorator        @-decorator for functions
105  function         function header "def some_name(...):"
106  class            class header "class SomeName(...):"
107  title            name of a function or a class inside a header
108  params           everything inside parentheses in a function's or class' header
109
110Python profiler results ("profile"):
111
112  number           number
113  string           string
114  builtin          builtin function entry
115  filename         filename in an entry
116  summary          profiling summary
117  header           header of table of results
118  keyword          column header
119  function         function name in an entry (including parentheses)
120  title            actual name of a function in an entry (excluding parentheses)
121
122Ruby ("ruby"):
123
124  keyword          keyword
125  string           string
126  subst            in-string substitution (#{...})
127  comment          comment
128  function         function header "def some_name(...):"
129  class            class header "class SomeName(...):"
130  title            name of a function or a class inside a header
131  parent           name of a parent class
132  symbol           symbol
133  instancevar      instance variable
134
135Perl ("perl"):
136
137  keyword          keyword
138  comment          comment
139  number           number
140  string           string
141  regexp           regular expression
142  sub              subroutine header (from "sub" till "{")
143  variable         variable starting with "$", "%", "@"
144  operator         operator
145  pod              plain old doc
146
147PHP ("php"):
148
149  keyword          keyword
150  number           number
151  string           string (of any type)
152  comment          comment
153  phpdoc           phpdoc params in comments
154  variable         variable starting with "$"
155  preprocessor     preprocessor marks: "<?php" and "?>"
156
157XML ("xml"):
158
159  tag              any tag from "<" till ">"
160  comment          comment
161  pi               processing instruction (<? ... ?>)
162  cdata            CDATA section
163  attribute        attribute
164  value            attribute's value
165
166HTML ("html"):
167
168  keyword          HTML tag
169  tag              any tag from "<" till ">"
170  comment          comment
171  doctype          <!DOCTYPE ... > declaration
172  attribute        tag's attribute with or without value
173  value            attribute's value
174
175CSS ("css"):
176
177  keyword          HTML tag when in selectors, CSS keyword when in rules
178  id               #some_name in selectors
179  class            .some_name in selectors
180  at_rule          @-rule till first "{" or ";"
181  attr_selector    attribute selector (square brackets in a[href^=http://])
182  pseudo           pseudo classes and elemens (:after, ::after etc.)
183  comment          comment
184  rules            everything from "{" till "}"
185  value            property's value inside a rule, from ":" till ";" or
186                   till the end of rule block
187  number           number within a value
188  string           string within a value
189  hexcolor         hex color (#FFFFFF) within a value
190  function         CSS function within a value
191  params           everything between "(" and ")" within a function
192
193Django ("django"):
194
195  keyword          HTML tag in HTML, default tags and default filters in templates
196  tag              any tag from "<" till ">"
197  comment          comment
198  doctype          <!DOCTYPE ... > declaration
199  attribute        tag's attribute with or withou value
200  value            attribute's value
201  template_tag     template tag {% .. %}
202  variable         template variable {{ .. }}
203  template_comment template comment, both {# .. #} and {% comment %}
204  filter           filter from "|" till the next filter or the end of tag
205  argument         filter argument
206
207Javascript ("javascript"):
208
209  keyword          keyword
210  comment          comment
211  number           number
212  literal          special literal: "true", "false" and "null"
213  string           string
214  regexp           regular expression
215  function         header of a function
216  title            name of a function inside a header
217  params           everything inside parentheses in a function's header
218
219VBScript ("vbscript"):
220
221  keyword          keyword
222  number           number
223  string           string
224  comment          comment
225  built_in         built-in function
226
227Delphi ("delphi"):
228
229  keyword          keyword
230  comment          comment (of any type)
231  number           number
232  string           string
233  function         header of a function, procedure, constructor and destructor
234  title            name of a function, procedure, constructor or destructor
235                   inside a header
236  params           everything inside parentheses in a function's header
237  class            class' body from "= class" till "end;"
238
239Java ("java"):
240
241  keyword          keyword
242  number           number
243  string           string
244  comment          commment
245  annotaion        annotation
246  javadoc          javadoc comment
247  class            class header from "class" till "{"
248  title            class name inside a header
249  params           everything in parentheses inside a class header
250  inheritance      keywords "extends" and "implements" inside class header
251
252C++ ("cpp"):
253
254  keyword          keyword
255  number           number
256  string           string and character
257  comment          comment
258  preprocessor     preprocessor directive
259  stl_container    instantiation of STL containers ("vector<...>")
260
261C# ("cs"):
262
263  keyword          keyword
264  number           number
265  string           string
266  comment          commment
267  xmlDocTag        xmldoc tag ("///", "<!--", "-->", "<..>")
268
269RenderMan RSL ("rsl"):
270
271  keyword          keyword
272  number           number
273  string           string (including @"..")
274  comment          comment
275  preprocessor     preprocessor directive
276  shader           sahder keywords
277  shading          shading keywords
278  built_in         built-in function
279
280RenderMan RIB ("rib"):
281
282  keyword          keyword
283  number           number
284  string           string
285  comment          comment
286  commands         command
287
288Maya Embedded Language ("mel"):
289
290  keyword          keyword
291  number           number
292  string           string
293  comment          comment
294  variable         variable
295
296SQL ("sql"):
297
298  keyword          keyword (mostly SQL'92 and SQL'99)
299  number           number
300  string           string (of any type: "..", '..', `..`)
301  comment          comment
302  aggregate        aggregate function
303
304Smalltalk ("smalltalk"):
305
306  keyword          keyword
307  number           number
308  string           string
309  comment          commment
310  symbol           symbol
311  array            array
312  class            name of a class
313  char             char
314  localvars        block of local variables
315
316Lisp ("lisp"):
317
318  keyword          keyword
319  number           number
320  string           string
321  comment          commment
322  variable         variable
323  literal          b, t and nil
324  list             non-quoted list
325  title            first symbol in a non-quoted list
326  body             remainder of the non-quoted list
327  quoted_list      quoted list, both "(quote .. )" and "'(..)"
328
329Ini ("ini"):
330
331  title            title of a section
332  value            value of a setting of any type
333  string           string
334  number           number
335  keyword          boolean value keyword
336
337Apache ("apache"):
338
339  keyword          keyword
340  number           number
341  comment          commment
342  literal          On and Off
343  sqbracket        variables in rewrites "%{..}"
344  cbracket         options in rewrites "[..]"
345  tag              begin and end of a configuration section
346
347DOS ("dos"):
348
349  keyword          keyword
350  flow             batch control keyword
351  stream           DOS special files ("con", "prn", ...)
352  winutils         some commands (see dos.js specifically)
353  envvar           environment variables
354
355Bash ("bash"):
356
357  keyword          keyword
358  string           string
359  number           number
360  comment          comment
361  literal          special literal: "true" и "false"
362  variable         variable
363  shebang          script interpreter header
364
365Diff ("diff"):
366
367  header           file header
368  chunk            chunk header within a file
369  addition         added lines
370  deletion         deleted lines
371  change           changed lines
372
373Axapta ("axapta"):
374
375  keyword          keyword
376  number           number
377  string           string
378  comment          commment
379  class            class header from "class" till "{"
380  title            class name inside a header
381  params           everything in parentheses inside a class header
382  inheritance      keywords "extends" and "implements" inside class header
383  preprocessor     preprocessor directive
384
3851C ("1c"):
386
387  keyword          keyword
388  number           number
389  date             date
390  string           string
391  comment          commment
392  function         header of function or procudure
393  title            function name inside a header
394  params           everything in parentheses inside a function header
395  preprocessor     preprocessor directive
396
397AVR assembler ("avrasm"):
398
399  keyword          keyword
400  built_in         pre-defined register
401  number           number
402  string           string
403  comment          commment
404  label            label
405  preprocessor     preprocessor directive
406  localvars        substitution in .macro
407
408Parser3 ("parser3"):
409
410  keyword          keyword
411  number           number
412  comment          commment
413  variable         variable starting with "$"
414  preprocessor     preprocessor directive
415  title            user-defined name starting with "@"
416
417## Heuristics
418
419Autodetection of a code's language is done with a simple heuristics:
420the program tries to highlight a fragment with all available languages and
421counts all syntactic structures that it finds along the way. The language
422with greatest count wins.
423
424This means that in short fragments the probability of an error is high
425(and it really happens sometimes). In this cases you can set the fragment's
426language explicitly by assigning a class to the `<code>` element:
427
428    <pre><code class="html">...</code></pre>
429
430You can use class names recommended in HTML5: "language-html",
431"language-php". Classes also can be assigned to the `<pre>` element.
432
433To disable highlighting of a fragment altogether use "no-highlight" class:
434
435    <pre><code class="no-highlight">...</code></pre>
436
437## Contacts
438
439Version: 5.7
440URL:     http://softwaremaniacs.org/soft/highlight/en/
441Author:  Ivan Sagalaev (Maniac@SoftwareManiacs.Org)
442
443For the license terms see LICENSE files.
444For the list of contributors see AUTHORS.en.txt file.
445