Mercurial > eldonilo > lightstring
diff console/lib/highlight/README.md @ 108:5cb4733c5189
many api changes
author | Sonny Piers <sonny@fastmail.net> |
---|---|
date | Fri, 13 Jul 2012 15:26:18 +0200 |
parents | |
children |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/console/lib/highlight/README.md @@ -0,0 +1,120 @@ +# Highlight.js + +Highlight.js highlights syntax in code examples on blogs, forums and, +in fact, on any web page. It's very easy to use because it works +automatically: finds blocks of code, detects a language, highlights it. + +Autodetection can be fine tuned when it fails by itself (see "Heuristics"). + + +## Basic usage + +Link the library and a stylesheet from your page and hook highlighting to +the page load event: + +```html +<link rel="stylesheet" href="styles/default.css"> +<script src="highlight.pack.js"></script> +<script>hljs.initHighlightingOnLoad();</script> +``` + +This will highlight all code on the page marked up as `<pre><code> .. </code></pre>`. +If you use different markup or need to apply highlighting dynamically, read +"Custom initialization" below. + +- You can download your own customized version of "highlight.pack.js" or + use the hosted one as described on the download page: + <http://softwaremaniacs.org/soft/highlight/en/download/> + +- Style themes are available in the download package or as hosted files. + To create a custom style for your site see the class reference in the file + [classref.txt][cr] from the downloaded package. + +[cr]: http://github.com/isagalaev/highlight.js/blob/master/classref.txt + + +## Tab replacement + +You can replace TAB ('\x09') characters used for indentation in your code +with some fixed number of spaces or with a `<span>` to give them special +styling: + +```html +<script type="text/javascript"> + hljs.tabReplace = ' '; // 4 spaces + // ... or + hljs.tabReplace = '<span class="indent">\t</span>'; + + hljs.initHighlightingOnLoad(); +</script> +``` + +## Custom initialization + +If you use different markup for code blocks you can initialize them manually +with `highlightBlock(code, tabReplace, useBR)` function. It takes a DOM element +containing the code to highlight and optionally a string with which to replace +TAB characters. + +Initialization using, for example, jQuery might look like this: + +```javascript +$(document).ready(function() { + $('pre code').each(function(i, e) {hljs.highlightBlock(e)}); +}); +``` + +You can use `highlightBlock` to highlight blocks dynamically inserted into +the page. Just make sure you don't do it twice for already highlighted +blocks. + +If your code container relies on `<br>` tags instead of line breaks (i.e. if +it's not `<pre>`) pass `true` into the third parameter of `highlightBlock` +to make highlight.js use `<br>` in the output: + +```javascript +$('div.code').each(function(i, e) {hljs.highlightBlock(e, null, true)}); +``` + + +## Heuristics + +Autodetection of a code's language is done using a simple heuristic: +the program tries to highlight a fragment with all available languages and +counts all syntactic structures that it finds along the way. The language +with greatest count wins. + +This means that in short fragments the probability of an error is high +(and it really happens sometimes). In this cases you can set the fragment's +language explicitly by assigning a class to the `<code>` element: + +```html +<pre><code class="html">...</code></pre> +``` + +You can use class names recommended in HTML5: "language-html", +"language-php". Classes also can be assigned to the `<pre>` element. + +To disable highlighting of a fragment altogether use "no-highlight" class: + +```html +<pre><code class="no-highlight">...</code></pre> +``` + + +## Export + +File export.html contains a little program that allows you to paste in a code +snippet and then copy and paste the resulting HTML code generated by the +highlighter. This is useful in situations when you can't use the script itself +on a site. + + +## Meta + +- Version: 7.0 +- URL: http://softwaremaniacs.org/soft/highlight/en/ +- Author: Ivan Sagalaev (<maniac@softwaremaniacs.org>) + +For the license terms see LICENSE files. +For the list of contributors see AUTHORS.en.txt file.