Add support for inline code highlighting (#3180)

* Allow highlightAll to be used with custom selectors

Resolves #945 for non-technical users such as those using
highlight.js via a WordPress plugin, allowing simpler inclusion 
of other elements (such as <code>s not wrapped in a <pre>) 
than existing proposed solutions

* Move highlightAll's querySelector into options

* Don't coerce any non-block elements to be blocks

This nearly-singlehandedly resolves
#945

* mention as a breaking change

Co-authored-by: Josh Goebel <me@joshgoebel.com>

.gitignore

@@ -8,6 +8,11 @@ node_modules
 yarn.lock
 extra/
 
+# play stuff
+quick*
+test*
+extra*
+
 # editors
 .idea/
 .vscode/

CHANGES.md

@@ -54,6 +54,7 @@ Parser:
 - adds `title.class` sub-scope support (#3078) [Josh Goebel][]
 - adds `title.function` sub-scope support (#3078) [Josh Goebel][]
 - adds `beforeMatch` compiler extension (#3078) [Josh Goebel][]
+- adds `cssSelector ` configuration option (#3180) [James Edington][]
 
 Grammars:
 
@@ -128,7 +129,8 @@ Dev Improvements:
 [Jared Luboff]: https://github.com/jaredlll08
 [NullVoxPopuli]: https://github.com/NullVoxPopuli
 [Mike Watling]: https://github.com/Pickysaurus
-[Nico Abram]:https://github.com/nico-abram
+[Nico Abram]: https://github.com/nico-abram
+[James Edington]: http://www.ishygddt.xyz/
 
 
 ## Version 10.7.1

VERSION_11_UPGRADE.md

@@ -58,6 +58,7 @@ hljs.registerAliases(["php3","php4","php5","php6","php7","php8"],{ languageName:
 - The default padding on `.hljs` element has been increased and is now `1em` (it was `0.5em` previously). If your design depends on the smaller spacing you may need to update your CSS to override.
 - `schoolbook` no longer has a custom lined background, it is solid color now.  The old image and CSS can be found in the [10-stable branch](https://github.com/highlightjs/highlight.js/tree/10-stable/src/styles) if you wish to manually copy it into your project.
 - `github` includes significant changes to more properly match modern GitHub syntax highlighting. If you desire the old theme you can manually copy it into your project from the [10-stable branch](https://github.com/highlightjs/highlight.js/tree/10-stable/src/styles).
+- The `.hljs` CSS selector is now further scoped.  It now targets `code.hljs` (inline code) and `pre code.hljs` (code blocks). If you are using a different element you may need to update your CSS to reapply some styling.
 
 
 ### Behavioral changes

docs/api.rst

@@ -95,6 +95,7 @@ Configures global options:
 * ``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'``.
 
 Accepts an object representing options with the values to updated. Other options don't change
 ::
@@ -111,7 +112,8 @@ Accepts an object representing options with the values to updated. Other options
 highlightAll
 ------------
 
-Applies highlighting to all ``<pre><code>...</code></pre>`` blocks on a page.
+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.
 
 
@@ -120,7 +122,7 @@ initHighlighting
 
 *Deprecated as of 10.6:* Please use ``highlightAll()`` instead.
 
-Applies highlighting to all ``<pre><code>...</code></pre>`` blocks on a page.
+Applies highlighting to all elements on a page matching ``cssSelector ``.
 
 
 initHighlightingOnLoad

src/highlight.js

@@ -67,6 +67,7 @@ const HLJS = function(hljs) {
     noHighlightRe: /^(no-?highlight)$/i,
     languageDetectRe: /\blang(?:uage)?-([\w-]+)\b/i,
     classPrefix: 'hljs-',
+    cssSelector: 'pre code',
     languages: null,
     // beta configuration options, subject to change, welcome to discuss
     // https://github.com/highlightjs/highlight.js/issues/1086
@@ -784,7 +785,7 @@ const HLJS = function(hljs) {
       return;
     }
 
-    const blocks = document.querySelectorAll('pre code');
+    const blocks = document.querySelectorAll(options.cssSelector);
     blocks.forEach(highlightElement);
   }
 

src/styles/default.css

@@ -8,15 +8,28 @@
   Touched: 2021
 */
 
-.hljs {
+/*
+This is left on purpose making default.css the single file that can be lifted
+as-is from the repository directly without the need for a build step
+
+Typically this "required" baseline CSS is added by `makestuff.js` during build.
+*/
+pre code.hljs {
   display: block;
   overflow-x: auto;
   padding: 1em;
+}
+
+code.hljs {
+  padding: 3px 5px;
+}
+/* end baseline CSS */
+
+.hljs {
   background: #F0F0F0;
   color: #444;
 }
 
-
 /* Base color: saturation 0; */
 
 .hljs-subst {

tools/lib/makestuff.js

@@ -15,10 +15,14 @@ function install(file, dest = file) {
 }
 
 const DEFAULT_CSS = `
-.hljs {
+pre code.hljs {
   display: block;
   overflow-x: auto;
-  padding: 0.5em;
+  padding: 1em;
+}
+
+code.hljs {
+  padding: 3px 5px;
 }
 `.trim();
 

types/index.d.ts

@@ -130,6 +130,7 @@ declare module 'highlight.js' {
         noHighlightRe: RegExp
         languageDetectRe: RegExp
         classPrefix: string
+        cssSelector: string
         languages?: string[]
         __emitter: EmitterConstructor
         ignoreUnescapedHTML?: boolean