highlightjs · joshgoebel · Mar 17, 2021 · Mar 17, 2021 · Mar 17, 2021 · Mar 17, 2021
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,4 +1,44 @@
-## Version next
+## Version 11.0.0
+
+**This is a major release.**  As such it contains breaking changes which may require action from users.  Please read [VERSION_11_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_11_UPGRADE.md) for a detailed summary of all breaking changes.
+
+Unless otherwise attributed items below are thanks to [Josh Goebel][] (ref: [#2558](https://github.com/highlightjs/highlight.js/issues/2558)).
+
+*The below list should only be considered to be a high-level summary.*
+
+Deprecations / Removals / API Changes:
+
+- `initHighlighting()` and `initHighlightingOnLoad()` deprecated. **Use `highlightAll()`.**
+- `highlightBlock(el)` deprecated. **Use `highlightElement(el)`**
+- `before:highlightBlock` & `after:highlightBlock` callbacks deprecated. **Use  equivalent `highlightElement` callbacks.**
+- `highlight(languageName, code, ignoreIllegals, continuation)` signature deprecated. **Use `highlight(code, {language, ignoreIllegals})`.**
+- Deprecated `highlight()` signature no longer supports `continuation` argument.
+- `tabReplace` option removed. Consider a plugin.
+- `useBR` option removed. Consider a plugin or CSS.
+- `requireLanguage()` removed. **Use `getLanguage()`.**
+- The return values/keys of some APIs have changed slightly.
+
+Security:
+
+- HTML auto-passthru has been removed. Consider a plugin.
+- Unescaped HTML is now stripped (for security). A warning is logged to the console. (#3057) [Josh Goebel][]
+
+Themes:
+
+- The default padding of all themes increases (0.5em => 1em).
+- `schoolbook` has been updated to remove the lined background.
+- `github` updated to better match modern GitHub (#1616) [Jan Pilzer][]
+
+Language Grammars:
+
+- Default CDN build drops support for several languages.
+- Some language grammar files have been removed.
+- Some redundant language aliases have been removed.
+
+[Josh Goebel]: https://github.com/joshgoebel
+
+
+## Version next 10??? (maybe move into 11)
 
 - enh(parser) Detect comments based on english like text, rather than keyword list [Josh Goebel][]
 - enh(shell) add alias ShellSession [Ryan Mulligan][]
@@ -8,6 +48,7 @@
 [Ryan Mulligan]: https://github.com/ryantm
 
 
+
 ## Version 10.7.1
 
 - fix(parser) Resolves issues with TypeScript types [Josh Goebel][]

diff --git a/README.md b/README.md
@@ -29,11 +29,11 @@ the browser as well as on the server. It works with pretty much any
 markup, doesn’t depend on any framework, and has automatic language
 detection.
 
-#### Upgrading to Version 10
+#### Upgrading to Version 11
+
+As always our major releases do contain breaking changes which may require action from users.  Please read [VERSION_11_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_11_UPGRADE.md) for a detailed summary of breaking changes and any actions you may need to take.
 
-Version 10 is one of the biggest releases in quite some time.  If you're
-upgrading from version 9, there are some breaking changes and things you may
-want to double check first.
+#### Upgrading to Version 10
 
 Please read [VERSION_10_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_UPGRADE.md) for  high-level summary of breaking changes and any actions you may need to take. See [VERSION_10_BREAKING_CHANGES.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_BREAKING_CHANGES.md) for a more detailed list and [CHANGES.md](https://github.com/highlightjs/highlight.js/blob/main/CHANGES.md) to learn what else is new.
 
@@ -147,10 +147,11 @@ div.code {
 
 ## Using with Vue.js
 
-Simply register the plugin with Vue:
+Simply build & register the plugin with Vue:
 
 ```js
-Vue.use(hljs.vuePlugin);
+import { buildVuePlugin } from "highlight.js/lib/vue_plugin.js";
+Vue.use(buildVuePlugin(hljs).VuePlugin);
 ```
 
 And you'll be provided with a `highlightjs` component for use

diff --git a/SECURITY.md b/SECURITY.md
@@ -1,19 +1,20 @@
 # Security Policy
 
-## Supported Versions
+Due to both time and resource constrains the Highlight.js core team fully supports only the current major/minor release of the library.  Prior major releases may be supported for a short time after new major releases are issued.  Problems with minor releases are often resolved by upgrading to the most recent release.
 
-Due to both time and resource constrains the Highlight.js core team only fully supports the current major/minor release of the library.  Problems with minor releases are often resolved by upgrading to the most recent release.
+### Supported Versions
 
-| Version  | Supported  | Status  |
+| Version  | | Status  |
 | :-----:  | :-: | :------ |
-| 10.7.1   | :white_check_mark: &nbsp; :closed_lock_with_key: |  The 10.x series recieves regular updates, new features & bug fixes. |
-| <= 10.4.0  | :x: | Known vulnerabities.  *Please upgrade to a more recent 10.x release.* |
-| 9.18.5   | :x: |  [EOL](https://github.com/highlightjs/highlight.js/issues/2877). No longer supported. See [VERSION_10_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_UPGRADE.md). |
-| <= 9.18.3 | :x: | No longer supported.  Known vulnerabities. |
-| <= 8.x    | :x: | Obsolete. |
+| 11.0   | :white_check_mark: |  The 11.x series recieves regular updates, new features & security fixes. |
+| 10.7.1   | :white_check_mark: |  The 10.x series is in maintence mode.  EOL TBD.<br>See [VERSION_11_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/master/VERSION_11_UPGRADE.md).|
+| <= 10.4.0  | :x: | Known vulnerabities. |
+| 9.18.5   | :x: | [EOL](https://github.com/highlightjs/highlight.js/issues/2877). No longer supported. |
+| <= 9.18.3 | :x: | Known vulnerabities. |
+| <= 8.x    | :x: | Obsolete. Known vulnerabities. |
 
 
-## Reporting a Vulnerability
+### Reporting a Vulnerability
 
-Minor vulnerabilities can simply be reported (and tracked) via our [GitHub issues](https://github.com/highlightjs/highlight.js/issues).   If you feel your issue is more sensitive than that you can always reach us via email: [[email protected]](mailto:[email protected])
+Many vulnerabilities can simply be reported (and tracked) via our [GitHub issues](https://github.com/highlightjs/highlight.js/issues).   If you feel your issue is more sensitive than that you can always reach us via email: [[email protected]](mailto:[email protected])
 
diff --git a/VERSION_11_UPGRADE.md b/VERSION_11_UPGRADE.md
@@ -0,0 +1,146 @@
+- [Overview of Breaking Changes](#overview-of-breaking-changes)
+  - [Built-in set of "Common" Languages](#built-in-set-of-common-languages)
+  - [Language Files](#language-files)
+  - [Language Aliases](#language-aliases)
+  - [Styles and CSS](#styles-and-css)
+  - [Behavioral changes](#behavioral-changes)
+    - [API changes](#api-changes)
+      - [Changes to Result Data](#changes-to-result-data)
+    - [Feature Removal](#feature-removal)
+  - [Small Things](#small-things)
+
+
+## Overview of Breaking Changes
+
+Welcome to version 11.0.  This a major release and therefore contains breaking changes.  Below is a complete list of those such changes.
+
+
+### Built-in set of "Common" Languages
+
+The default `highlight.min.js` build **removes** a few less popular grammars:
+
+- apache
+- http
+- nginx
+- properties
+- coffeescript
+
+If you need any of these, you can always create a custom build.
+
+Ref: https://github.com/highlightjs/highlight.js/issues/2848
+
+
+### Language Files
+
+This would matter if you are requiring any of these files directly (via Node.js or CDN).
+
+- `htmlbars` has been removed. Use `handlebars` instead.
+- `c-like` has been removed. Use `c`, `cpp`, or `arduino`.
+- `sql_more` has been removed. Use `sql` instead.
+
+
+### Language Aliases
+
+This would matter if you are using these aliases.
+
+- `php3`,`php4`,`php5`, `php6`, `php7`, and `php8` havbe been removed. Use `php` instead.
+- `zsh` has been removed. Use `sh` or `bash` instead.
+- `freepascal`, `lazarus`, `lpr`, and `lpm` removed. Use `delphi` instead.
+
+You can of course re-register any of these aliases easily if necessary. For example to restore the PHP aliases:
+
+```js
+hljs.registerAliases(["php3","php4","php5","php6","php7","php8"],{ languageName: "php" })
+```
+
+### Styles and CSS
+
+- 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).
+
+
+### Behavioral changes
+
+#### API changes
+
+- The `highlight(language,code, ...args)` API no longer accepts `continuation` as a 4th argument.
+- The `highlight(language,code, ...args)` API is deprecated (to be removed in 12.0).
+
+The new call signature is `highlight(code, {options})`. ([see docs](https://highlightjs.readthedocs.io/en/latest/api.html#highlight))
+
+Code using the old API:
+
+```js
+// highlight(language, code, ignoreIllegals, continuation)
+highlight("javascript", "var a = 5;", true)
+```
+...would be upgraded to the newer API as follows:
+
+```js
+// highlight(code, {language, ignoreIllegals})
+highlight("var a = 5;", {language: "javascript", ignoreIllegals: true})
+```
+
+The new API purposely does not support `continuation` as this is only intended for internal library usage.
+
+- `initHighlighting()` is deprecated (to be removed in 12.0).
+- `initHighlightingOnLoad()` is deprecated (to be removed in 12.0).
+
+**Use `highlightAll()` instead.** ([see docs](https://highlightjs.readthedocs.io/en/latest/api.html#highlight-all)) The old functions are now simply aliases of `highlightAll()`. The new function may be called before or after the DOM is loaded and should do the correct thing in all cases, replacing the need for the previous individual functions.
+
+Note: `highlightAll()` does not guard against calling itself repeatedly as the previous functions did. Your code should be careful to avoid doing this.
+
+- `highlightBlock()` is deprecated (to be removed in 12.0).
+
+**Use `highlightElement()` instead.** ([see docs](https://highlightjs.readthedocs.io/en/latest/api.html#highlight-element)) This is merely a naming change.
+
+Note: The object literal passed to the `before:highlightElement` callback now passes the element in the `el` key vs the `block` key.
+
+##### Changes to Result Data
+
+- `highlightAuto()`'s `second_best` key has been renamed to `secondBest`
+- `highlightElement()`'s result now no longer includes a `re` key. Use the `relevance` key now.
+- `highlight()` renames some result keys to more clearly mark them as private: `_top`, `_emitter`, and `_illegalBy`. You should not depend on these keys as they are subject to change at any time.
+- The `relevance` key returned by `highlight()` is no longer guaranteed to be an even integer.
+
+
+#### Feature Removal
+
+- HTML auto-passthru is now no longer included in core.  Use a plugin instead. For a possible plugin please see [#2889](https://github.com/highlightjs/highlight.js/issues/2889).
+
+An example:
+
+```html
+<pre><code class="lang-js">
+var a = 4;
+<span class="yellow">var a = 4;</span>
+</code></pre>
+```
+
+Unescaped HTML like this will now be ignored (stripped before highlighting) and a warning will be logged to the console.  All HTML to be highlighted should be properly escaped to avoid potential HTML/JS injection attacks.
+
+- `fixMarkup` has been removed.
+
+This function was deprecated in v10.2.  It is not our goal to provide random string utilities. You may need to provide your own replacement [Ref: #2534](https://github.com/highlightjs/highlight.js/issues/2634)
+
+- `CSS_NUMBER_MODE` has been removed.
+
+This rule was too broad for bring inclusion in core and has been removed.
+
+- `useBR` configuration has been removed.
+
+This configuration option was deprecated in v10.1. Use a plugin or preferably simply CSS `white-space: pre`. [Ref: #2559](https://github.com/highlightjs/highlight.js/issues/2559)
+
+
+- `tabReplace` configuration has been removed.
+
+This configuration option was deprecated in v10.5. Use a plugin or pre-render content instead with desired spacing. [Ref: #2874](https://github.com/highlightjs/highlight.js/issues/2874)
+
+
+
+
+
+### Small Things
+
+- The `regex` utility `join` has been renamed to `_eitherRewriteBackreferences` (this has always been intended for internal use only)
diff --git a/docs/api.rst b/docs/api.rst
@@ -51,17 +51,7 @@ Returns an object with the following properties:
 * ``language``: detected language
 * ``relevance``: integer value representing the relevance score
 * ``value``: HTML string with highlighting markup
-* ``second_best``: object with the same structure for second-best heuristically detected language (may be absent)
-
-
-``fixMarkup(value)`` (deprecated as of 10.3)
---------------------------------------------
-
-**fixMarkup is deprecated and will be removed entirely in v11.**
-
-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``.
-
-Accepts a string with the highlighted markup.
+* ``secondBest``: object with the same structure for second-best heuristically detected language (may be absent)
 
 
 ``highlightBlock(block)``
@@ -82,8 +72,6 @@ in the ``class`` attribute of the DOM node. See the :doc:`class reference
 
 Configures global options:
 
-* ``tabReplace``: a string used to replace TAB characters in indentation.
-* ``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.
 * ``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.)
@@ -93,11 +81,12 @@ Accepts an object representing options with the values to updated. Other options
 ::
 
   hljs.configure({
-    tabReplace: '    ', // 4 spaces
+    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
   });
-  hljs.initHighlighting();
+  hljs.highlightAll();
 
 
 ``highlightAll()``

diff --git a/docs/style-guide.rst b/docs/style-guide.rst
@@ -60,17 +60,6 @@ Okay to use:
 These may seem arbitrary at first but it's what has shown to make sense in
 practice.
 
-There's also a common set of rules that *has* to be defined for the root
-container verbatim:
-
-::
-
-  .hljs {
-    display: block;
-    overflow-x: auto;
-    padding: 0.5em;
-  }
-
 
 ``.subst``
 ----------