feat: Update to highlight.js v11

Author: MurhafSousli

CHANGELOG.md

@@ -1,9 +1,22 @@
 # Changelog
 
+## 5.0.0
+
+- Upgrade usage to highlight.js v11, you can find the breaking changes from the official page [here](https://highlightjs.readthedocs.io/en/latest/upgrade-11.html).
+- feat: Add the missing functions from v11 in `HighlightJS` service.
+- Remove deprecated function in v11, such as `initHighlighting()`, `highlightBlock()`, `fixMarkup()` from `HighlightJS` service.
+
+### Breaking changes
+
+- refactor: `(highlighted)` output has been updated to highlight.js v11, the result object has a new interface `HighlightAutoResult`.
+- refactor: `HighlightJS.configure(config)` has been updated the config interface to highlight.js v11.
+
 ## 4.1.4
 
 - Upgrade to Angular 12
-- Set peer dependency of hljs to v10
+- Set peer dependency of highlight.js to v10
+
+ > The library is still compatible with the new version of highlight.js v11 but the highlighting function will be deprecated in their next release
 
 ## 4.1.3
 

package-lock.json

@@ -47,7 +47,7 @@
     "@angular/platform-browser": "~12.0.2",
     "@angular/platform-browser-dynamic": "~12.0.2",
     "@angular/router": "~12.0.2",
-    "highlight.js": "^10.7.2",
+    "highlight.js": "^11.2.0",
     "highlightjs-line-numbers.js": "^2.8.0",
     "ngx-highlightjs": "^4.1.4",
     "ngx-scrollbar": "^7.5.6",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-highlightjs",
-  "version": "4.1.4",
+  "version": "5.0.0",
   "description": "Instant code highlighting, auto-detect language, super easy to use.",
   "homepage": "http://github.com/murhafsousli/ngx-highlightjs",
   "author": {
@@ -25,13 +25,13 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "highlight.js": "^10.0.0",
+    "highlight.js": ">=11.0.0",
     "highlightjs-line-numbers.js": "^2.8.0",
     "tslib": "^2.0.0"
   },
   "peerDependencies": {
-    "@angular/common": ">=8.0.0",
-    "@angular/core": ">=8.0.0",
+    "@angular/common": ">=12.0.0",
+    "@angular/core": ">=12.0.0",
     "rxjs": ">=6.0.0"
   }
 }

projects/ngx-highlightjs/package.json

@@ -1,41 +1,42 @@
 import { InjectionToken } from '@angular/core';
 
+/**
+ * Full documentation is available here https://highlightjs.readthedocs.io/en/latest/api.html
+ */
+
 export interface HighlightLibrary {
 
   /**
-   * Core highlighting function.
-   * @param name Accepts a language name, or an alias
-   * @param value A string with the code to highlight.
-   * @param ignore_illegals 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.
-   * @param continuation An optional mode stack representing unfinished parsing.
-   * When present, the function will restart parsing from this state instead of initializing a new one
+   * Core highlighting function. Accepts the code to highlight (string) and a list of options (object)
+   * @param code Accepts the code to highlight
+   * @param language must be present and specify the language name or alias of the grammar to be used for highlighting
+   * @param ignoreIllegals (optional) when set to true it forces highlighting to finish even in case of detecting illegal syntax for the language instead of throwing an exception.
    */
-  highlight(name: string, value: string, ignore_illegals: boolean, continuation?: any): HighlightResult;
+  highlight(code: string, { language, ignoreIllegals }: { language: string, ignoreIllegals: boolean }): HighlightResult;
 
   /**
    * Highlighting with language detection.
    * @param value Accepts a string with the code to highlight
    * @param languageSubset 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.
    */
-  highlightAuto(value: string, languageSubset: string[]): HighlightResult;
+  highlightAuto(value: string, languageSubset: string[]): HighlightAutoResult;
 
   /**
-   * 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.
-   * @param value Accepts a string with the highlighted markup
+   * 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 scopes reference for all available language names and scopes.
+   * @param element Element to highlight
    */
-  fixMarkup(value: string): string;
+  highlightElement(element: HTMLElement): void;
 
   /**
-   * Applies highlighting to a DOM node containing code.
-   * The function uses language detection by default but you can specify the language in the class attribute of the DOM node.
-   * See the class reference for all available language names and aliases.
-   * @param block The element to apply highlight on.
+   * 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.
    */
-  highlightBlock(block: HTMLElement): void;
+  highlightAll(): void;
 
   /**
    * Configures global options:
@@ -44,17 +45,25 @@ export interface HighlightLibrary {
   configure(config: HighlightConfig): void;
 
   /**
-   * Applies highlighting to all <pre><code>..</code></pre> blocks on a page.
+   * Adds new language to the library under the specified name. Used mostly internally.
+   * @param languageName A string with the name of the language being registered
+   * @param 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.
    */
-  initHighlighting(): void;
+  registerLanguage(languageName: string, languageDefinition: () => any): void;
 
   /**
-   * Adds new language to the library under the specified name. Used mostly internally.
-   * @param name A string with the name of the language being registered
-   * @param 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.
+   * Removes a language and its aliases from the library. Used mostly internall
+   * @param languageName: a string with the name of the language being removed.
+   */
+  unregisterLanguage(languageName: string): void;
+
+  /**
+   * Adds new language alias or aliases to the library for the specified language name defined under languageName key.
+   * @param alias: A string or array with the name of alias being registered
+   * @param languageName: the language name as specified by registerLanguage.
    */
-  registerLanguage(name: string, language: () => any): void;
+  registerAliases(alias: string | string[], { languageName }: { languageName: string }): void;
 
   /**
    * @return The languages names list.
@@ -68,6 +77,16 @@ export interface HighlightLibrary {
    */
   getLanguage(name: string): any;
 
+  /**
+   * Enables safe mode. This is the default mode, providing the most reliable experience for production usage.
+   */
+  safeMode(): void;
+
+  /**
+   * Enables debug/development mode.
+   */
+  debugMode(): void;
+
   /**
    * Add line numbers to code element
    * @param el Code element
@@ -76,21 +95,31 @@ export interface HighlightLibrary {
 }
 
 export interface HighlightConfig {
-  /** tabReplace: a string used to replace TAB characters in indentation. */
-  tabReplace?: string;
-  /** 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. */
-  useBR?: boolean;
   /** classPrefix: a string prefix added before class names in the generated markup, used for backwards compatibility with stylesheets. */
   classPrefix?: string;
   /** languages: an array of language names and aliases restricting auto detection to only these languages. */
   languages?: string[];
+  /** 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.) */
+  languageDetectRe: string;
+  /** noHighlightRe: a regex to configure which CSS classes are to be skipped completely. */
+  noHighlightRe: string;
+  /** a CSS selector to configure which elements are affected by hljs.highlightAll. Defaults to 'pre code'. */
+  cssSelector: string;
 }
 
 export interface HighlightResult {
   language?: string;
-  second_best?: any;
-  top?: any;
-  value?: string;
+  value?: string | undefined;
+  relevance?: number;
+  top: any;
+  code: string;
+  illegal: boolean;
+}
+
+export interface HighlightAutoResult {
+  language?: string;
+  secondBest?: any;
+  value?: string | undefined;
   relevance?: number;
 }