Highlightjs - Syntax Highlighting your Blog with highlight.js by Susan Diaz

highlight.js Documentation Release 8.1

Ivan Sagalaev

July 09, 2014

Contents

Library API 1.1 highlight(name, value, ignore_illegals, 1.2 highlightAuto(value, languageSubset) . . 1.3 fixMarkup(value) . . . . . . . . . . . . . . . . . . 1.4 highlightBlock(block) . . . . . . . . . . . . . . 1.5 configure(options) . . . . . . . . . . . . . . . . . 1.6 initHighlighting() . . . . . . . . . . . . . . . . . 1.7 initHighlightingOnLoad() . . . . . . . . . . . . 1.8 registerLanguage(name, language) . . . . . 1.9 listLanguages() . . . . . . . . . . . . . . . . . . . 1.10 getLanguage(name) . . . . . . . . . . . . . . . . .

continuation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . .

3 3 3 3 4 4 4 4 4 5 5

Language definition guide 2.1 Highlighting overview . . . . . . . . . . . 2.2 General syntax . . . . . . . . . . . . . . . 2.3 Keywords . . . . . . . . . . . . . . . . . . 2.4 Sub-modes . . . . . . . . . . . . . . . . . 2.5 Markup generation . . . . . . . . . . . . . 2.6 Mode attributes . . . . . . . . . . . . . . . 2.7 Relevance . . . . . . . . . . . . . . . . . . 2.8 Illegal symbols . . . . . . . . . . . . . . . 2.9 Pre-defined modes and regular expressions 2.10 Contributing . . . . . . . . . . . . . . . .

. . . . . . . . . .

7 7 7 8 8 9 9 9 10 10 10

Mode reference 3.1 Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11 11 11

CSS classes reference 4.1 Python (“python”, “py”, “gyp”) . . . . . . . . . . . . . . 4.2 Python profiler results (“profile”) . . . . . . . . . . . . . 4.3 Ruby (“ruby”, “rb”, “gemspec”, “podspec”, “thor”, “irb”) 4.4 Haml (“haml”) . . . . . . . . . . . . . . . . . . . . . . . 4.5 Perl (“perl”, “pl”) . . . . . . . . . . . . . . . . . . . . . . 4.6 PHP (“php”, “php3”, “php4”, “php5”, “php6”) . . . . . . 4.7 Scala (“scala”) . . . . . . . . . . . . . . . . . . . . . . . 4.8 Go (“go”, “golang”) . . . . . . . . . . . . . . . . . . . . 4.9 Gradle (“gradle”) . . . . . . . . . . . . . . . . . . . . . .

17 17 17 18 18 18 19 19 19 20

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . .

4.10 4.11 4.12 4.13 4.14 4.15 4.16 4.17 4.18 4.19 4.20 4.21 4.22 4.23 4.24 4.25 4.26 4.27 4.28 4.29 4.30 4.31 4.32 4.33 4.34 4.35 4.36 4.37 4.38 4.39 4.40 4.41 4.42 4.43 4.44 4.45 4.46 4.47 4.48 4.49 4.50 4.51 4.52 4.53 4.54 4.55 4.56 4.57 4.58 4.59 4.60 4.61 4.62 4.63

HTML, XML (“xml”, “html”, “xhtml”, “rss”, “atom”, “xsl”, “plist”) Lasso (“lasso”, “ls”, “lassoscript”) . . . . . . . . . . . . . . . . . . . CSS (“css”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SCSS (“scss”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Markdown (“markdown”, “md”, “mkdown”, “mkd”) . . . . . . . . . AsciiDoc (“asciidoc”) . . . . . . . . . . . . . . . . . . . . . . . . . Django (“django”, “jinja”) . . . . . . . . . . . . . . . . . . . . . . . Handlebars (“handlebars”, “hbs”, “html.hbs”, “html.handlebars”) . . JSON (“json”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mathematica (“mathematica”, “mma”) . . . . . . . . . . . . . . . . JavaScript (“javascript”, “js”) . . . . . . . . . . . . . . . . . . . . . TypeScript (“typescript”, “ts”) . . . . . . . . . . . . . . . . . . . . . CoffeeScript (“coffeescript”, “coffee”, “cson”, “iced”) . . . . . . . . ActionScript (“actionscript”, “as”) . . . . . . . . . . . . . . . . . . . Haxe (“haxe”, “hx”) . . . . . . . . . . . . . . . . . . . . . . . . . . VBScript (“vbscript”, “vbs”) . . . . . . . . . . . . . . . . . . . . . . VB.Net (“vbnet”, “vb”) . . . . . . . . . . . . . . . . . . . . . . . . Protocol Buffers (“protobuf”) . . . . . . . . . . . . . . . . . . . . . Cap’n Proto (“capnproto”, “capnp”) . . . . . . . . . . . . . . . . . . Thrift (“thrift”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTTP (“http”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lua (“lua”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Delphi (“delphi”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oxygene (“oxygene”) . . . . . . . . . . . . . . . . . . . . . . . . . Java (“java”, “jsp”) . . . . . . . . . . . . . . . . . . . . . . . . . . . C++ (“cpp”, “c”, “h”, “c++”, “h++”) . . . . . . . . . . . . . . . . . Objective C (“objectivec”, “m”, “mm”, “objc”, “obj-c”) . . . . . . . Vala (“vala”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C# (“cs”, “csharp”) . . . . . . . . . . . . . . . . . . . . . . . . . . . F# (“fsharp”, “fs”) . . . . . . . . . . . . . . . . . . . . . . . . . . . OCaml (“ocaml”, “ml”) . . . . . . . . . . . . . . . . . . . . . . . . D (“d”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RenderMan RSL (“rsl”) . . . . . . . . . . . . . . . . . . . . . . . . RenderMan RIB (“rib”) . . . . . . . . . . . . . . . . . . . . . . . . Maya Embedded Language (“mel”) . . . . . . . . . . . . . . . . . . SQL (“sql”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Smalltalk (“smalltalk”, “st”) . . . . . . . . . . . . . . . . . . . . . . Lisp (“lisp”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clojure (“clojure”, “clj”) . . . . . . . . . . . . . . . . . . . . . . . . Ini (“ini”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Apache (“apache”, “apacheconf”) . . . . . . . . . . . . . . . . . . . Nginx (“nginx”, “nginxconf”) . . . . . . . . . . . . . . . . . . . . . Diff (“diff”, “patch”) . . . . . . . . . . . . . . . . . . . . . . . . . . DOS (“dos”, “bat”, “cmd”) . . . . . . . . . . . . . . . . . . . . . . Bash (“bash”, “sh”, “zsh”) . . . . . . . . . . . . . . . . . . . . . . . Makefile (“makefile”, “mk”, “mak”) . . . . . . . . . . . . . . . . . . CMake (“cmake”, “cmake.in”) . . . . . . . . . . . . . . . . . . . . . Nix (“nix”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NSIS (“nsis”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Axapta (“axapta”) . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Rules Language (“ruleslanguage”) . . . . . . . . . . . . . . . 1C (“1c”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x86 Assembly (“x86asm”) . . . . . . . . . . . . . . . . . . . . . . . AVR assembler (“avrasm”) . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

20 20 21 21 22 22 22 23 23 23 23 24 24 25 25 26 26 26 26 27 27 27 28 28 28 29 29 29 29 30 30 30 30 31 31 31 31 32 32 32 33 33 33 33 34 34 34 34 35 35 35 35 36 36

4.64 4.65 4.66 4.67 4.68 4.69 4.70 4.71 4.72 4.73 4.74 4.75 4.76 4.77 4.78 4.79 4.80 4.81 4.82 4.83 4.84 4.85

. . . . . . . . . . . . . . . . . . . . . .

36 37 37 37 38 38 38 39 39 39 40 40 40 41 41 41 41 42 42 42 42 43

. . . . . .

45 45 45 45 46 46 46

Building and testing 6.1 Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

47 47 47

Language contributor checklist 7.1 1. Put language definition into a .js file . . . . . . . . . 7.2 2. Provide meta data . . . . . . . . . . . . . . . . . . . 7.3 3. Create a test fragment . . . . . . . . . . . . . . . . . 7.4 4. Write class reference . . . . . . . . . . . . . . . . . 7.5 5. Add yourself to AUTHORS.*.txt and CHANGES.md 7.6 6. Create a pull request . . . . . . . . . . . . . . . . . .

. . . . . .

49 49 49 50 50 50 50

Style contributor checklist 8.1 1. Put style definition into a .css file . . . . . . . . . . . 8.2 2. Provide meta data . . . . . . . . . . . . . . . . . . . 8.3 3. Add it to test page . . . . . . . . . . . . . . . . . . . 8.4 4. Add yourself to AUTHORS.*.txt and CHANGES.md 8.5 5. Create a pull request . . . . . . . . . . . . . . . . . .

. . . . .

51 51 51 51 51 51

VHDL (“vhdl”) . . . . . . . . . . . . . Parser3 (“parser3”) . . . . . . . . . . . LiveCode Server (“livecodeserver”) . . TeX (“tex”) . . . . . . . . . . . . . . . Haskell (“haskell”, “hs”) . . . . . . . . Erlang (“erlang”, “erl”) . . . . . . . . Elixir (“elixir”) . . . . . . . . . . . . . Rust (“rust”, “rs”) . . . . . . . . . . . Matlab (“matlab”) . . . . . . . . . . . Scilab (“scilab”, “sci”) . . . . . . . . . R (“r”) . . . . . . . . . . . . . . . . . OpenGL Shading Language (“glsl”) . . AppleScript (“applescript”, “osascript”) Vim Script (“vim”) . . . . . . . . . . . Brainfuck (“brainfuck”, “bf”) . . . . . Mizar (“mizar”) . . . . . . . . . . . . AutoHotkey (“autohotkey”) . . . . . . Monkey (“monkey”) . . . . . . . . . . FIX (“fix”) . . . . . . . . . . . . . . . Gherkin (“gherkin”) . . . . . . . . . . Nimrod (“nimrod”) . . . . . . . . . . . Swift (“swift”) . . . . . . . . . . . . .

Style guide 5.1 Overview . . . 5.2 Simplicity . . 5.3 Consistency . . 5.4 Portability . . 5.5 CSS file header 5.6 Contributing .

. . . . . .

Line numbers

. . . . . .

10 On requesting new languages

11 Indices and tables

iii

highlight.js Documentation, Release 8.1

Contents:

Contents

highlight.js Documentation, Release 8.1

Contents

CHAPTER 1

Library API

Highilght.js exports a few functions as methods of the hljs object.

1.1 highlight(name, value, ignore_illegals, continuation) Core highlighting function. Accepts a language name, or an alias, and a string with the code to highlight. The ignore_illegals parameter, when present and evaluates to a true value, forces highlighting to finish even in case of detecting illegal syntax for the language instead of throwing an exception. The continuation is an optional mode stack representing unfinished parsing. When present, the function will restart parsing from this state instead of initializing a new one. Returns an object with the following properties: • language: language name, same as the one passed into a function, returned for consistency with highlightAuto • relevance: integer value • value: HTML string with highlighting markup • top: top of the current mode stack

1.2 highlightAuto(value, languageSubset) Highlighting with language detection. Accepts a string with the code to highlight and an optional array of language names and aliases restricting detection to only those languages. The subset can also be set with configure, but the local parameter overrides the option if set. Returns an object with the following properties: • language: detected language • relevance: integer value • value: HTML string with highlighting markup • second_best: object with the same structure for second-best heuristically detected language, may be absent

1.3 fixMarkup(value) Post-processing of the highlighted markup. Currently consists of replacing indentation TAB characters and using <br> tags instead of new-line characters. Options are set globally with configure. 3

highlight.js Documentation, Release 8.1

Accepts a string with the highlighted markup.

1.4 highlightBlock(block) Applies highlighting to a DOM node containing code. This function is the one to use to apply highlighting dynamically after page load or within initialization code of third-party Javascript frameworks.

1.5 configure(options) Configures global options: • tabReplace: a string used to replace TAB characters in indentation. • useBR: a flag to generate <br> tags instead of new-line characters in the output, useful when code is marked up using a non-<pre> container. • classPrefix: a string prefix added before class names in the generated markup, used for backwards compatibility with stylesheets. • languages: an array of language names and aliases restricting auto detection to only these languages. Accepts an object representing options with the values to updated. Other options don’t change hljs.configure({ tabReplace: ’ classPrefix: ’’

’, // 4 spaces // don’t append class prefix // ... other options aren’t changed

}) hljs.initHighlighting();

1.6 initHighlighting() Applies highlighting to all <pre><code>..</code></pre> blocks on a page.

1.7 initHighlightingOnLoad() Attaches highlighting to the page load event.

1.8 registerLanguage(name, language) Adds new language to the library under the specified name. Used mostly internally. • name: a string with the name of the language being registered • language: a function that returns an object which represents the language definition. The function is passed the hljs object to be able to use common regular expressions defined within it.

Chapter 1. Library API

highlight.js Documentation, Release 8.1

1.9 listLanguages() Returns the languages names list.

1.10 getLanguage(name) Looks up a language by name or alias. Returns the language object if found, undefined otherwise.

1.9. listLanguages()

highlight.js Documentation, Release 8.1

Chapter 1. Library API

CHAPTER 2

Language definition guide

2.1 Highlighting overview Programming language code consists of parts with different rules of parsing: keywords like for or if don’t make sense inside strings, strings may contain backslash-escaped symbols like \" and comments usually don’t contain anything interesting except the end of the comment. In highlight.js such parts are called “modes”. Each mode consists of: • starting condition • ending condition • list of contained sub-modes • lexing rules and keywords • . . . exotic stuff like another language inside a language The parser’s work is to look for modes and their keywords. Upon finding it wraps them into the markup <span class="...">...</span> and puts the name of the mode (“string”, “comment”, “number”) or a keyword group name (“keyword”, “literal”, “built-in”) as the span’s class name.

2.2 General syntax A language definition is a JavaScript object describing the default parsing mode for the language. This default mode contain sub-modes which in turn contain other sub-modes effectively making the language definition a tree of modes. Here’s an example: { case_insensitive: true, // language is case-insensitive keywords: ’for if while’, contains: [ { className: ’string’, begin: ’"’, end: ’"’ }, { className: ’comment’, begin: ’/*’, end: ’*/’,

highlight.js Documentation, Release 8.1

contains: [ { className: ’doc’, begin: ’@\\w+’ } ] } ] }

Usually the default mode accounts for the majority of the code and describes all language keywords. A notable exception here is XML in which a default mode is just a user text that doesn’t contain any keywords, and most interesting parsing happens inside tags.

2.3 Keywords In the simple case language keywords are defined in a string, separated by space: { keywords: ’else for if while’ }

Some languages have different kinds of “keywords” that might not be called as such by the language spec but are very close to them from the point of view of a syntax highlighter. These are all sorts of “literals”, “built-ins”, “symbols” and such. To define such keyword groups the attribute keywords becomes an object each property of which defines its own group of keywords: { keywords: { keyword: ’else for if while’, literal: ’false true null’ } }

The group name becomes then a class name in a generated markup enabling different styling for different kinds of keywords. To detect keywords highlight.js breaks the processed chunk of code into separate words — a process called lexing. The “word” here is defined by the regexp [a-zA-Z][a-zA-Z0-9_]* that works for keywords in most languages. Different lexing rules can be defined by the lexemes attribute: { lexemes ’-[a-z]+’, keywords: ’-import -export’ }

2.4 Sub-modes Sub-modes are listed in the contains attribute: { keywords: ’...’, contains: [ hljs.QUOTE_STRING_MODE, hljs.C_LINE_COMMENT,

Chapter 2. Language definition guide

highlight.js Documentation, Release 8.1

{ ... custom mode definition ... } ] }

A mode can reference itself in the contains array by using a special keyword ’self‘. This is commonly used to define nested modes: { className: ’object’, begin: ’{’, end: ’}’, contains: [hljs.QUOTE_STRING_MODE, ’self’] }

2.5 Markup generation Modes usually generate actual highlighting markup — <span> elements with specific class names that are defined by the className attribute: { contains: [ { className: ’string’, // ... other attributes }, { className: ’number’, // ... } ] }

Names are not required to be unique, it’s quite common to have several definitions with the same name. For example, many languages have various syntaxes for strings, comments, etc. . . Sometimes modes are defined only to support specific parsing rules and aren’t needed in the final markup. A classic example is an escaping sequence inside strings allowing them to contain an ending quote. { className: ’string’, begin: ’"’, end: ’"’, contains: [{begin: ’\\\\.’}], }

For such modes className attribute should be omitted so they won’t generate excessive markup.

2.6 Mode attributes Other useful attributes are defined in the mode reference.

2.7 Relevance Highlight.js tries to automatically detect the language of a code fragment. The heuristics is essentially simple: it tries to highlight a fragment with all the language definitions and the one that yields most specific modes and keywords 2.5. Markup generation

highlight.js Documentation, Release 8.1

wins. The job of a language definition is to help this heuristics by hinting relative relevance (or irrelevance) of modes. This is best illustrated by example. Python has special kinds of strings defined by prefix letters before the quotes: r"...", u"...". If a code fragment contains such strings there is a good chance that it’s in Python. So these string modes are given high relevance: { className: ’string’, begin: ’r"’, end: ’"’, relevance: 10 }

On the other hand, conventional strings in plain single or double quotes aren’t specific to any language and it makes sense to bring their relevance to zero to lessen statistical noise: { className: ’string’, begin: ’"’, end: ’"’, relevance: 0 }

The default value for relevance is 1. When setting an explicit value it’s recommended to use either 10 or 0. Keywords also influence relevance. Each of them usually has a relevance of 1, but there are some unique names that aren’t likely to be found outside of their languages, even in the form of variable names. For example just having reinterpret_cast somewhere in the code is a good indicator that we’re looking at C++. It’s worth to set relevance of such keywords a bit higher. This is done with a pipe: { keywords: ’for if reinterpret_cast|10’ }

2.8 Illegal symbols Another way to improve language detection is to define illegal symbols for a mode. For example in Python first line of class definition (class MyClass(object):) cannot contain symbol “{” or a newline. Presence of these symbols clearly shows that the language is not Python and the parser can drop this attempt early. Illegal symbols are defined as a a single regular expression: { className: ’class’, illegal: ’[${]’ }

2.9 Pre-defined modes and regular expressions Many languages share common modes and regular expressions. Such expressions are defined in core highlight.js code at the end under “Common regexps” and “Common modes” titles. Use them when possible.

2.10 Contributing Follow the contributor checklist.

Chapter 2. Language definition guide

CHAPTER 3

Mode reference

3.1 Types Types of attributes values in this reference: identifier regexp boolean number object array

String suitable to be used as a Javascript variable and CSS class name (i.e. mostly /[A-Za-z0-9_]+/) String representing a Javascript regexp. Note that since itâ&#x20AC;&#x2122;s not a literal regexp all back-slashes should be repeated twice Javascript boolean: true or false Javascript number Javascript object: { ... } Javascript array: [ ... ]

3.2 Attributes 3.2.1 case_insensitive type: boolean Case insensitivity of language keywords and regexps. Used only on the top-level mode.

3.2.2 aliases type: array A list of additional names (besides the canonical one given by the filename) that can be used to identify a language in HTML classes and in a call to getLanguage.

3.2.3 className type: identifier The name of the mode. It is used as a class name in HTML markup. Multiple modes can have the same name. This is useful when a language has multiple variants of syntax for one thing like string in single or double quotes.

highlight.js Documentation, Release 8.1

3.2.4 begin type: regexp Regular expression starting a mode. For example a single quote for strings or two forward slashes for C-style comments. If absent, begin defaults to a regexp that matches anything, so the mode starts immediately.

3.2.5 end type: regexp Regular expression ending a mode. For example a single quote for strings or “$” (end of line) for one-line comments. It’s often the case that a beginning regular expression defines the entire mode and doesn’t need any special ending. For example a number can be defined with begin: "\\b\\d+" which spans all the digits. If absent, end defaults to a regexp that matches anything, so the mode ends immediately. Sometimes a mode can end not by itself but implicitly with its containing (parent) mode. This is achieved with endsWithParent attribute.

3.2.6 beginKeywords type: string Used instead of begin for modes starting with keywords to avoid needless repetition: { begin: ’\\b(extends|implements) ’, keywords: ’extends implements’ }

. . . becomes: { beginKeywords: ’extends implements’ }

Unlike the keywords attribute, this one allows only a simple list of space separated keywords. If you do need additional features of keywords or you just need more keywords for this mode you may include keywords along with beginKeywords.

3.2.7 endsWithParent type: boolean A flag showing that a mode ends when its parent ends. This is best demonstrated by example. In CSS syntax a selector has a set of rules contained within symbols “{” and “}”. Individual rules separated by ”;” but the last one in a set can omit the terminating semicolon: p { width: 100%; color: red }

This is when endsWithParent comes into play:

Chapter 3. Mode reference

highlight.js Documentation, Release 8.1

{ className: ’rules’, begin: ’{’, end: ’}’, contains: [ {className: ’rule’, /* ... */ end: ’;’, endsWithParent: true} ] }

3.2.8 lexemes type: regexp A regular expression that extracts individual lexemes from language text to find keywords among them. Default value is hljs.IDENT_RE which works for most languages.

3.2.9 keywords type: object Keyword definition comes in two forms: • ’for while if else weird_voodoo|10 ... optional relevance over a pipe

’ – a string of space-separated keywords with an

• {’keyword’: ’ ... ’, ’literal’: ’ ... ’} – an object whose keys are names of different kinds of keywords and values are keyword definition strings in the first form For detailed explanation see Language definition guide.

3.2.10 illegal type: regexp A regular expression that defines symbols illegal for the mode. When the parser finds a match for illegal expression it immediately drops parsing the whole language altogether.

3.2.11 excludeBegin, excludeEnd type: boolean Exclude beginning or ending lexemes out of mode’s generated markup. For example in CSS syntax a rule ends with a semicolon. However visually it’s better not to color it as the rule contents. Having excludeEnd: true forces a <span> element for the rule to close before the semicolon.

3.2.12 returnBegin type: boolean Returns just found beginning lexeme back into parser. This is used when beginning of a sub-mode is a complex expression that should not only be found within a parent mode but also parsed according to the rules of a sub-mode. Since the parser is effectively goes back it’s quite possible to create a infinite loop here so use with caution!

3.2. Attributes

highlight.js Documentation, Release 8.1

3.2.13 returnEnd type: boolean Returns just found ending lexeme back into parser. This is used for example to parse Javascript embedded into HTML. A Javascript block ends with the HTML closing tag </script> that cannot be parsed with Javascript rules. So it is returned back into its parent HTML mode that knows what to do with it. Since the parser is effectively goes back it’s quite possible to create a infinite loop here so use with caution!

3.2.14 contains type: array The list of sub-modes that can be found inside the mode. For detailed explanation see Language definition guide.

3.2.15 starts type: identifier The name of the mode that will start right after the current mode ends. The new mode won’t be contained within the current one. Currently this attribute is used to highlight Javascript and CSS contained within HTML. Tags <script> and <style> start sub-modes that use another language definition to parse their contents (see subLanguage).

3.2.16 variants type: array Modification to the main definitions of the mode, effectively expanding it into several similar modes each having all the attributes from the main definition augmented or overridden by the variants: { className: ’string’, contains: [hljs.BACKSLASH_ESCAPE], relevance: 0, variants: [ {begin: /"/, end: /"/}, {begin: /’/, end: /’/, relevance: 1} ] }

3.2.17 subLanguage type: identifier The name of another language used to parse the contents of the mode. When using this attribute there’s no point to define internal parsing rules like lexemes or keywords. Also it is recommended to skip className attribute since the sublanguage will wrap the text in its own <span class="language-name"> If the attribute is set to an empty string highlight.js will highlight the mode contents with language detection. Note that for this to work the language should be included in the package (obviously).

Chapter 3. Mode reference

highlight.js Documentation, Release 8.1

3.2.18 subLanguageMode type: identifier The only available value for this is ’continuous’. By default subLanguage highlights the contents of the mode as an isolated code snippet. In continuous mode every occurrence of the mode is treated as a continuation of the previous one and highlighted from the point where it was interrupted before. This is best illustrated by an example. The following snippet consists of HTML markup intermixed with some templating language: <link href="<% url ’style.css’ absolute %>" rel="stylesheet">

To highlight HTML markup outside templating tags the language can be defined like this: { subLanguage: ’xml’, subLanguageMode: ’continuous’, contains: [ ... templating tags ... ] }

The outside contents will be highlighted as ‘xml’ up to the first double quote. Then the templating tag will be highlighted according to the rules of the templating language. And after that ‘xml’ will restart from the previous parsing state — inside the value of a tag — and will correctly process the closing double quote and highlight the next HTML attribute.

3.2. Attributes

highlight.js Documentation, Release 8.1

Chapter 3. Mode reference

CHAPTER 4

CSS classes reference

This is a full list of available classes corresponding to languages’ syntactic structures. The parentheses after language name contain identifiers used as class names in <code> element.

4.1 Python (“python”, “py”, “gyp”) • keyword: keyword • built_in: built-in objects (None, False, True and Ellipsis) • number: number • string: string (of any type) • comment: comment • decorator: @-decorator for functions • function: function header “def some_name(...):” • class: class header “class SomeName(...):” • title: name of a function or a class inside a header • params: everything inside parentheses in a function’s or class’ header

4.2 Python profiler results (“profile”) • number: number • string: string • built_in: built-in function entry • filename: filename in an entry • summary: profiling summary • header: header of table of results • keyword: column header • function: function name in an entry (including parentheses) • title: actual name of a function in an entry (excluding parentheses)

highlight.js Documentation, Release 8.1

• prompt: interpreter prompt (>>> or ...)

4.3 Ruby (“ruby”, “rb”, “gemspec”, “podspec”, “thor”, “irb”) • keyword: keyword • string: string • subst: in-string substitution (#{...}) • comment: comment • yardoctag: YARD tag • function: function header “def some_name(...):” • class: class header “class SomeName(...):” • title: name of a function or a class inside a header • parent: name of a parent class • symbol: symbol • input: complete input line (interpreter) • output: complete output line (interpreter) • prompt: interpreter prompt (>>) • status: interpreter response (=>)

4.4 Haml (“haml”) • tag: any tag starting with “%” • title: tag’s name • attribute: tag’s attribute • keyword: tag’s attribute that is a keyword • string: attribute’s value that is a string • value: attribute’s value, shorthand id or class for tag • comment: comment • doctype: !!! declaration • bullet: line defined by variable

4.5 Perl (“perl”, “pl”) • keyword: keyword • comment: comment • number: number • string: string 18

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• regexp: regular expression • sub: subroutine header (from “sub” till “{”) • variable: variable starting with “$”, “%”, “@” • operator: operator • pod: plain old doc

4.6 PHP (“php”, “php3”, “php4”, “php5”, “php6”) • keyword: keyword • number: number • string: string (of any type) • comment: comment • phpdoc: phpdoc params in comments • variable: variable starting with “$” • preprocessor: preprocessor marks: “<?php” and ”?>”

4.7 Scala (“scala”) • keyword: keyword • number: number • string: string • comment: comment • annotation: annotation • javadoc: javadoc comment • javadoctag: @-tag in javadoc • class: class header • title: class name inside a header • params: everything in parentheses inside a class header • inheritance: keywords “extends” and “with” inside class header

4.8 Go (“go”, “golang”) • comment: comment • string: string constant • number: number • keyword: language keywords • constant: true false nil iota

4.6. PHP (“php”, “php3”, “php4”, “php5”, “php6”)

highlight.js Documentation, Release 8.1

• typename: built-in plain types (int, string etc.) • built_in: built-in functions

4.9 Gradle (“gradle”) • keyword: keyword • number: number • string: string and character • comment: comment • regexp: regular expression

4.10 HTML, XML (“xml”, “html”, “xhtml”, “rss”, “atom”, “xsl”, “plist”) • tag: any tag from “<” till “>” • attribute: tag’s attribute with or without value • value: attribute’s value • comment: comment • pi: processing instruction (<? ... ?>) • doctype: <!DOCTYPE ... > declaration • cdata: CDATA section

4.11 Lasso (“lasso”, “ls”, “lassoscript”) • preprocessor: delimiters and interpreter flags • shebang: Lasso 9 shell script header • comment: single- or multi-line comment • javadoc: doc comment • keyword: keyword • literal: keyword representing a value • built_in: built-in types and variables • number: number • string: string • variable: variable reference starting with “#” or “$” • tag: tag literal • attribute: named or rest parameter in method signature • subst: unary/binary/ternary operator symbols • class: type, trait, or method header 20

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• title: name following “define” inside a header

4.12 CSS (“css”) • tag: tag in selectors • id: #some_name in selectors • class: .some_name in selectors • at_rule: @-rule till first “{” or ”;” • attr_selector: attribute selector (square brackets in a[href^=http://]) • pseudo: pseudo classes and elements (:after, ::after etc.) • comment: comment • rules: everything from “{” till “}” • attribute: property name inside a rule • value: property value inside a rule, from ”:” till ”;” or till the end of rule block • number: number within a value • string: string within a value • hexcolor: hex color (#FFFFFF) within a value • function: CSS function within a value • important: ”!important” symbol

4.13 SCSS (“scss”) • tag: tag in selectors • id: #some_name in selectors • class: .some_name in selectors • at_rule: @-rule till first “{” or ”;” • attr_selector: attribute selector (square brackets in a[href^=http://]) • pseudo: pseudo classes and elements (:after, ::after etc.) • comment: comment • rules: everything from “{” till “}” • attribute: property name inside a rule • value: property value inside a rule, from ”:” till ”;” or till the end of rule block • number: number within a value • string: string within a value • hexcolor: hex color (#FFFFFF) within a value • function: CSS function within a value • important: ”!important” symbol 4.12. CSS (“css”)

highlight.js Documentation, Release 8.1

• variable: variable starting with “$” • preprocessor: keywords after @

4.14 Markdown (“markdown”, “md”, “mkdown”, “mkd”) • header: header • bullet: list bullet • emphasis: emphasis • strong: strong emphasis • blockquote: blockquote • code: code • horizontal_rule: horizontal rule • link_label: link label • link_url: link url • link_reference: link reference

4.15 AsciiDoc (“asciidoc”) • header: heading • bullet: list or labeled bullet • emphasis: emphasis • strong: strong emphasis • blockquote: blockquote • code: inline or block code • horizontal_rule: horizontal rule • link_label: link or image label • link_url: link or image url • comment: comment • attribute: document attribute, block attributes • label: admonition label

4.16 Django (“django”, “jinja”) • keyword: HTML tag in HTML, default tags and default filters in templates • tag: any tag from “<” till “>” • comment: comment • doctype: <!DOCTYPE ... > declaration 22

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• attribute: tag’s attribute with or without value • value: attribute’s value • template_tag: template tag {% .. %} • variable: template variable {{ .. }} • template_comment: template comment, both {# .. #} and {% comment %} • filter: filter from “|” till the next filter or the end of tag • argument: filter argument

4.17 Handlebars (“handlebars”, “html.handlebars”)

“hbs”,

“html.hbs”,

• expression: expression to be evaluated • variable: variable • begin:-block the beginning of a block • end:-block the ending of a block • string: string

4.18 JSON (“json”) • number: number • literal: “true”, “false” and “null” • string: string value • attribute: name of an object property • value: value of an object property

4.19 Mathematica (“mathematica”, “mma”) • keyword: keyword • number: number • comment: comment • string: string • list: a list { .. } - the basic Mma structure

4.20 JavaScript (“javascript”, “js”) • keyword: keyword • comment: comment

4.17. Handlebars (“handlebars”, “hbs”, “html.hbs”, “html.handlebars”)

highlight.js Documentation, Release 8.1

• number: number • literal: special literal: “true”, “false” and “null” • string: string • regexp: regular expression • function: header of a function • title: name of a function inside a header • params: parentheses and everything inside them in a function’s header • pi: ‘use strict’ processing instruction

4.21 TypeScript (“typescript”, “ts”) • keyword: keyword • comment: comment • number: number • literal: special literal: “true”, “false” and “null” • string: string • regexp: regular expression • function: header of a function • title: name of a function inside a header • params: parentheses and everything inside them in a function’s header • pi: ‘use strict’ processing instruction

4.22 CoffeeScript (“coffeescript”, “coffee”, “cson”, “iced”) • keyword: keyword • comment: comment • number: number • literal: special literal: “true”, “false” and “null” • built_in: built-in objects and functions (“window”, “console”, “require”, etc...) • string: string • subst: #{ ... } interpolation in double-quoted strings • regexp: regular expression • function: header of a function • class: header of a class • title: name of a function variable inside a header • params: parentheses and everything inside them in a function’s header • property: @-property within class and functions 24

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

4.23 ActionScript (“actionscript”, “as”) • comment: comment • string: string • number: number • keyword: keywords • literal: literal • reserved: reserved keyword • title: name of declaration (package, class or function) • preprocessor: preprocessor directive (import, include) • type: type of returned value (for functions) • package: package (named or not) • class: class/interface • function: function • param: params of function • rest_arg: rest argument of function

4.24 Haxe (“haxe”, “hx”) • comment: comment • string: string • number: number • keyword: keywords • literal: literal • reserved: reserved keyword • title: name of declaration (package, class or function) • preprocessor: preprocessor directive (if, else, elseif, error) • type: type of returned value (for functions) • package: package (named or not) • class: class/interface • function: function • param: params of function • rest_arg: rest argument of function

4.23. ActionScript (“actionscript”, “as”)

highlight.js Documentation, Release 8.1

4.25 VBScript (“vbscript”, “vbs”) • keyword: keyword • number: number • string: string • comment: comment • built_in: built-in function

4.26 VB.Net (“vbnet”, “vb”) • keyword: keyword • built_in: built-in types • literal: “true”, “false” and “nothing” • string: string • comment: comment • xmlDocTag: xmldoc tag (“’‘”’, “<!–”, “–>”, “<..>”) • preprocessor: preprocessor directive

4.27 Protocol Buffers (“protobuf”) • keyword: keyword • built_in: built-in types (e.g. int64, string) • string: string • number: number • literal: “true” and “false” • comment: comment • class: message, service or enum definition header • title: message, service or enum identifier • function: RPC call identifier

4.28 Cap’n Proto (“capnproto”, “capnp”) • shebang: message identifier • keyword: keyword • built_in: built-in types (e.g. Int64, Text) • string: string • number: number or field number (e.g. @N)

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• literal: “true” and “false” • comment: comment • class: message, interface or enum definition header • title: message, interface or enum identifier

4.29 Thrift (“thrift”) • keyword: keyword • built_in: built-in types (e.g. byte, i32) • string: string • number: number • literal: “true” and “false” • comment: comment • class: struct, enum, service or exception definition header • title: struct, enum, service or exception identifier • stl_container: instantiation of STL-like containers (“list<...>”)

4.30 HTTP (“http”) • request: first line of a request • status: first line of a response • attribute: header name • string: header value or query string in a request line • number: status code

4.31 Lua (“lua”) • keyword: keyword • number: number • string: string • comment: comment • built_in: built-in operator • function: header of a function • title: name of a function inside a header • params: everything inside parentheses in a function’s header • long_brackets: multiline string in [=[ .. ]=]

4.29. Thrift (“thrift”)

highlight.js Documentation, Release 8.1

4.32 Delphi (“delphi”) • keyword: keyword • comment: comment (of any type) • number: number • string: string • function: header of a function, procedure, constructor and destructor • title: name of a function, procedure, constructor or destructor inside a header • params: everything inside parentheses in a function’s header • class: class’ body from “= class” till “end;”

4.33 Oxygene (“oxygene”) • keyword: keyword • comment: comment (of any type) • string: string/char • function: method, destructor, procedure or function • title: name of a function (inside function) • params: everything inside parentheses in a function’s header • number: number • class: class’ body from “= class” till “end;”

4.34 Java (“java”, “jsp”) • keyword: keyword • number: number • string: string • comment: comment • annotaion: annotation • javadoc: javadoc comment • class: class header from “class” till “{“ • title: class or method name • params: everything in parentheses inside a class header • inheritance: keywords “extends” and “implements” inside class header

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

4.35 C++ (“cpp”, “c”, “h”, “c++”, “h++”) • keyword: keyword • number: number • string: string and character • comment: comment • preprocessor: preprocessor directive • stl_container: instantiation of STL containers (“vector<...>”)

4.36 Objective C (“objectivec”, “m”, “mm”, “objc”, “obj-c”) • keyword: keyword • built_in: Cocoa/Cocoa Touch constants and classes • number: number • string: string • comment: comment • preprocessor: preprocessor directive • class: interface/implementation, protocol and forward class declaration • title: title (id) of interface, implementation, protocol, class • variable: properties and struct accessors

4.37 Vala (“vala”) • keyword: keyword • number: number • string: string • comment: comment • class: class definitions • title: in class definition • constant: ALL_UPPER_CASE

4.38 C# (“cs”, “csharp”) • keyword: keyword • number: number • string: string • comment: comment

4.35. C++ (“cpp”, “c”, “h”, “c++”, “h++”)

highlight.js Documentation, Release 8.1

• xmlDocTag: xmldoc tag (“///”, “<!–”, “–>”, “<..>”) • title: title of namespace or class

4.39 F# (“fsharp”, “fs”) • keywords: keyword • number: number • string: string • comment: comment • class: any custom F# type • title: the name of a custom F# type • annotation: any attribute

4.40 OCaml (“ocaml”, “ml”) • keywords: keyword • number: number • string: string • comment: comment • class: any custom OCaml type • title: the name of a custom OCaml type • annotation: any attribute

4.41 D (“d”) • comment: comment • string: string constant • number: number • keyword: language keywords (including @attributes) • constant: true false null • built_in: built-in plain types (int, string etc.)

4.42 RenderMan RSL (“rsl”) • keyword: keyword • number: number • string: string (including @”..”)

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• comment: comment • preprocessor: preprocessor directive • shader: shader keywords • shading: shading keywords • built_in: built-in function

4.43 RenderMan RIB (“rib”) • keyword: keyword • number: number • string: string • comment: comment • commands: command

4.44 Maya Embedded Language (“mel”) • keyword: keyword • number: number • string: string • comment: comment • variable: variable

4.45 SQL (“sql”) • keyword: keyword (mostly SQL‘92, SQL‘99 and T-SQL) • literal: special literal: “true” and “false” • built_in: built-in type name • number: number • string: string (of any type: ”..”, ‘..’, ‘..‘) • comment: comment

4.46 Smalltalk (“smalltalk”, “st”) • keyword: keyword • number: number • string: string • comment: comment

4.43. RenderMan RIB (“rib”)

highlight.js Documentation, Release 8.1

• symbol: symbol • array: array • class: name of a class • char: char • localvars: block of local variables

4.47 Lisp (“lisp”) • keyword: keyword • number: number • string: string • comment: comment • variable: variable • literal: b, t and nil • list: non-quoted list • title: first symbol in a non-quoted list • body: remainder of the non-quoted list • quoted: quoted list, both “(quote .. )” and “’(..)”

4.48 Clojure (“clojure”, “clj”) • comment: comments and hints • string: string • number: number • collection: collections • attribute: :keyword • title: function name (built-in or user defined) • built_in: built-in function name

4.49 Ini (“ini”) • title: title of a section • value: value of a setting of any type • string: string • number: number • keyword: boolean value keyword

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

4.50 Apache (“apache”, “apacheconf”) • keyword: keyword • number: number • comment: comment • literal: On and Off • sqbracket: variables in rewrites “%{..}” • cbracket: options in rewrites “[..]” • tag: begin and end of a configuration section

4.51 Nginx (“nginx”, “nginxconf”) • title: directive title • string: string • number: number • comment: comment • built_in: built-in constant • variable: $-variable • regexp: regexp

4.52 Diff (“diff”, “patch”) • header: file header • chunk: chunk header within a file • addition: added lines • deletion: deleted lines • change: changed lines

4.53 DOS (“dos”, “bat”, “cmd”) • keyword: keyword • flow: batch control keyword • stream: DOS special files (“con”, “prn”, ...) • winutils: some commands (see dos.js specifically) • envvar: environment variables

4.50. Apache (“apache”, “apacheconf”)

highlight.js Documentation, Release 8.1

4.54 Bash (“bash”, “sh”, “zsh”) • keyword: keyword • string: string • number: number • comment: comment • literal: special literal: “true” and “false” • variable: variable • shebang: script interpreter header

4.55 Makefile (“makefile”, “mk”, “mak”) • keyword: keyword ”.PHONY” within the phony line • string: string • comment: comment • variable: $(..) variable • title: target title • constant: constant within the initial definition

4.56 CMake (“cmake”, “cmake.in”) • keyword: keyword • number: number • string: string • comment: comment • envvar: $-variable • operator: operator (LESS, STREQUAL, MATCHES, etc)

4.57 Nix (“nix”) • keyword: keyword • built_in: built-in constant • number: number • string: single and double quotes • subst: antiquote ${} • comment: comment • variable: function parameter name

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

4.58 NSIS (“nsis”) • symbol: directory constants • number: number • constant: definitions, language-strings, compiler commands • variable: $-variable • string: string • comment: comment • params: parameters • keyword: keywords • literal: keyword options

4.59 Axapta (“axapta”) • keyword: keyword • number: number • string: string • comment: comment • class: class header from “class” till “{“ • title: class name inside a header • params: everything in parentheses inside a class header • inheritance: keywords “extends” and “implements” inside class header • preprocessor: preprocessor directive

4.60 Oracle Rules Language (“ruleslanguage”) • comment: comment • string: string constant • number: number • keyword: language keywords • built_in: built-in functions • array: array stem

4.61 1C (“1c”) • keyword: keyword • number: number

4.58. NSIS (“nsis”)

highlight.js Documentation, Release 8.1

• date: date • string: string • comment: comment • function: header of function or procedure • title: function name inside a header • params: everything in parentheses inside a function header • preprocessor: preprocessor directive

4.62 x86 Assembly (“x86asm”) • keyword: instruction mnemonic • literal: register name • pseudo: assembler’s pseudo instruction • preprocessor: macro • built_in: assembler’s keyword • comment: comment • number: number • string: string • label: jump label • argument: macro’s argument

4.63 AVR assembler (“avrasm”) • keyword: keyword • built_in: pre-defined register • number: number • string: string • comment: comment • label: label • preprocessor: preprocessor directive • localvars: substitution in .macro

4.64 VHDL (“vhdl”) • keyword: keyword • number: number • string: string 36

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• comment: comment • literal: signal logical value • typename: typename • attribute: signal attribute

4.65 Parser3 (“parser3”) • keyword: keyword • number: number • comment: comment • variable: variable starting with “$” • preprocessor: preprocessor directive • title: user-defined name starting with “@”

4.66 LiveCode Server (“livecodeserver”) • variable: variable starting with “g”, “t”, “p”, “s”, “$_” • string: string • comment: comment • number: number • title: name of a command or a function • keyword: keyword • constant: constant • operator: operator • built_in: built_in functions and commands • function: header of a function • command: header of a command • preprocessor: preprocessor marks: “<?”, “<?rev”, “<?lc”, “<?livecode” and ”?>”

4.67 TeX (“tex”) • comment: comment • number: number • command: command • parameter: parameter • formula: formula • special: special symbol

4.65. Parser3 (“parser3”)

highlight.js Documentation, Release 8.1

4.68 Haskell (“haskell”, “hs”) • comment: comment • pragma: GHC pragma • preprocessor: CPP preprocessor directive • keyword: keyword • number: number • string: string • title: function or variable name • type: value, type or type class constructor name (i.e. capitalized) • container: (..., ...) or {...; ...} list in declaration or record • module: module declaration • import: import declaration • class: type class or instance declaration • typedef: type declaration (type, newtype, data) • default: default declaration • infix: infix declaration • foreign: FFI declaration • shebang: shebang line

4.69 Erlang (“erlang”, “erl”) • comment: comment • string: string • number: number • keyword: keyword • record_name: record access (#record_name) • title: name of declaration function • variable: variable (starts with capital letter or with _) • pp:.keywords module’s attribute (-attribute) • function_name: atom or atom:atom in case of function call

4.70 Elixir (“elixir”) • keyword: keyword • string: string • subst: in-string substitution (#{...})

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

• comment: comment • function: function header “def some_name(...):” • class: defmodule and defrecord headers • title: name of a function or a module inside a header • symbol: atom • constant: name of a module • number: number • variable: variable • regexp: regexp

4.71 Rust (“rust”, “rs”) • comment: comment • string: string • number: number • keyword: keyword • title: name of declaration • preprocessor: preprocessor directive

4.72 Matlab (“matlab”) • comment: comment • string: string • number: number • keyword: keyword • title: function name • function: function • param: params of function • matrix: matrix in [ .. ] • cell: cell in { .. }

4.73 Scilab (“scilab”, “sci”) • comment: comment • string: string • number: number • keyword: keyword

4.71. Rust (“rust”, “rs”)

highlight.js Documentation, Release 8.1

• title: function name • function: function • param: params of function • matrix: matrix in [ .. ]

4.74 R (“r”) • comment: comment • string: string constant • number: number • keyword: language keywords (function, if) plus “structural” functions (attach, require, setClass) • literal: special literal: TRUE, FALSE, NULL, NA, etc.

4.75 OpenGL Shading Language (“glsl”) • comment: comment • number: number • preprocessor: preprocessor directive • keyword: keyword • built_in: GLSL built-in functions and variables • literal: true false

4.76 AppleScript (“applescript”, “osascript”) • keyword: keyword • command: core AppleScript command • constant: AppleScript built in constant • type: AppleScript variable type (integer, etc.) • property: Applescript built in property (length, etc.) • number: number • string: string • comment: comment • title: name of a handler

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

4.77 Vim Script (“vim”) • keyword: keyword • built_in: built-in functions • string: string, comment • number: number • function: function header “function Foo(...)” • title: name of a function • params: everything inside parentheses in a function’s header • variable: vim variables with different visibilities “g:foo, b:bar”

4.78 Brainfuck (“brainfuck”, “bf”) • title: Brainfuck while loop command • literal: Brainfuck inc and dec commands • comment: comment • string: Brainfuck input and output commands

4.79 Mizar (“mizar”) • keyword: keyword • comment: comment

4.80 AutoHotkey (“autohotkey”) • keyword: keyword • literal: A (active window), true, false, NOT, AND, OR • built_in: built-in variables • string: string • comment: comment • number: number • var_expand: variable expansion (enclosed in percent sign) • label: label, hotkey label, hotstring label

4.77. Vim Script (“vim”)

highlight.js Documentation, Release 8.1

4.81 Monkey (“monkey”) • keyword: keyword • built_in: built-in functions, variables and types of variables • literal: True, False, Null, And, Or, Shl, Shr, Mod • string: string • comment: comment • number: number • function: header of a function, method and constructor • class: class header • title: name of an alias, class, interface, function or method inside a header • variable: self and super keywords • preprocessor: import and preprocessor • pi: Strict directive

4.82 FIX (“fix”) • attribute: attribute name • string: attribute value

4.83 Gherkin (“gherkin”) • keyword: keyword • number: number • comment: comment • string: string

4.84 Nimrod (“nimrod”) • decorator pragma • string string literal • type variable type • number numeric literal • comment comment

Chapter 4. CSS classes reference

highlight.js Documentation, Release 8.1

4.85 Swift (“swift”) • keyword: keyword • comment: comment • number: number • string: string • literal: special literal: “true”, “false” and “nil” • built_in: built-in Swift functions • func: header of a function • class: class, protocol, enum, struct, or extension declaration • title: name of a function or class (or protocol, etc) • generics: generic type of a function • params: parameters of a function • type: a type • preprocessor: @attributes

4.85. Swift (“swift”)

highlight.js Documentation, Release 8.1

Chapter 4. CSS classes reference

CHAPTER 5

Style guide

5.1 Overview Highlighted code is a single <code> element containing <span>‘s with pre-defined classes. Its appearance is controlled by a normal CSS file that can use all the features of CSS. There are however a couple of specific requirements for highlight.js styles: • Simplicity • Consistency • Portability

5.2 Simplicity Overall style of highlight.js is minimalist, usable and generally not very bright. It’s discouraged to use individual styling for small elements such as parentheses, commas, quotes etc. The ultimate goal of styling is to help people to actually read the code.

5.3 Consistency Highlight.js uses consistent class names across all the supported languages: strings are always “string”, comments are always “comment”, numbers are always “number”. This allows to define a style that will work for all languages, not just one. This means that language names in style definition should be avoided: /* wrong! */ .html .tag { font-weight: bold; } /* right, works for tags in HTML and XML */ .tag { font-weight: bold; }

There are also unique syntax elements that languages don’t share with each other: “javadoc” in Java, “attr_selector” in CSS, “doctype” in XML etc. The best way to style them is by “packing” them into a group of selectors for a single CSS group of rules:

highlight.js Documentation, Release 8.1

.javadoc, .decorator, .filter .argument, .localvars, .array, .attr_selector, .pi, .doctype { color: #88F; }

This pattern helps keeping the number of different style rules to a minimum. Itâ&#x20AC;&#x2122;s also easier to maintain: when a programmer adds definition of a new language itâ&#x20AC;&#x2122;s easier to stack its unique elements to existing groups instead of trying to define its style from scratch (something that programmers are known to be not very good at). The only case where you should include a language class name is when its commonly named element should not adhere to general rules. For example a class title serves in most languages as a title of a function or class definition and has a unique color. If we want it in, say, HTML to be black as the general text we should specify a language for this rule: .html .tag. .title { color: black; }

5.4 Portability CSS for syntax highlighting should not interfere with the main site styling. To achieve this all style rules are defined within pre element: pre .string { color: red; } pre .number { color: green; }

5.5 CSS file header A good idea is to include a comment at the top of your contributed CSS file that properly attributes your work: /* Mean-and-clean style (c) John Smith <email@domain.com> */

5.6 Contributing Follow the style contributor checklist.

Chapter 5. Style guide

CHAPTER 6

Building and testing

To actually run highlight.js it is necessary to build it for the environment where you’re going to run it: a browser, the node.js server, etc.

6.1 Building The build tool is written in Python, 3.x version. It also can use YUICompressor for the in-browser builds so make sure you have Java installed for that too. The tool is located in tools/build.py. A few useful examples: • Build for a browser using only common languages: python3 tools/build.py :common

• Build for node.js including all available languages: python3 tools/build.py -t node

• Build two specific languages for debugging, skipping compression in this case: python3 tools/build.py -n python ruby

The full option reference is available with the usual --help option. The build result will be in the build/ directory.

6.2 Testing Testing is done in a browser using the provided src/test.html file that contains snippets for all the supported languages. You can use browser builds with all or only some of the languages, with or without compression. The usual approach to debugging and testing a language is first building highlight.js with only the language you’re working on without compression (to have readable code in browser error messages). After this you have to build the entire package with all the languages and see if anything is broken. If your language breaks auto-detection it should be fixed by improving relevance, which is a black art in and of itself. When in doubt, please refer to the discussion group! Contribution:

highlight.js Documentation, Release 8.1

Chapter 6. Building and testing

CHAPTER 7

Language contributor checklist

7.1 1. Put language definition into a .js file The file defines a function accepting a reference to the library and returning a language object. The library parameter is useful to access common modes and regexps. You should not immediately call this function, this is done during the build process and details differ for different build targets. function(hljs) { return { keywords: ’foo bar’, contains: [ ..., hljs.NUMBER_MODE, ... ] } }

The name of the file is used as a short language identifier and should be usable as a class name in HTML and CSS.

7.2 2. Provide meta data At the top of the file there is a specially formatted comment with meta data processed by a build system. Meta data format is simply key-value pairs each occupying its own line: /* Language: Superlanguage Requires: java.js, sql.js Author: John Smith <email@domain.com> Contributors: Mike Johnson <...@...>, Matt Wilson <...@...> Description: Some cool language definition */

Language — the only required header giving a human-readable language name. Requires — a list of other language files required for this language to work. This make it possible to describe languages that extend definitions of other ones. Required files aren’t processed in any special way. The build system just makes sure that they will be in the final package in LANGUAGES object. The meaning of the other headers is pretty obvious.

highlight.js Documentation, Release 8.1

7.3 3. Create a test fragment The fragment should include various language features. This is used both as an example and a test case. It’s usually better to create a synthetic fragment instead of just take a snippet of an existing code because real-world code rarely contains all language features in one place. This fragment is also absolutely not required to actually work or make sense :-). Good example are C++ and HTML fragments in test.html. Then put the fragment into the test.html similar to other languages and test if it’s properly detected and doesn’t break detection of other languages.

7.4 4. Write class reference Class reference lives in the CSS classes reference.. Describe shortly names of all meaningful modes used in your language definition.

7.5 5. Add yourself to AUTHORS.*.txt and CHANGES.md If you’re a new contributor add yourself to the authors list. Feel free to use either English and/or Russian version. Also it will be good to update CHANGES.md.

7.6 6. Create a pull request Send your contribution as a pull request on GitHub.

Chapter 7. Language contributor checklist

CHAPTER 8

Style contributor checklist

8.1 1. Put style definition into a .css file Please refer to style guide to make it consistent with other styles.

8.2 2. Provide meta data Add some information about style to file header. There may be style name, original author and yours name and contacts. /* Mean-and-clean style (c) John Smith <email@domain.com> Ported by Jack Man */

8.3 3. Add it to test page Add your style to the top of src/test.html page, as for other styles.

8.4 4. Add yourself to AUTHORS.*.txt and CHANGES.md If youâ&#x20AC;&#x2122;re a new contributor add yourself to the authors list. Feel free to use either English and/or Russian version. Also it will be good to update CHANGES.md.

8.5 5. Create a pull request Send your contribution as a pull request on GitHub. Miscellaneous:

highlight.js Documentation, Release 8.1

Chapter 8. Style contributor checklist

CHAPTER 9

Line numbers

Highlight.js’ notable lack of line numbers support is not an oversight but a feature. Following is the explanation of this policy from the current project maintainer (hey guys!): One of the defining design principles for highlight.js from the start was simplicity. Not the simplicity of code (in fact, it’s quite complex) but the simplicity of usage and of the actual look of highlighted snippets on HTML pages. Many highlighters, in my opinion, are overdoing it with such things as separate colors for every single type of lexemes, striped backgrounds, fancy buttons around code blocks and — yes — line numbers. The more fancy stuff resides around the code the more it distracts a reader from understanding it. This is why it’s not a straightforward decision: this new feature will not just make highlight.js better, it might actually make it worse simply by making it look more bloated in blog posts around the Internet. This is why I’m asking people to show that it’s worth it. The only real use-case that ever was brought up in support of line numbers is referencing code from the descriptive text around it. On my own blog I was always solving this either with comments within the code itself or by breaking the larger snippets into smaller ones and describing each small part separately. I’m not saying that my solution is better. But I don’t see how line numbers are better either. And the only way to show that they are better is to set up some usability research on the subject. I doubt anyone would bother to do it. Then there’s maintenance. So far the core code of highlight.js is maintained by only one person — yours truly. Inclusion of any new code in highlight.js means that from that moment I will have to fix bugs in it, improve it further, make it work together with the rest of the code, defend its design. And I don’t want to do all this for the feature that I consider “evil” and probably will never use myself. This position is subject to discuss. Also it doesn’t stop anyone from forking the code and maintaining line-numbers implementation separately.

highlight.js Documentation, Release 8.1

Chapter 9. Line numbers

CHAPTER 10

On requesting new languages

This is a general answer to requests for adding new languages that appear from time to time in the highlight.js issue tracker and discussion group. Highlight.js doesn’t have a fundamental plan for implementing languages, instead the project works by accepting language definitions from interested contributors. There are also no rules at the moment forbidding any languages from being added to the library, no matter how obscure or weird. This means that there’s no point in requesting a new language without providing an implementation for it. If you want to see a particular language included in highlight.js but cannot implement it, the best way to make it happen is to get another developer interested in doing so. Here’s our Language definition guide. Links: • Code: https://github.com/isagalaev/highlight.js • Discussion: http://groups.google.com/group/highlightjs • Bug tracking: https://github.com/isagalaev/highlight.js/issues

highlight.js Documentation, Release 8.1

Chapter 10. On requesting new languages

CHAPTER 11

Indices and tables

• genindex • modindex • search