From e86ede2917ce0ca3386f1b29445c1aa205ab3a95 Mon Sep 17 00:00:00 2001 From: Josh Goebel Date: Thu, 14 Jan 2021 12:12:07 -0500 Subject: [PATCH 1/8] add new highlightAll --- src/highlight.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/highlight.js b/src/highlight.js index e0406d91eb..6de1bd8120 100644 --- a/src/highlight.js +++ b/src/highlight.js @@ -753,6 +753,25 @@ const HLJS = function(hljs) { window.addEventListener('DOMContentLoaded', initHighlighting, false); } + let wantsHighlight = false; + let domLoaded = false; + + 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 required before DOM was loaded, do now + if (wantsHighlight) highlightAll(); + } + + window.addEventListener('DOMContentLoaded', boot, false); + /** * Register a language grammar module * @@ -878,6 +897,7 @@ const HLJS = function(hljs) { Object.assign(hljs, { highlight, highlightAuto, + highlightAll, fixMarkup: deprecateFixMarkup, highlightBlock, configure, From e110cc1b21adb78bd9245234e1f91994fd8d2174 Mon Sep 17 00:00:00 2001 From: Josh Goebel Date: Thu, 14 Jan 2021 12:17:53 -0500 Subject: [PATCH 2/8] simplify --- src/highlight.js | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/highlight.js b/src/highlight.js index 6de1bd8120..f2a9ade70a 100644 --- a/src/highlight.js +++ b/src/highlight.js @@ -739,6 +739,7 @@ const HLJS = function(hljs) { * * @type {Function & {called?: boolean}} */ + // TODO: remove v12, deprecated const initHighlighting = () => { if (initHighlighting.called) return; initHighlighting.called = true; @@ -748,9 +749,9 @@ const HLJS = function(hljs) { }; // Higlights all when DOMContentLoaded fires + // TODO: remove v12, deprecated function initHighlightingOnLoad() { - // @ts-ignore - window.addEventListener('DOMContentLoaded', initHighlighting, false); + wantsHighlight = true; } let wantsHighlight = false; @@ -766,7 +767,7 @@ const HLJS = function(hljs) { function boot() { domLoaded = true; - // if a highlight was required before DOM was loaded, do now + // if a highlight was requested before DOM was loaded, do now if (wantsHighlight) highlightAll(); } From ff1cb2116cdbfb9ea5c8c06caa07d02d5f73bfdc Mon Sep 17 00:00:00 2001 From: Josh Goebel Date: Thu, 14 Jan 2021 12:28:29 -0500 Subject: [PATCH 3/8] update docs --- README.md | 6 +++--- README.ru.md | 2 +- demo/demo.js | 2 +- docs/api.rst | 15 +++++++++++++-- src/highlight.js | 3 +++ 5 files changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ee80e8e0f1..f58fbbade4 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ library along with one of the styles and calling [`initHighlightingOnLoad`][1]: ```html - + ``` This will find and highlight code inside of `
` 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
diff --git a/README.ru.md b/README.ru.md
index 26df3e34c9..5d82efd62a 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -13,7 +13,7 @@ Highlight.js — это инструмент для подсветки синт
 ```html
 
 
-
+
 ```
 
 Библиотека найдёт и раскрасит код внутри тегов `
