docs/api.rst
Highlight.js exports a few functions as methods of the hljs object.
.. _newerapi:
::
highlight(code, {language, ignoreIllegals})
Core highlighting function. Accepts the code to highlight (string) and a list of options (object).
The language parameter must be present and specify the language name or alias
of the grammar to be used for highlighting.
The ignoreIllegals is an optional parameter that when true forces highlighting
to finish even in case of detecting illegal syntax for the
language instead of throwing an exception.
Returns an object with the following properties:
language: language name, same as the name passed in languageName, returned for consistency with highlightAutorelevance: integer value representing the relevance scorevalue: HTML string with highlighting markuptop: top of the current mode stackillegal: boolean representing whether any illegal matches were foundcode: the original raw code::
highlightAuto(code, 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 languagerelevance: integer value representing the relevance scorevalue: HTML string with highlighting markupsecondBest: object with the same structure for second-best heuristically detected language (may be absent)::
highlightElement(element)
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.
The function uses language detection by default but you can specify the language
in the class attribute of the DOM node. See the :doc:scopes reference </css-classes-reference> for all available language names and scopes.
Applies highlighting to all elements on a page matching the configured cssSelector.
The default cssSelector value is 'pre code', which highlights all code blocks.
This can be called before or after the page's onload event has fired.
Returns a new instance of the highlighter with default configuration.
::
configure(options)
Configures global options:
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.languageDetectRe: a regex to configure how CSS class names map to language (allows class names like say color-as-php vs the default of language-php, etc.)noHighlightRe: a regex to configure which CSS classes are to be skipped completely.cssSelector: a CSS selector to configure which elements are affected by hljs.highlightAll. Defaults to 'pre code'.ignoreUnescapedHTML: do not log warnings to console about unescaped HTML in code blocksthrowUnescapedHTML: throw a HTMLInjectionError when highlightElement is asked to highlight content that includes unescaped HTMLAccepts an object representing options with the values to updated. Other options don't change ::
hljs.configure({
noHighlightRe: /^do-not-highlightme$/i,
languageDetectRe: /\bgrammar-([\w-]+)\b/i, // for grammar-swift style CSS naming
classPrefix: '' // don't append class prefix
// … other options aren't changed
});
::
registerLanguage(languageName, languageDefinition)
Adds new language to the library under the specified name. Used mostly internally.
languageName: a string with the name of the language being registeredlanguageDefinition: 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.::
unregisterLanguage(languageName)
Removes a language and its aliases from the library. Used mostly internally.
languageName: a string with the name of the language being removed.::
registerAliases(alias|aliases, {languageName})
Adds new language alias or aliases to the library for the specified language name defined under languageName key.
alias|aliases: a string or array with the name of alias being registeredlanguageName: the language name as specified by registerLanguage.Returns the languages names list.
.. _getLanguage:
::
getLanguage(name)
Looks up a language by name or alias.
Returns the language object if found, undefined otherwise.
::
versionString
Returns the full Highlight.js version as a string, ie: "11.0.1".
::
safeMode()
Enables safe mode. This is the default mode, providing the most reliable experience for production usage.
::
debugMode()
Enables debug/development mode.
.. warning::
This mode purposely makes Highlight.js more fragile! It should only be used for testing and local development (of languages or the library itself).
For example, if a new version suddenly had a serious bug (or breaking change) that affected only a single language:
::
addPlugin(plugin)
Add a plugin to this instance of Highlight.js. See the :doc:plugin api </plugin-api> for additional plugin information.
::
removePlugin(plugin)
Remove the specified plugin from this instance. plugin must be exactly the same object that was passed to addPlugin.
highlight ^^^^^^^^^
.. deprecated:: 10.7 This will be removed entirely in v12.
::
highlight(languageName, code)
Please see the :ref:newer API<newerapi> shown above.
highlightBlock ^^^^^^^^^^^^^^
.. deprecated:: 11.0 Please use highlightElement() instead.
initHighlighting ^^^^^^^^^^^^^^^^
.. deprecated:: 10.6 Please use highlightAll() instead.
initHighlightingOnLoad ^^^^^^^^^^^^^^^^^^^^^^
.. deprecated:: 10.6 Please use highlightAll() instead.