mirror of https://github.com/jkjoy/sunpeiwen.git
204 lines
8.7 KiB
Markdown
204 lines
8.7 KiB
Markdown
|
# Upgrading to Highlight.js v11.0
|
||
|
|
|
||
|
|
- [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)
|
||
|
|
- [Grammar Scopes](#grammar-scopes)
|
||
|
|
- [Behavioral changes](#behavioral-changes)
|
||
|
|
- [API changes](#api-changes)
|
||
|
|
- [Changes to Result Data](#changes-to-result-data)
|
||
|
|
- [Feature Removal](#feature-removal)
|
||
|
|
- [Small Things](#small-things)
|
||
|
|
- [Upgrading from Version 9.x](#upgrading-from-version-9x)
|
||
|
|
|
||
|
|
|
||
|
|
## 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 or a more specific 3rd party grammar.
|
||
|
|
|
||
|
|
|
||
|
|
### Language Aliases
|
||
|
|
|
||
|
|
This would matter if you are using these aliases.
|
||
|
|
|
||
|
|
- `php3`,`php4`,`php5`, `php6`, `php7`, and `php8` have 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).
|
||
|
|
- `github-gist` has been removed in favor of `github` as GitHub and GitHub Gist have converged. If you desire the 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.
|
||
|
|
- All [Base16 themes](https://github.com/highlightjs/base16-highlightjs) now live in the `styles/base16` directory - this means some CSS files have moved. Please confirm themes you use reference the new locations.
|
||
|
|
|
||
|
|
|
||
|
|
#### Grammar Scopes
|
||
|
|
|
||
|
|
- `.meta-string` removed/deprecated. Use `.meta .string` (a nested scope) instead. See [meta-keyword][].
|
||
|
|
- `.meta-keyword` removed/deprecated. Use `.meta .keyword` (a nested scope) instead. See [meta-keyword][].
|
||
|
|
|
||
|
|
### Behavioral changes
|
||
|
|
|
||
|
|
- `after:highlightElement` plugin callback is now fired *after* the DOM has been updated, not before.
|
||
|
|
|
||
|
|
#### API changes
|
||
|
|
|
||
|
|
- The option `ignoreIllegals` is now `true` by default (for `highlight()`). Previously it was `false`.
|
||
|
|
- 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.
|
||
|
|
- `highlightElement` now always tags blocks with a consistent `language-[name]` class
|
||
|
|
|
||
|
|
This behavior was inconsistent before. Sometimes `[name]` class would be added, sometimes the alias name would be added, something no class would be added. now `language-[name]` is always added. This also affects sublanguage `span` tags which now also include the `language-` prefix.
|
||
|
|
|
||
|
|
#### 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.
|
||
|
|
|
||
|
|
- `lexemes` mode attribute has been removed.
|
||
|
|
|
||
|
|
Use the new `keywords.$pattern` instead.
|
||
|
|
|
||
|
|
Before:
|
||
|
|
|
||
|
|
```js
|
||
|
|
{
|
||
|
|
keywords: "do.it start.now begin.later end.immediately"
|
||
|
|
lexemes: /[a-z.]+/
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
After:
|
||
|
|
|
||
|
|
```js
|
||
|
|
{
|
||
|
|
keywords: {
|
||
|
|
$pattern: /[a-z.]+/
|
||
|
|
keyword: "do.it start.now begin.later end.immediately",
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
This may required converting your `keywords` key into an object if it's not already (as shown above).
|
||
|
|
|
||
|
|
- `endSameAsBegin` mode attribute has been removed.
|
||
|
|
|
||
|
|
Use the new `END_SAME_AS_BEGIN` mode rule/function instead.
|
||
|
|
|
||
|
|
- `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)
|
||
|
|
|
||
|
|
### Upgrading from Version 9.x
|
||
|
|
|
||
|
|
If you're upgrading all the way from version 9 it may still be helpful to review all the breaking changes in version 10 as well:
|
||
|
|
|
||
|
|
- [VERSION_10_UPGRADE.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_UPGRADE.md)
|
||
|
|
- [VERSION_10_BREAKING_CHANGES.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_BREAKING_CHANGES.md)
|
||
|
|
|
||
|
|
|
||
|
|
[meta-keyword]: https://github.com/highlightjs/highlight.js/pull/3167
|