Core API ======== Highlight.js exports a few functions as methods of the ``hljs`` object. .. _newerapi: highlight --------- :: 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 ``highlightAuto`` * ``relevance``: integer value representing the relevance score * ``value``: HTML string with highlighting markup * ``top``: top of the current mode stack * ``illegal``: boolean representing whether any illegal matches were found * ``code``: the original raw code highlightAuto ------------- :: 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 language * ``relevance``: integer value representing the relevance score * ``value``: HTML string with highlighting markup * ``secondBest``: object with the same structure for second-best heuristically detected language (may be absent) highlightElement ---------------- :: 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 ` for all available language names and scopes. highlightAll ------------ 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. newInstance ----------- Returns a new instance of the highlighter with default configuration. configure --------- :: 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 blocks * ``throwUnescapedHTML``: throw a ``HTMLInjectionError`` when ``highlightElement`` is asked to highlight content that includes unescaped HTML Accepts 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 ---------------- :: 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 registered * ``languageDefinition``: 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 ------------------ :: 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 --------------- :: 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 registered * ``languageName``: the language name as specified by ``registerLanguage``. listLanguages ------------- Returns the languages names list. .. _getLanguage: getLanguage ----------- :: getLanguage(name) Looks up a language by name or alias. Returns the language object if found, ``undefined`` otherwise. versionString ------------- :: versionString Returns the full Highlight.js version as a string, ie: ``"11.0.1"``. safeMode -------- :: safeMode() Enables safe mode. This is the default mode, providing the most reliable experience for production usage. debugMode --------- :: 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: * **In Safe Mode** all other languages would continue to highlight just fine. The broken language would appear as a code block, but without any highlighting (as if it were plaintext). * **In Debug Mode** all highlighting would stop and a JavaScript error would be thrown. addPlugin --------- :: addPlugin(plugin) Add a plugin to this instance of Highlight.js. See the :doc:`plugin api ` for additional plugin information. removePlugin --------- :: removePlugin(plugin) Remove the specified plugin from this instance. ``plugin`` must be exactly the same object that was passed to ``addPlugin``. Deprecated API -------------- highlight ^^^^^^^^^ .. deprecated:: 10.7 This will be removed entirely in v12. :: highlight(languageName, code) Please see the :ref:`newer API` 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.