|
1 | | -# Default Build Changes |
| 1 | +- [Overview of Breaking Changes](#overview-of-breaking-changes) |
| 2 | + - [Built-in set of "Common" Languages](#built-in-set-of-common-languages) |
| 3 | + - [Language Files](#language-files) |
| 4 | + - [Language Aliases](#language-aliases) |
| 5 | + - [Styles and CSS](#styles-and-css) |
| 6 | + - [Behavioral changes](#behavioral-changes) |
| 7 | + - [API changes](#api-changes) |
| 8 | + - [Changes to Result Data](#changes-to-result-data) |
| 9 | + - [Feature Removal](#feature-removal) |
| 10 | + - [Small Things](#small-things) |
2 | 11 |
|
3 | | -- remove apache, http, nginx, properties, coffeescript from :common #2848 |
4 | 12 |
|
5 | | -### Feature Removal |
| 13 | +## Overview of Breaking Changes |
6 | 14 |
|
7 | | -- HTML merging is now no longer included in core. You'll want to use a plugin instead. https://github.com/highlightjs/highlight.js/issues/2889 |
8 | | -- fixMarkup is gone now, provide your own replacement #2534 |
| 15 | +Welcome to version 11.0. This a major release and therefore contains breaking changes. Below is a complete list of those such changes. |
9 | 16 |
|
10 | | -### Behavior changes |
11 | 17 |
|
12 | | -- `initHighlighting` and `initHighlightingOnLoad` call `highlightAll` |
13 | | -- Calling `highlightAll` over and over is not guarded against |
| 18 | +### Built-in set of "Common" Languages |
14 | 19 |
|
15 | | -### Grammar's removed or renamed |
| 20 | +The default `highlight.min.js` build **removes** a few less popular grammars: |
16 | 21 |
|
17 | | -- remove the old htmlbars stub, use handlebars |
18 | | -- remove c-like, use c, cpp, or arduino |
19 | | -- removed `sql_more`, use `sql` instead |
| 22 | +- apache |
| 23 | +- http |
| 24 | +- nginx |
| 25 | +- properties |
| 26 | +- coffeescript |
20 | 27 |
|
21 | | -### Visual / Themeing / CSS Changes |
| 28 | +If you need any of these, you can always create a custom build. |
22 | 29 |
|
23 | | -- Default padding on `.hljs` is now 1em (up from 0.5em) |
24 | | -- schoolbook no longer has a custom lined background, it's solid now |
| 30 | +Ref: https://github.com/highlightjs/highlight.js/issues/2848 |
25 | 31 |
|
26 | | -### Alias Changes |
27 | 32 |
|
28 | | -- php3,4,5,6,etc... aliases removed, use php instead |
29 | | -- `zsh` removed, use `sh` instead |
30 | | -- `freepascal`, `lazarus`, `lpr`, `lpm` removed. Use `delphi` or add you own aliases back. |
| 33 | +### Language Files |
31 | 34 |
|
32 | | -## API's changed |
| 35 | +This would matter if you are requiring any of these files directly (via Node.js or CDN). |
33 | 36 |
|
34 | | -- rename second_best to secondBest (highlightAuto) |
35 | | -- highlightElement/highlightBlock result now no longer returns `re` key, use `relevance` instead |
36 | | -- `CSS_NUMBER_MODE` has now been moved into the internal `css-shared` library |
37 | | -- `highlight()` result now renames some keys to mark them as private: `_top`, `_emitter`, and `_illegalBy` |
| 37 | +- `htmlbars` has been removed. Use `handlebars` instead. |
| 38 | +- `c-like` has been removed. Use `c`, `cpp`, or `arduino`. |
| 39 | +- `sql_more` has been removed. Use `sql` instead. |
38 | 40 |
|
39 | | -### Configuration options removed/changed |
40 | 41 |
|
41 | | -- useBR gone, #2559 |
42 | | -- tabReplace gone, #2874 |
| 42 | +### Language Aliases |
43 | 43 |
|
44 | | -## Others |
| 44 | +This would matter if you are using these aliases. |
45 | 45 |
|
46 | | -- `relevance` returned may be a floating point number now |
47 | | -- regex utility `join` renamed to `_eitherRewriteBackreferences` (this was always internal) |
| 46 | +- `php3`,`php4`,`php5`, `php6`, `php7`, and `php8` havbe been removed. Use `php` instead. |
| 47 | +- `zsh` has been removed. Use `sh` or `bash` instead. |
| 48 | +- `freepascal`, `lazarus`, `lpr`, and `lpm` removed. Use `delphi` instead. |
| 49 | + |
| 50 | +You can of course re-register any of these aliases easily if necessary. For example to restore the PHP aliases: |
| 51 | + |
| 52 | +```js |
| 53 | +hljs.registerAliases(["php3","php4","php5","php6","php7","php8"],{ languageName: "php" }) |
| 54 | +``` |
| 55 | + |
| 56 | +### Styles and CSS |
| 57 | + |
| 58 | +- 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. |
| 59 | +- `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. |
| 60 | +- `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). |
| 61 | + |
| 62 | + |
| 63 | +### Behavioral changes |
| 64 | + |
| 65 | +#### API changes |
| 66 | + |
| 67 | +- The `highlight(language,code, ...args)` API no longer accepts `continuation` as a 4th argument. |
| 68 | +- The `highlight(language,code, ...args)` API is deprecated (to be removed in 12.0). |
| 69 | + |
| 70 | +The new call signature is `highlight(code, {options})`. ([see docs](https://highlightjs.readthedocs.io/en/latest/api.html#highlight)) |
| 71 | + |
| 72 | +Code using the old API: |
| 73 | + |
| 74 | +```js |
| 75 | +// highlight(language, code, ignoreIllegals, continuation) |
| 76 | +highlight("javascript", "var a = 5;", true) |
| 77 | +``` |
| 78 | +...would be upgraded to the newer API as follows: |
| 79 | + |
| 80 | +```js |
| 81 | +// highlight(code, {language, ignoreIllegals}) |
| 82 | +highlight("var a = 5;", {language: "javascript", ignoreIllegals: true}) |
| 83 | +``` |
| 84 | + |
| 85 | +The new API purposely does not support `continuation` as this is only intended for internal library usage. |
| 86 | + |
| 87 | +- `initHighlighting()` is deprecated (to be removed in 12.0). |
| 88 | +- `initHighlightingOnLoad()` is deprecated (to be removed in 12.0). |
| 89 | + |
| 90 | +**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. |
| 91 | + |
| 92 | +Note: `highlightAll()` does not guard against calling itself repeatedly as the previous functions did. Your code should be careful to avoid doing this. |
| 93 | + |
| 94 | +- `highlightBlock()` is deprecated (to be removed in 12.0). |
| 95 | + |
| 96 | +**Use `highlightElement()` instead.** ([see docs](https://highlightjs.readthedocs.io/en/latest/api.html#highlight-element)) This is merely a naming change. |
| 97 | + |
| 98 | +Note: The object literal passed to the `before:highlightElement` callback now passes the element in the `el` key vs the `block` key. |
| 99 | + |
| 100 | +##### Changes to Result Data |
| 101 | + |
| 102 | +- `highlightAuto()`'s `second_best` key has been renamed to `secondBest` |
| 103 | +- `highlightElement()`'s result now no longer includes a `re` key. Use the `relevance` key now. |
| 104 | +- `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. |
| 105 | +- The `relevance` key returned by `highlight()` is no longer guaranteed to be an even integer. |
| 106 | + |
| 107 | + |
| 108 | +#### Feature Removal |
| 109 | + |
| 110 | +- 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). |
| 111 | + |
| 112 | +An example: |
| 113 | + |
| 114 | +```html |
| 115 | +<pre><code class="lang-js"> |
| 116 | +var a = 4; |
| 117 | +<span class="yellow">var a = 4;</span> |
| 118 | +</code></pre> |
| 119 | +``` |
| 120 | + |
| 121 | +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. |
| 122 | + |
| 123 | +- `fixMarkup` has been removed. |
| 124 | + |
| 125 | +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) |
| 126 | + |
| 127 | +- `CSS_NUMBER_MODE` has been removed. |
| 128 | + |
| 129 | +This rule was too broad for bring inclusion in core and has been removed. |
| 130 | + |
| 131 | +- `useBR` configuration has been removed. |
| 132 | + |
| 133 | +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) |
| 134 | + |
| 135 | + |
| 136 | +- `tabReplace` configuration has been removed. |
| 137 | + |
| 138 | +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) |
| 139 | + |
| 140 | + |
| 141 | + |
| 142 | + |
| 143 | + |
| 144 | +### Small Things |
| 145 | + |
| 146 | +- The `regex` utility `join` has been renamed to `_eitherRewriteBackreferences` (this has always been intended for internal use only) |
0 commit comments