diff --git a/README.md b/README.md index ecff7ed488..e060a8c0d3 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,15 @@ detection. - [Using with Vue.js](#using-with-vuejs) - [Using Web Workers](#using-web-workers) - [Importing the Library](#importing-the-library) - - [Node.js / `require`](#nodejs--require) - - [ES6 Modules / `import`](#es6-modules--import) + - [Node.js CommonJS Modules / `require`](#nodejs-commonjs-modules--require) + - [Node.js ES6 Modules / `import`](#nodejs-es6-modules--import) + - [Browser ES6 Modules](#browser-es6-modules) - [Getting the Library](#getting-the-library) - [Fetch via CDN](#fetch-via-cdn) - [cdnjs (link)](#cdnjs-link) - [jsdelivr (link)](#jsdelivr-link) - [unpkg (link)](#unpkg-link) - - [Download prebuilt CDN assets](#download-prebuilt-cdn-assets) + - [Download prebuilt CDN assets](#download-prebuilt-cdn-assets) - [Download from our website](#download-from-our-website) - [Install via NPM package](#install-via-npm-package) - [Build from Source](#build-from-source) @@ -240,7 +241,7 @@ onmessage = (event) => { First, you'll likely be installing the library via `npm` or `yarn` -- see [Getting the Library](#getting-the-library). -### Node.js / `require` +### Node.js CommonJS Modules / `require` Requiring the top-level library will load all languages: @@ -266,10 +267,7 @@ const highlightedCode = hljs.highlight('Hello World!', {language: ' ``` -### ES6 Modules / `import` - -*Note: You can also import directly from fully static URLs, such as our very own pre-built -ES6 Module CDN resources. See [Fetch via CDN](#fetch-via-cdn) for specific examples.* +### Node.js ES6 Modules / `import` The default import will register all languages: @@ -292,6 +290,53 @@ import hljs from 'highlight.js'; import 'highlight.js/styles/github.css'; ``` +### Browser ES6 Modules + +*Note: For now you'll want to install `@highlightjs/cdn-assets` package instead of `highlight.js`. +See [Download prebuilt CDN assets](#download-prebuilt-cdn-assets)* + +To import the library and register only those languages that you need: + +```js +import hljs from './assets/js/@highlightjs/cdn-assets/es/core.js'; +import javascript from './assets/js/@highlightjs/cdn-assets/es/languages/javascript.min.js'; + +hljs.registerLanguage('javascript', javascript); +``` + +To import the library and register all languages: + +```js +import hljs from './assets/js/@highlightjs/cdn-assets/es/highlight.js'; +``` + +*Note: The path to these files will vary depending on where you have installed/copied them +within your project or site. The above path is only an example.* + +You can also use [`importmap`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to import in similar way as Node: + +```html + +``` + +Use the above code in your HTML. After that, your JavaScript can import using the named key from +your `importmap`, for example `@highlightjs` in this case: + +```js +import hljs from '@highlightjs/core.js'; +import javascript from '@highlightjs/languages/javascript.min.js'; + +hljs.registerLanguage('javascript', javascript); +``` + +*Note: You can also import directly from fully static URLs, such as our very own pre-built ES6 Module CDN resources. See [Fetch via CDN](#fetch-via-cdn) for specific examples.* + ## Getting the Library @@ -395,7 +440,7 @@ hljs.registerLanguage('go', go); **Note:** *The CDN-hosted `highlight.min.js` package doesn't bundle every language.* It would be very large. You can find our list of "common" languages that we bundle by default on our [download page][5]. -#### Download prebuilt CDN assets +### Download prebuilt CDN assets You can also download and self-host the same assets we serve up via our own CDNs. We publish those builds to the [cdn-release](https://github.com/highlightjs/cdn-release) GitHub repository. You can easily pull individual files off the CDN endpoints with `curl`, etc; if say you only needed `highlight.min.js` and a single CSS file. @@ -418,6 +463,14 @@ npm install highlight.js yarn add highlight.js ``` +There is also another npm package [@highlightjs/cdn-assets](https://www.npmjs.com/package/@highlightjs/cdn-assets) that contains prebuilt CDN assets including [ES6 Modules that can be imported in browser](#browser-es6-modules): + +```bash +npm install @highlightjs/cdn-assets +# or +yarn add @highlightjs/cdn-assets +``` + Alternatively, you can build the NPM package from source.