| 1 | # Upgrading to Version 10.0
|
| 2 |
|
| 3 | Welcome to version 10.0. This a major release and therefore will contain breaking changes.
|
| 4 |
|
| 5 | ## Breaking Changes
|
| 6 |
|
| 7 | Our normal minor releases try to never break anything, holding all breaking changes for major releases.
|
| 8 | We tried to squeeze in as many as we could this time so that after 10.0 ships we'll be back to quiet sailing for a while before we need to push version 11. That said, we're very conservative about what we consider a breaking change.
|
| 9 |
|
| 10 | *IE, if there it could possibly break things for anyone, it's typically a breaking change.* The fact is a vast majority of users should upgrade and probably not notice any changes at all.
|
| 11 |
|
| 12 | See [VERSION_10_BREAKING_CHANGES.md](https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_BREAKING_CHANGES.md) for a comprehensive list of breaking changes, but here is a summary... if you use:
|
| 13 |
|
| 14 | ### Core highlight.js lib on the client (with no extra CDN languages)
|
| 15 |
|
| 16 | Just keep doing that.
|
| 17 |
|
| 18 | - If you're using `darkula.css`, you'll need to change that to `darcula.css`
|
| 19 | - The minified distributable has changed from `.pack.js` to `.min.js`, update your name when you update your URL.
|
| 20 | - If your users have very old browsers, they may no longer be supported (no more IE11, etc.). (We're using ES2015 code now.)
|
| 21 | - `nohighlight` or `no-highlight` are the only two CSS classes that will SKIP highlighting completely. `*text*` and `*plain*` no longer will do this.
|
| 22 |
|
| 23 | ### Core highlight.js lib on the client (plus additional CDN languages)
|
| 24 |
|
| 25 | Quite a few grammars have been renamed. Ex: `nimrod.js` is now `nim.js`.
|
| 26 |
|
| 27 | - Check the renamed grammars to see if you might need to update your links.
|
| 28 | - Be aware that you can't use version 9 CDN JS files anymore, they aren't compatible.
|
| 29 | - Plus read the above list of items.
|
| 30 |
|
| 31 | ### highlight.js on the server (via NPM) and only use the public API
|
| 32 |
|
| 33 | If you're just pulling in the FULL library (`require('./highlight.js')`) just keep doing that. You might not need to change anything.
|
| 34 |
|
| 35 | - If you're manually loading a smaller set of languages and using `registerLanguage` make sure you check out all the renamed grammars and dependency changes.
|
| 36 | - Read the client-side lists above also.
|
| 37 |
|
| 38 | ### highlight.js on the server (via NPM) with a custom integration
|
| 39 |
|
| 40 | Read the complete breaking changes list carefully.
|
| 41 |
|
| 42 | - Read the client-side lists above also.
|
| 43 |
|
| 44 | ### highlight.js lib on the client, with source directly from our GitHub repo
|
| 45 |
|
| 46 | That will no longer work. The source needs to be built to work properly and cannot be used "raw" unless you've also setup your own build pipeline (rollup, etc.). Fetch a static build from the CDN, the [cdn-release repo](https://github.com/highlightjs/cdn-release) or use the new [`highlightjs-dist`]() NPM package.
|
| 47 |
|
| 48 | ### highlight.js source code directly from our GitHub repo with a custom integration
|
| 49 |
|
| 50 | All bets are off, since we only try to guarantee stability of our NPM and CDN builds and the public API. Read all the breaking changes and perhaps skim the commit history.
|
| 51 |
|
| 52 | - We're using ES6 modules now.
|
| 53 | - We're using an entirely new build system.
|
| 54 | - The source will likely become more and more modular during the 10.0 timeline.
|
| 55 |
|
| 56 | ## Enjoy and good luck.
|
| 57 |
|
| 58 | As always if you have any questions or issues, jump on the [Github Issues](https://github.com/highlightjs/highlight.js/issues).
|