enh(parser) new highlightAll() API (#2962)

Added new `highlightAll()` API which deprecates both:

- `initHighlighting()`
- `initHighlightingOnLoad()`

The new function can be called at any time and will "just work".

- If called after DOM has loaded, it will immediately highlight.
- If called before, it will wait until the DOM finishes loading, then
highlight.

CHANGES.md

@@ -18,11 +18,20 @@ Grammar changes:
 
 Parser:
 
+- new simpler `highlightAll()` API (#2962) [Josh Goebel][]
+  - this should be a drop-in replacement for both `initHighlighting()` and `initHighlightingOnLoad()`
+  - note: it does not prevent itself from being called multiple times (as the previous API did)
 - `beginKeyword` no longer bestows double relevance (#2953) [Josh Goebel][]
 - allow `keywords` to be an array of strings [Josh Goebel][]
 - add `modes.MATCH_NOTHING_RE` that will never match
-  - This can be used with `end` to hold a mode open (it must then be ended with
-    `endsParent` in one of it's children modes) [Josh Goebel][]
+  - This can be used with `end` to hold a mode open (it must then be ended with `endsParent` in one of it's children modes) [Josh Goebel][]
+
+Deprecations:
+
+- `initHighlighting()` and `initHighlightingOnLoad()` deprecated.
+  - Please use the new `highlightAll()` API instead.
+  - Deprecated as of 10.6.
+  - These will both be aliases to `highlightAll` in v11.
 
 [Michael Newton]: https://github.com/miken32
 [Steven Van Impe]: https://github.com/svanimpe/

README.md

@@ -49,7 +49,7 @@ library along with one of the styles and calling [`initHighlightingOnLoad`][1]:
 ```html
 <link rel="stylesheet" href="/path/to/styles/default.css">
 <script src="/path/to/highlight.min.js"></script>
-<script>hljs.initHighlightingOnLoad();</script>
+<script>hljs.highlightAll();</script>
 ```
 
 This will find and highlight code inside of `<pre><code>` tags; it tries
@@ -93,7 +93,7 @@ When you need a bit more control over the initialization of
 highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
 functions. This allows you to better control *what* to highlight and *when*.
 
-Here’s the equivalent of calling [`initHighlightingOnLoad`][1] using
+Here’s the equivalent of calling [`highlightAll`][1] using
 only vanilla JS:
 
 ```js
@@ -359,7 +359,7 @@ Further in-depth documentation for the API and other topics is at
 
 Authors and contributors are listed in the [AUTHORS.txt][8] file.
 
-[1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
+[1]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightall
 [2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
 [3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
 [4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options

README.ru.md

@@ -13,7 +13,7 @@ Highlight.js — это инструмент для подсветки синт
 ```html
 <link rel="stylesheet" href="/path/to/styles/default.css">
 <script src="/path/to/highlight.min.js"></script>
-<script>hljs.initHighlightingOnLoad();</script>
+<script>hljs.highlightAll();</script>
 ```
 
 Библиотека найдёт и раскрасит код внутри тегов `<pre><code>`, попытавшись

demo/demo.js

@@ -1,5 +1,5 @@
 hljs.debugMode();
-hljs.initHighlightingOnLoad();
+hljs.highlightAll();
 
 document.querySelectorAll(".categories > li").forEach((category) => {
   category.addEventListener("click", (event) => {

docs/api.rst

@@ -91,15 +91,26 @@ Accepts an object representing options with the values to updated. Other options
   hljs.initHighlighting();
 
 
-``initHighlighting()``
+``highlightAll()``
+------------------
+
+Applies highlighting to all ``<pre><code>...</code></pre>`` blocks on a page.
+This can be called before or after the page's ``onload`` event has fired.
+
+
+``initHighlighting()`` (deprecated as of 10.6)
 ----------------------
 
+*Deprecated:* Please use ``highlightAll()`` instead.
+
 Applies highlighting to all ``<pre><code>...</code></pre>`` blocks on a page.
 
 
-``initHighlightingOnLoad()``
+``initHighlightingOnLoad()`` (deprecated as of 10.6)
 ----------------------------
 
+*Deprecated:* Please use ``highlightAll()`` instead.
+
 Attaches highlighting to the page load event.
 
 

src/highlight.js

@@ -741,18 +741,47 @@ const HLJS = function(hljs) {
    *
    * @type {Function & {called?: boolean}}
    */
+  // TODO: remove v12, deprecated
   const initHighlighting = () => {
     if (initHighlighting.called) return;
     initHighlighting.called = true;
 
+    logger.deprecated("10.6.0", "initHighlighting() is deprecated.  Use highlightAll() instead.");
+
     const blocks = document.querySelectorAll('pre code');
     blocks.forEach(highlightBlock);
   };
 
   // Higlights all when DOMContentLoaded fires
+  // TODO: remove v12, deprecated
   function initHighlightingOnLoad() {
-    // @ts-ignore
-    window.addEventListener('DOMContentLoaded', initHighlighting, false);
+    logger.deprecated("10.6.0", "initHighlightingOnLoad() is deprecated.  Use highlightAll() instead.");
+    wantsHighlight = true;
+  }
+
+  let wantsHighlight = false;
+  let domLoaded = false;
+
+  /**
+   * auto-highlights all pre>code elements on the page
+   */
+  function highlightAll() {
+    // if we are called too early in the loading process
+    if (!domLoaded) { wantsHighlight = true; return; }
+
+    const blocks = document.querySelectorAll('pre code');
+    blocks.forEach(highlightBlock);
+  }
+
+  function boot() {
+    domLoaded = true;
+    // if a highlight was requested before DOM was loaded, do now
+    if (wantsHighlight) highlightAll();
+  }
+
+  // make sure we are in the browser environment
+  if (typeof window !== 'undefined' && window.addEventListener) {
+    window.addEventListener('DOMContentLoaded', boot, false);
   }
 
   /**
@@ -880,6 +909,7 @@ const HLJS = function(hljs) {
   Object.assign(hljs, {
     highlight,
     highlightAuto,
+    highlightAll,
     fixMarkup: deprecateFixMarkup,
     highlightBlock,
     configure,

test/special/index.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const hljs     = require('../../build');
+hljs.debugMode(); // tests run in debug mode so errors are raised
+
 const { JSDOM } = require('jsdom');
 const { readFile } = require('fs').promises;
 const utility  = require('../utility');
@@ -19,12 +21,13 @@ describe('special cases tests', () => {
 
     // Setup hljs environment
     hljs.configure({ tabReplace: '    ' });
-    hljs.initHighlighting();
+    let blocks = document.querySelectorAll('pre code');
+    blocks.forEach(hljs.highlightBlock);
 
     // Setup hljs for non-`<pre><code>` tests
     hljs.configure({ useBR: true });
 
-    let blocks = document.querySelectorAll('.code');
+    blocks = document.querySelectorAll('.code');
     blocks.forEach(hljs.highlightBlock);
   });
 

types/index.d.ts

@@ -22,6 +22,7 @@ interface PublicApi {
     configure: (options: Partial<HLJSOptions>) => void
     initHighlighting: () => void
     initHighlightingOnLoad: () => void
+    highlightAll: () => void
     registerLanguage: (languageName: string, language: LanguageFn) => void
     listLanguages: () => string[]
     registerAliases: (aliasList: string | string[], { languageName } : {languageName: string}) => void