`, попытавшись
diff --git a/demo/demo.js b/demo/demo.js
index f431408a13..079080e67a 100644
--- a/demo/demo.js
+++ b/demo/demo.js
@@ -1,5 +1,5 @@
 hljs.debugMode();
-hljs.initHighlightingOnLoad();
+hljs.highlightAll();
 
 document.querySelectorAll(".categories > li").forEach((category) => {
   category.addEventListener("click", (event) => {
diff --git a/docs/api.rst b/docs/api.rst
index 877f2c0bda..237c6eb1b9 100644
--- a/docs/api.rst
+++ b/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 ``
...
`` 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 ``
...
`` blocks on a page.
 
 
-``initHighlightingOnLoad()``
+``initHighlightingOnLoad()`` (deprecated as of 10.6)
 ----------------------------
 
+*Deprecated:* Please use ``highlightAll()`` instead.
+
 Attaches highlighting to the page load event.
 
 
diff --git a/src/highlight.js b/src/highlight.js
index f2a9ade70a..ed4eaf0388 100644
--- a/src/highlight.js
+++ b/src/highlight.js
@@ -757,6 +757,9 @@ const HLJS = function(hljs) {
   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; }

From 1473a29b161782ae5a4c2fcaae9c3de920aa99bf Mon Sep 17 00:00:00 2001
From: Josh Goebel 
Date: Thu, 14 Jan 2021 12:37:38 -0500
Subject: [PATCH 4/8] update types

---
 types/index.d.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/types/index.d.ts b/types/index.d.ts
index 5275cdfd58..825ad72301 100644
--- a/types/index.d.ts
+++ b/types/index.d.ts
@@ -22,6 +22,7 @@ interface PublicApi {
     configure: (options: Partial) => void
     initHighlighting: () => void
     initHighlightingOnLoad: () => void
+    highlightAll: () => void
     registerLanguage: (languageName: string, language: LanguageFn) => void
     listLanguages: () => string[]
     registerAliases: (aliasList: string | string[], { languageName } : {languageName: string}) => void

From e99216ec051d2f806acff5f98816225226820bab Mon Sep 17 00:00:00 2001
From: Josh Goebel 
Date: Thu, 14 Jan 2021 12:42:15 -0500
Subject: [PATCH 5/8] add deprecation warnings

---
 src/highlight.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/highlight.js b/src/highlight.js
index ed4eaf0388..e4b6334de4 100644
--- a/src/highlight.js
+++ b/src/highlight.js
@@ -744,6 +744,8 @@ const HLJS = function(hljs) {
     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);
   };
@@ -751,6 +753,7 @@ const HLJS = function(hljs) {
   // Higlights all when DOMContentLoaded fires
   // TODO: remove v12, deprecated
   function initHighlightingOnLoad() {
+    logger.deprecated("10.6.0", "initHighlightingOnLoad() is deprecated.  Use highlightAll() instead.");
     wantsHighlight = true;
   }
 

From 97cb5abddde3c23c216de00d7c8725018f883f67 Mon Sep 17 00:00:00 2001
From: Josh Goebel 
Date: Thu, 14 Jan 2021 13:14:38 -0500
Subject: [PATCH 6/8] check env

---
 src/highlight.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/highlight.js b/src/highlight.js
index e4b6334de4..2de853f3c4 100644
--- a/src/highlight.js
+++ b/src/highlight.js
@@ -777,7 +777,10 @@ const HLJS = function(hljs) {
     if (wantsHighlight) highlightAll();
   }
 
-  window.addEventListener('DOMContentLoaded', boot, false);
+  // make sure we are in the browser environment
+  if (typeof window !== 'undefined' && window.addEventListener) {
+    window.addEventListener('DOMContentLoaded', boot, false);
+  }
 
   /**
    * Register a language grammar module

From 98d1b6a020f78d95f49dd1ff2c53603400ce4a07 Mon Sep 17 00:00:00 2001
From: Josh Goebel 
Date: Thu, 14 Jan 2021 13:27:19 -0500
Subject: [PATCH 7/8] test was making assumptions it should not have been

---
 test/special/index.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/test/special/index.js b/test/special/index.js
index 1b5419321d..936465d904 100644
--- a/test/special/index.js
+++ b/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-`
` tests
     hljs.configure({ useBR: true });
 
-    let blocks = document.querySelectorAll('.code');
+    blocks = document.querySelectorAll('.code');
     blocks.forEach(hljs.highlightBlock);
   });
 

From 62ef08acd74fada70377534f04d86b84fe05e385 Mon Sep 17 00:00:00 2001
From: Josh Goebel 
Date: Tue, 19 Jan 2021 16:07:35 -0500
Subject: [PATCH 8/8] add changelog

---
 CHANGES.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index d1e6372176..5cabeb8aac 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,10 +11,19 @@ Language grammar improvements:
 
 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)
 - 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/