lowlight - npm Package Compare versions
Comparing version 2.4.0 to 2.4.1
| export {lowlight} from './lib/common.js' | ||
| export type Root = import('./lib/core.js').Root | ||
| export type Options = import('./lib/core.js').Options | ||
| export type AutoOptions = import('./lib/core.js').AutoOptions |
@@ -0,1 +1,7 @@ | ||
| /** | ||
| * @typedef {import('./lib/core.js').Root} Root | ||
| * @typedef {import('./lib/core.js').Options} Options | ||
| * @typedef {import('./lib/core.js').AutoOptions} AutoOptions | ||
| */ | ||
| export {lowlight} from './lib/common.js' |
@@ -14,3 +14,3 @@ export namespace lowlight { | ||
| export type HighlightEmitter = import('highlight.js').Emitter | ||
| export type LowlightElementSpan = { | ||
| export type Span = { | ||
| type: 'element' | ||
@@ -21,32 +21,39 @@ tagName: 'span' | ||
| } | ||
| children: Array<LowlightElementSpan | Text> | ||
| children: Array<Span | Text> | ||
| } | ||
| export type LowlightRoot = { | ||
| export type Root = { | ||
| type: 'root' | ||
| data: { | ||
| language: string | ||
| language: string | null | ||
| relevance: number | ||
| } | ||
| children: Array<LowlightElementSpan | Text> | ||
| children: Array<Span | Text> | ||
| } | ||
| export type ExtraAutoOptions = { | ||
| export type ExtraOptions = { | ||
| /** | ||
| * List of allowed languages; defaults to all registered languages | ||
| * List of allowed languages, defaults to all registered languages. | ||
| */ | ||
| subset?: Array<string> | ||
| subset?: string[] | undefined | ||
| } | ||
| export type LowlightOptions = { | ||
| /** | ||
| * Configuration. | ||
| */ | ||
| export type Options = { | ||
| /** | ||
| * Class prefix | ||
| * Class prefix. | ||
| */ | ||
| prefix?: string | ||
| prefix?: string | undefined | ||
| } | ||
| export type LowlightAutoOptions = LowlightOptions & ExtraAutoOptions | ||
| export type AutoOptions = Options & ExtraOptions | ||
| /** | ||
| * Parse `value` (code) according to the `language` (name) grammar. | ||
| * Highlight `value` (code) as `language` (name). | ||
| * | ||
| * @param {string} language Language name | ||
| * @param {string} value Code value | ||
| * @param {LowlightOptions} [options={}] Settings | ||
| * @returns {LowlightRoot} | ||
| * @param {string} language | ||
| * Programming language name. | ||
| * @param {string} value | ||
| * Code to highlight. | ||
| * @param {Options} [options={}] | ||
| * Configuration. | ||
| * @returns {Root} | ||
| * A hast `Root` node. | ||
| */ | ||
@@ -56,20 +63,25 @@ declare function highlight( | ||
| value: string, | ||
| options?: LowlightOptions | ||
| ): LowlightRoot | ||
| options?: Options | undefined | ||
| ): Root | ||
| /** | ||
| * Parse `value` (code) by guessing its grammar. | ||
| * Highlight `value` (code) and guess its programming language. | ||
| * | ||
| * @param {string} value Code value | ||
| * @param {LowlightAutoOptions} [options={}] Settings | ||
| * @returns {LowlightRoot} | ||
| * @param {string} value | ||
| * Code to highlight. | ||
| * @param {AutoOptions} [options={}] | ||
| * Configuration. | ||
| * @returns {Root} | ||
| * A hast `Root` node. | ||
| */ | ||
| declare function highlightAuto( | ||
| value: string, | ||
| options?: LowlightAutoOptions | ||
| ): LowlightRoot | ||
| options?: AutoOptions | undefined | ||
| ): Root | ||
| /** | ||
| * Register a language. | ||
| * | ||
| * @param {string} language Language name | ||
| * @param {HighlightSyntax} syntax Language syntax | ||
| * @param {string} language | ||
| * Programming language name. | ||
| * @param {HighlightSyntax} syntax | ||
| * `highlight.js` language syntax. | ||
| * @returns {void} | ||
@@ -82,14 +94,26 @@ */ | ||
| /** | ||
| * Is an alias or language name registered. | ||
| * Check whether an `alias` or `language` is registered. | ||
| * | ||
| * @param {string} aliasOrLanguage alias or language | ||
| * @param {string} aliasOrLanguage | ||
| * Name of a registered language or alias. | ||
| * @returns {boolean} | ||
| * Whether `aliasOrlanguage` is registered. | ||
| */ | ||
| declare function registered(aliasOrLanguage: string): boolean | ||
| /** | ||
| * Get a list of all registered languages. | ||
| * List registered languages. | ||
| * | ||
| * @returns {Array.<string>} | ||
| * @returns {Array<string>} | ||
| * Names of registered language. | ||
| */ | ||
| declare function listLanguages(): Array<string> | ||
| /** | ||
| * Register aliases for already registered languages. | ||
| * | ||
| * @param {string|Record<string, string|Array<string>>} language | ||
| * Programming language name or a map of `language`s to `alias`es or `list`s | ||
| * @param {string|Array<string>} [alias] | ||
| * New aliases for the programming language. | ||
| * @returns {void} | ||
| */ | ||
| declare const registerAlias: (( | ||
@@ -99,3 +123,3 @@ language: string, | ||
| ) => void) & | ||
| ((aliases: {[x: string]: string | Array<string>}) => void) | ||
| ((aliases: Record<string, string | Array<string>>) => void) | ||
| export {} |
152
lib/core.js
| /** | ||
| * @typedef {import('hast').Text} Text | ||
| * | ||
| * @typedef {import('highlight.js').HighlightResult} HighlightResult | ||
@@ -9,12 +8,15 @@ * @typedef {import('highlight.js').HLJSOptions} HighlightOptions | ||
| * | ||
| * @typedef {{type: 'element', tagName: 'span', properties: {className: Array.<string>}, children: Array.<LowlightElementSpan|Text>}} LowlightElementSpan | ||
| * @typedef {{type: 'root', data: {language: string, relevance: number}, children: Array.<LowlightElementSpan|Text>}} LowlightRoot | ||
| * @typedef {{type: 'element', tagName: 'span', properties: {className: Array<string>}, children: Array<Span|Text>}} Span | ||
| * @typedef {{type: 'root', data: {language: string|null, relevance: number}, children: Array<Span|Text>}} Root | ||
| * | ||
| * @typedef {Object} ExtraAutoOptions | ||
| * @property {Array.<string>} [subset] List of allowed languages; defaults to all registered languages | ||
| * @typedef {Object} ExtraOptions | ||
| * @property {Array<string>} [subset] | ||
| * List of allowed languages, defaults to all registered languages. | ||
| * | ||
| * @typedef {Object} LowlightOptions | ||
| * @property {string} [prefix='hljs-'] Class prefix | ||
| * @typedef {Object} Options | ||
| * Configuration. | ||
| * @property {string} [prefix='hljs-'] | ||
| * Class prefix. | ||
| * | ||
| * @typedef {LowlightOptions & ExtraAutoOptions} LowlightAutoOptions | ||
| * @typedef {Options & ExtraOptions} AutoOptions | ||
| */ | ||
@@ -30,8 +32,12 @@ | ||
| /** | ||
| * Parse `value` (code) according to the `language` (name) grammar. | ||
| * Highlight `value` (code) as `language` (name). | ||
| * | ||
| * @param {string} language Language name | ||
| * @param {string} value Code value | ||
| * @param {LowlightOptions} [options={}] Settings | ||
| * @returns {LowlightRoot} | ||
| * @param {string} language | ||
| * Programming language name. | ||
| * @param {string} value | ||
| * Code to highlight. | ||
| * @param {Options} [options={}] | ||
| * Configuration. | ||
| * @returns {Root} | ||
| * A hast `Root` node. | ||
| */ | ||
@@ -58,8 +64,10 @@ function highlight(language, value, options = {}) { | ||
| high.configure({__emitter: HastEmitter, classPrefix: prefix}) | ||
| /** @type {HighlightResult & {_emitter: HastEmitter}} */ | ||
| // @ts-ignore our emitter is added. | ||
| const result = high.highlight(value, {language, ignoreIllegals: true}) | ||
| const result = /** @type {HighlightResult & {_emitter: HastEmitter}} */ ( | ||
| high.highlight(value, {language, ignoreIllegals: true}) | ||
| ) | ||
| high.configure({}) | ||
| // Highlight.js seems to use this (currently) for broken grammars, so let’s | ||
| // `highlight.js` seems to use this (currently) for broken grammars, so let’s | ||
| // keep it in there just to be sure. | ||
@@ -71,2 +79,3 @@ /* c8 ignore next 3 */ | ||
| // @ts-expect-error: `language` is always defined in `highlight`. | ||
| result._emitter.root.data.language = result.language | ||
@@ -79,7 +88,10 @@ result._emitter.root.data.relevance = result.relevance | ||
| /** | ||
| * Parse `value` (code) by guessing its grammar. | ||
| * Highlight `value` (code) and guess its programming language. | ||
| * | ||
| * @param {string} value Code value | ||
| * @param {LowlightAutoOptions} [options={}] Settings | ||
| * @returns {LowlightRoot} | ||
| * @param {string} value | ||
| * Code to highlight. | ||
| * @param {AutoOptions} [options={}] | ||
| * Configuration. | ||
| * @returns {Root} | ||
| * A hast `Root` node. | ||
| */ | ||
@@ -90,3 +102,3 @@ function highlightAuto(value, options = {}) { | ||
| let index = -1 | ||
| /** @type {LowlightRoot} */ | ||
| /** @type {Root} */ | ||
| let result = { | ||
@@ -97,6 +109,2 @@ type: 'root', | ||
| } | ||
| /** @type {string} */ | ||
| let name | ||
| /** @type {LowlightRoot} */ | ||
| let current | ||
@@ -112,7 +120,7 @@ if (prefix === null || prefix === undefined) { | ||
| while (++index < subset.length) { | ||
| name = subset[index] | ||
| const name = subset[index] | ||
| if (!high.getLanguage(name)) continue | ||
| current = highlight(name, value, options) | ||
| const current = highlight(name, value, options) | ||
@@ -128,4 +136,6 @@ if (current.data.relevance > result.data.relevance) result = current | ||
| * | ||
| * @param {string} language Language name | ||
| * @param {HighlightSyntax} syntax Language syntax | ||
| * @param {string} language | ||
| * Programming language name. | ||
| * @param {HighlightSyntax} syntax | ||
| * `highlight.js` language syntax. | ||
| * @returns {void} | ||
@@ -138,25 +148,15 @@ */ | ||
| /** | ||
| * Get a list of all registered languages. | ||
| * Register aliases for already registered languages. | ||
| * | ||
| * @returns {Array.<string>} | ||
| * @param {string|Record<string, string|Array<string>>} language | ||
| * Programming language name or a map of `language`s to `alias`es or `list`s | ||
| * @param {string|Array<string>} [alias] | ||
| * New aliases for the programming language. | ||
| * @returns {void} | ||
| */ | ||
| function listLanguages() { | ||
| return high.listLanguages() | ||
| } | ||
| /** | ||
| * Is an alias or language name registered. | ||
| * | ||
| * @param {string} aliasOrLanguage alias or language | ||
| * @returns {boolean} | ||
| */ | ||
| function registered(aliasOrLanguage) { | ||
| return Boolean(high.getLanguage(aliasOrLanguage)) | ||
| } | ||
| const registerAlias = | ||
| /** | ||
| * @type {( | ||
| * ((language: string, alias: string|Array.<string>) => void) & | ||
| * ((aliases: Object<string, string|Array.<string>>) => void) | ||
| * ((language: string, alias: string|Array<string>) => void) & | ||
| * ((aliases: Record<string, string|Array<string>>) => void) | ||
| * )} | ||
@@ -166,24 +166,18 @@ */ | ||
| /** | ||
| * Register more aliases for an already registered language. | ||
| * | ||
| * @param {string|Object<string, string|Array.<string>>} language | ||
| * @param {string|Array.<string>} [alias] | ||
| * @param {string|Record<string, string|Array<string>>} language | ||
| * @param {string|Array<string>} [alias] | ||
| * @returns {void} | ||
| */ | ||
| function (language, alias) { | ||
| /** @type {Object<string, string|Array.<string>>} */ | ||
| let map | ||
| /** @type {string} */ | ||
| let key | ||
| if (typeof language === 'string') { | ||
| map = {} | ||
| map[language] = alias | ||
| // @ts-expect-error: should be a string in this overload. | ||
| high.registerAliases(alias, {languageName: language}) | ||
| } else { | ||
| map = language | ||
| } | ||
| /** @type {string} */ | ||
| let key | ||
| for (key in map) { | ||
| if (own.call(map, key)) { | ||
| high.registerAliases(map[key], {languageName: key}) | ||
| for (key in language) { | ||
| if (own.call(language, key)) { | ||
| high.registerAliases(language[key], {languageName: key}) | ||
| } | ||
| } | ||
@@ -194,2 +188,24 @@ } | ||
| /** | ||
| * Check whether an `alias` or `language` is registered. | ||
| * | ||
| * @param {string} aliasOrLanguage | ||
| * Name of a registered language or alias. | ||
| * @returns {boolean} | ||
| * Whether `aliasOrlanguage` is registered. | ||
| */ | ||
| function registered(aliasOrLanguage) { | ||
| return Boolean(high.getLanguage(aliasOrLanguage)) | ||
| } | ||
| /** | ||
| * List registered languages. | ||
| * | ||
| * @returns {Array<string>} | ||
| * Names of registered language. | ||
| */ | ||
| function listLanguages() { | ||
| return high.listLanguages() | ||
| } | ||
| /** @type {HighlightEmitter} */ | ||
@@ -203,9 +219,9 @@ class HastEmitter { | ||
| this.options = options | ||
| /** @type {LowlightRoot} */ | ||
| /** @type {Root} */ | ||
| this.root = { | ||
| type: 'root', | ||
| data: {language: undefined, relevance: 0}, | ||
| data: {language: null, relevance: 0}, | ||
| children: [] | ||
| } | ||
| /** @type {[LowlightRoot, ...LowlightElementSpan[]]} */ | ||
| /** @type {[Root, ...Span[]]} */ | ||
| this.stack = [this.root] | ||
@@ -266,3 +282,3 @@ } | ||
| const current = this.stack[this.stack.length - 1] | ||
| /** @type {LowlightElementSpan} */ | ||
| /** @type {Span} */ | ||
| const child = { | ||
@@ -269,0 +285,0 @@ type: 'element', |
| { | ||
| "name": "lowlight", | ||
| "version": "2.4.0", | ||
| "version": "2.4.1", | ||
| "description": "Virtual syntax highlighting for virtual DOMs and non-HTML things", | ||
@@ -62,11 +62,11 @@ "license": "MIT", | ||
| "unist-util-remove-position": "^4.0.0", | ||
| "xo": "^0.45.0" | ||
| "xo": "^0.46.0" | ||
| }, | ||
| "scripts": { | ||
| "prepack": "npm run build && npm run format", | ||
| "build": "rimraf \"{lib/**,test/**,script/**,}*.d.ts\" && tsc && type-coverage", | ||
| "generate": "node script/build-registry", | ||
| "generate": "node script/build-registry.js", | ||
| "prepublishOnly": "npm run build && npm run format", | ||
| "build": "rimraf \"{lib,script,test}/**/*.d.ts\" \"*.d.ts\" && tsc && type-coverage", | ||
| "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix", | ||
| "test-api": "node test/index.js", | ||
| "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test/index.js", | ||
| "test-api": "node --conditions development test/index.js", | ||
| "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov npm run test-api", | ||
| "test": "npm run generate && npm run build && npm run format && npm run test-coverage" | ||
@@ -98,4 +98,5 @@ }, | ||
| "detail": true, | ||
| "strict": true | ||
| "strict": true, | ||
| "ignoreCatch": true | ||
| } | ||
| } |
335
readme.md
@@ -0,1 +1,3 @@ | ||
| <!--lint disable no-html--> | ||
| # lowlight | ||
@@ -8,22 +10,8 @@ | ||
| Virtual syntax highlighting for virtual DOMs and non-HTML things, with language | ||
| auto-detection. | ||
| Perfect for [React][], [VDOM][], and others. | ||
| Virtual syntax highlighting for virtual DOMs and non-HTML things. | ||
| Lowlight is built to work with all syntaxes supported by [highlight.js][]. | ||
| There are three builds of lowlight: | ||
| <!--index start--> | ||
| * `lib/core.js` — 0 languages | ||
| * `lib/common.js` (default) — 35 languages | ||
| * `lib/all.js` — 191 languages | ||
| <!--index end--> | ||
| Want to use [Prism][] instead? | ||
| Try [`refractor`][refractor]! | ||
| ## Contents | ||
| * [What is this?](#what-is-this) | ||
| * [When should I use this?](#when-should-i-use-this) | ||
| * [Install](#install) | ||
@@ -38,14 +26,51 @@ * [Use](#use) | ||
| * [`lowlight.listLanguages()`](#lowlightlistlanguages) | ||
| * [Syntaxes](#syntaxes) | ||
| * [Examples](#examples) | ||
| * [Example: serializing hast as html](#example-serializing-hast-as-html) | ||
| * [Example: turning hast into react nodes](#example-turning-hast-into-react-nodes) | ||
| * [Types](#types) | ||
| * [Data](#data) | ||
| * [CSS](#css) | ||
| * [Compatibility](#compatibility) | ||
| * [Security](#security) | ||
| * [Related](#related) | ||
| * [Projects](#projects) | ||
| * [Contribute](#contribute) | ||
| * [License](#license) | ||
| ## What is this? | ||
| This package wraps [highlight.js][] to output objects (ASTs) instead of a string | ||
| of HTML. | ||
| `highlight.js`, through lowlight, supports 190+ programming languages. | ||
| Supporting all of them requires a lot of code. | ||
| That’s why there are three entry points for lowlight: | ||
| <!--index start--> | ||
| * `lib/core.js` — 0 languages | ||
| * `lib/common.js` (default) — 35 languages | ||
| * `lib/all.js` — 191 languages | ||
| <!--index end--> | ||
| Bundled, minified, and gzipped, those are roughly 9.7 kB, 47 kB, and 290 kB. | ||
| ## When should I use this? | ||
| This package is useful when you want to perform syntax highlighting in a place | ||
| where serialized HTML wouldn’t work or wouldn’t work well. | ||
| For example, you can use lowlight when you want to show code in a CLI by | ||
| rendering to ANSI sequences, when you’re using virtual DOM frameworks (such as | ||
| React or Preact) so that diffing can be performant, or when you’re working with | ||
| ASTs (rehype). | ||
| A different package, [`refractor`][refractor], does the same as lowlight but | ||
| uses [Prism][] instead. | ||
| ## Install | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): | ||
| Node 12+ is needed to use it and it must be `import`ed instead of `require`d. | ||
| This package is [ESM only][esm]. | ||
| In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: | ||
| [npm][]: | ||
| ```sh | ||
@@ -55,6 +80,18 @@ npm install lowlight | ||
| In Deno with [Skypack][]: | ||
| ```js | ||
| import {lowlight} from 'https://cdn.skypack.dev/lowlight@2?dts' | ||
| ``` | ||
| In browsers with [Skypack][]: | ||
| ```html | ||
| <script type="module"> | ||
| import {lowlight} from 'https://cdn.skypack.dev/lowlight@2?min' | ||
| </script> | ||
| ``` | ||
| ## Use | ||
| Highlight: | ||
| ```js | ||
@@ -86,47 +123,5 @@ import {lowlight} from 'lowlight' | ||
| hast trees can be serialized with [`hast-util-to-html`][to-html]: | ||
| ```js | ||
| import {lowlight} from 'lowlight' | ||
| import {toHtml} from 'hast-util-to-html' | ||
| const tree = lowlight.highlight('js', '"use strict";') | ||
| console.log(toHtml(tree)) | ||
| ``` | ||
| Yields: | ||
| ```html | ||
| <span class="hljs-meta">"use strict"</span>; | ||
| ``` | ||
| hast trees can be turned into other things, like virtual DOMs, with | ||
| [`hast-to-hyperscript`][to-hyperscript]. | ||
| hast trees are also used throughout the **[rehype][]** (**[unified][]**) | ||
| ecosystem: | ||
| ```js | ||
| import {unified} from 'unified' | ||
| import rehypeStringify from 'rehype-stringify' | ||
| import {lowlight} from 'lowlight' | ||
| const tree = lowlight.highlight('js', '"use strict";') | ||
| const processor = unified().use(rehypeStringify) | ||
| const html = processor.stringify(tree).toString() | ||
| console.log(html) | ||
| ``` | ||
| Yields: | ||
| ```html | ||
| <span class="hljs-meta">"use strict"</span>; | ||
| ``` | ||
| ## API | ||
| This package exports the following identifiers: `lowlight`. | ||
| This package exports the following identifier: `lowlight`. | ||
| There is no default export. | ||
@@ -136,15 +131,21 @@ | ||
| Parse `value` (`string`) according to the [`language`][names] grammar. | ||
| Highlight `value` (code) as `language` (name). | ||
| ###### `options` | ||
| ###### Parameters | ||
| * `prefix` (`string?`, default: `'hljs-'`) — Class prefix | ||
| * `language` (`string`) | ||
| — programming language [name][names] | ||
| * `value` (`string`) | ||
| — code to highlight | ||
| * `options.prefix` (`string?`, default: `'hljs-'`) | ||
| — class prefix | ||
| ###### Returns | ||
| A hast [`Root`][root] with two `data` fields: | ||
| A hast [`Root`][root] node with the following `data` fields: | ||
| * `relevance` (`number`) — How sure **low** is that the given code is in the | ||
| language | ||
| * `language` (`string`) — The detected `language` name | ||
| * `relevance` (`number`) | ||
| — how sure lowlight is that the given code is in the language | ||
| * `language` (`string`) | ||
| — detected programming language name | ||
@@ -167,11 +168,13 @@ ###### Example | ||
| Parse `value` by guessing its grammar. | ||
| Highlight `value` (code) and guess its programming language. | ||
| ###### `options` | ||
| ###### Parameters | ||
| The options of `lowlight.highlight` are supported, plus: | ||
| * `value` (`string`) | ||
| — code to highlight | ||
| * `options.prefix` (`string?`, default: `'hljs-'`) | ||
| — class prefix | ||
| * `options.subset` (`Array<string>`, default: all registered language names) | ||
| — list of allowed languages | ||
| * `subset` (`Array.<string>?` default: all registered languages) | ||
| — List of allowed languages | ||
| ###### Returns | ||
@@ -198,5 +201,16 @@ | ||
| Register a [syntax][] as `language` (`string`). | ||
| Useful in the browser or with custom grammars. | ||
| Register a language. | ||
| ###### Parameters | ||
| * `language` (`string`) | ||
| — programming language name | ||
| * `syntax` ([`HighlightSyntax`][syntax]) | ||
| — `highlight.js` syntax | ||
| ###### Note | ||
| `highlight.js` operates as a singleton: once you register a language in one | ||
| place, it’ll be available everywhere. | ||
| ###### Example | ||
@@ -221,3 +235,3 @@ | ||
| Register a new `alias` for `language`. | ||
| Register aliases for already registered languages. | ||
@@ -231,7 +245,10 @@ ###### Signatures | ||
| * `language` (`string`) — [Name][names] of a registered language | ||
| * `alias` (`string`) — New alias for the registered language | ||
| * `list` (`Array.<alias>`) — List of aliases | ||
| * `aliases` (`Object.<language, alias|list>`) — Map where each key is a | ||
| `language` and each value an `alias` or a `list` | ||
| * `language` (`string`) | ||
| — programming language [name][names] | ||
| * `alias` (`string`) | ||
| — new aliases for the programming language | ||
| * `list` (`Array<string>`) | ||
| — list of aliases | ||
| * `aliases` (`Record<language, alias|list>`) | ||
| — map of `language`s to `alias`es or `list`s | ||
@@ -256,12 +273,12 @@ ###### Example | ||
| Is an `alias` or `language` registered. | ||
| Check whether an `alias` or `language` is registered. | ||
| ###### Parameters | ||
| * `aliasOrlanguage` (`string`) — [Name][names] of a registered language | ||
| or its alias | ||
| * `aliasOrlanguage` (`string`) | ||
| — [name][names] of a registered language or alias | ||
| ###### Returns | ||
| `boolean`. | ||
| Whether `aliasOrlanguage` is registered (`boolean`). | ||
@@ -284,7 +301,7 @@ ###### Example | ||
| List all registered languages. | ||
| List registered languages. | ||
| ###### Returns | ||
| `Array.<string>`. | ||
| Names of registered language (`Array<string>`). | ||
@@ -304,12 +321,74 @@ ###### Example | ||
| ## Syntaxes | ||
| ## Examples | ||
| ### Example: serializing hast as html | ||
| hast trees as returned by lowlight can be serialized with | ||
| [`hast-util-to-html`][hast-util-to-html]: | ||
| ```js | ||
| import {lowlight} from 'lowlight' | ||
| import {toHtml} from 'hast-util-to-html' | ||
| const tree = lowlight.highlight('js', '"use strict";') | ||
| console.log(toHtml(tree)) | ||
| ``` | ||
| Yields: | ||
| ```html | ||
| <span class="hljs-meta">"use strict"</span>; | ||
| ``` | ||
| ### Example: turning hast into react nodes | ||
| hast trees as returned by lowlight can be turned into React (or Preact) with | ||
| [`hast-to-hyperscript`][hast-to-hyperscript]: | ||
| ```js | ||
| import {lowlight} from 'lowlight' | ||
| import {toH} from 'hast-to-hyperscript' | ||
| import React from 'react' | ||
| const tree = lowlight.highlight('js', '"use strict";') | ||
| const react = toH(React.createElement, tree) | ||
| console.log(react) | ||
| ``` | ||
| Yields: | ||
| ```js | ||
| { | ||
| '$$typeof': Symbol(react.element), | ||
| type: 'div', | ||
| key: 'h-1', | ||
| ref: null, | ||
| props: { children: [ [Object], ';' ] }, | ||
| _owner: null, | ||
| _store: {} | ||
| } | ||
| ``` | ||
| ## Types | ||
| This package is fully typed with [TypeScript][]. | ||
| It exports additional `Root`, `Options`, and `AutoOptions` types that models | ||
| their respective interfaces. | ||
| <!--Old name of the following section:--> | ||
| <a name="syntaxes"></a> | ||
| ## Data | ||
| If you’re using `lowlight/lib/core.js`, no syntaxes are included. | ||
| Checked syntaxes are included if you import `lowlight` (or | ||
| Checked syntaxes are included if you import `lowlight` (or explicitly | ||
| `lowlight/lib/common.js`). | ||
| Unchecked syntaxes are available through `lowlight/lib/all.js` | ||
| Unchecked syntaxes are available through `lowlight/lib/all.js`. | ||
| You can import `core` or `common` and manually add more languages as you please. | ||
| Note that highlight.js works as a singleton. | ||
| That means that if you register a syntax anywhere in your project, it’ll become | ||
| available everywhere! | ||
| `highlight.js` operates as a singleton: once you register a language in one | ||
| place, it’ll be available everywhere. | ||
@@ -512,5 +591,27 @@ <!--support start--> | ||
| ## CSS | ||
| `lowlight` does not inject CSS for the syntax highlighted code (because well, | ||
| lowlight doesn’t have to be turned into HTML and might not run in a browser!). | ||
| If you are in a browser, you can use any `highlight.js` theme. | ||
| For example, to get GitHub Dark from cdnjs: | ||
| ```html | ||
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.2.0/styles/github-dark.min.css"> | ||
| ``` | ||
| ## Compatibility | ||
| This package is at least compatible with all maintained versions of Node.js. | ||
| As of now, that is Node.js 12.20+, 14.14+, and 16.0+. | ||
| It also works in Deno and modern browsers. | ||
| ## Security | ||
| This package is safe. | ||
| ## Related | ||
| * [`refractor`][refractor] — Same, but based on [Prism][] | ||
| * [`wooorm/refractor`][refractor] | ||
| — the same as lowlight but with [Prism][] | ||
@@ -520,15 +621,19 @@ ## Projects | ||
| * [`emphasize`](https://github.com/wooorm/emphasize) | ||
| — Syntax highlighting in ANSI, for the terminal | ||
| — syntax highlighting in ANSI (for the terminal) | ||
| * [`react-lowlight`](https://github.com/rexxars/react-lowlight) | ||
| — Syntax highlighter for [React][] | ||
| — syntax highlighter for [React][] | ||
| * [`react-syntax-highlighter`](https://github.com/conorhastings/react-syntax-highlighter) | ||
| — [React][] component for syntax highlighting | ||
| * [`rehype-highlight`](https://github.com/rehypejs/rehype-highlight) | ||
| — Syntax highlighting in [**rehype**](https://github.com/rehypejs/rehype) | ||
| * [`remark-highlight.js`](https://github.com/ben-eb/remark-highlight.js) | ||
| — Syntax highlighting in [**remark**](https://github.com/remarkjs/remark) | ||
| — [**rehype**](https://github.com/rehypejs/rehype) plugin to highlight code | ||
| blocks | ||
| * [`jstransformer-lowlight`](https://github.com/ai/jstransformer-lowlight) | ||
| — Syntax highlighting for [JSTransformers](https://github.com/jstransformers) | ||
| — syntax highlighting for [JSTransformers](https://github.com/jstransformers) | ||
| and [Pug](https://pugjs.org/language/filters.html) | ||
| ## Contribute | ||
| Yes please! | ||
| See [How to Contribute to Open Source][contribute]. | ||
| ## License | ||
@@ -558,2 +663,4 @@ | ||
| [skypack]: https://www.skypack.dev | ||
| [license]: license | ||
@@ -563,7 +670,7 @@ | ||
| [to-html]: https://github.com/syntax-tree/hast-util-to-html | ||
| [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c | ||
| [rehype]: https://github.com/rehypejs/rehype | ||
| [typescript]: https://www.typescriptlang.org | ||
| [unified]: https://github.com/unifiedjs/unified | ||
| [contribute]: https://opensource.guide/how-to-contribute/ | ||
@@ -580,8 +687,8 @@ [root]: https://github.com/syntax-tree/hast#root | ||
| [vdom]: https://github.com/Matt-Esch/virtual-dom | ||
| [prism]: https://github.com/PrismJS/prism | ||
| [to-hyperscript]: https://github.com/syntax-tree/hast-to-hyperscript | ||
| [refractor]: https://github.com/wooorm/refractor | ||
| [prism]: https://github.com/PrismJS/prism | ||
| [hast-util-to-html]: https://github.com/syntax-tree/hast-util-to-html | ||
| [refractor]: https://github.com/wooorm/refractor | ||
| [hast-to-hyperscript]: https://github.com/syntax-tree/hast-to-hyperscript |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by8.37%
52394
- Lines of code
- increased by6.34%
788
- Number of lines in readme file
- increased by18.74%
678
No dependency changes