/refractor

Lightweight, robust, elegant virtual syntax highlighting using Prism

Primary LanguageJavaScriptMIT LicenseMIT

refractor

Build Coverage Downloads Size

Lightweight, robust, elegant virtual syntax highlighting using Prism. Useful for virtual DOMs and non-HTML things. Perfect for React, VDOM, and others.

refractor is built to work with all syntaxes supported by [highlight.js][]. There are three builds:

  • lib/core.js — 0 languages
  • lib/common.js (default) — 36 languages
  • lib/all.js — 258 languages

Want to use highlight.js instead? Try lowlight!

Contents

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install refractor

Use in the browser »

Use

import {refractor} from 'refractor'

var root = refractor.highlight('"use strict";', 'js')

console.log(root)

Yields:

{
  type: 'root',
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {className: ['token', 'string']},
      children: [{type: 'text', value: '"use strict"'}]
    },
    {
      type: 'element',
      tagName: 'span',
      properties: {className: ['token', 'punctuation']},
      children: [{type: 'text', value: ';'}]
    }
  ]
}

Which serialized with hast-util-to-html (or rehype) yields:

<span class="token string">"use strict"</span><span class="token punctuation">;</span>

Tip: Use hast-to-hyperscript to transform to other virtual DOMs, or DIY.

API

This package exports the following identifiers: refractor. There is no default export.

refractor.register(syntax)

Register a syntax. Needed if you’re using refractor/core.

Example
import {refractor} from 'refractor/core.js'
import markdown from 'refractor/lang/markdown.js'

refractor.register(markdown)

console.log(refractor.highlight('*Emphasis*', 'markdown'))

Yields:

{
  type: 'root',
  children: [
    {type: 'element', tagName: 'span', properties: [Object], children: [Array]}
  ]
}

refractor.alias(name[, alias])

Register a new alias for the name language.

Signatures
  • alias(name, alias|list)
  • alias(aliases)
Parameters
  • name (string) — Name of a registered language
  • alias (string) — New alias for the registered language
  • list (Array.<alias>) — List of aliases
  • aliases (Object.<alias|list>) — Map where each key is a name and each value an alias or a list
Example
import {refractor} from 'refractor/core.js'
import markdown from 'refractor/lang/markdown.js'

refractor.register(markdown)

// refractor.highlight('*Emphasis*', 'mdown')
// ^ would throw: Error: Unknown language: `mdown` is not registered

refractor.alias({markdown: ['mdown', 'mkdn', 'mdwn', 'ron']})
refractor.highlight('*Emphasis*', 'mdown')
// ^ Works!

refractor.highlight(value, language)

Parse value (string) according to the language (name or alias) syntax.

Returns

Virtual node representing the highlighted value (Root).

Example
import {refractor} from 'refractor/core.js'
import css from 'refractor/lang/css.js'

refractor.register(css)
console.log(refractor.highlight('em { color: red }', 'css'))

Yields:

{
  type: 'root',
  children: [
    {type: 'element', tagName: 'span', properties: [Object], children: [Array]},
    {type: 'text', value: ' '},
    // …
    {type: 'text', value: ' red '},
    {type: 'element', tagName: 'span', properties: [Object], children: [Array]}
  ]
}

refractor.registered(language)

Check if a language (name or alias) is registered.

Example
import {refractor} from 'refractor/core.js'
import markdown from 'refractor/lang/markdown.js'

console.log(refractor.registered('markdown'))

refractor.register(markdown)

console.log(refractor.registered('markdown'))

Yields:

false
true

refractor.listLanguages()

List all registered languages (names and aliases).

Returns

Array.<string>.

Example
import {refractor} from 'refractor/core.js'
import markdown from 'refractor/lang/markdown.js'

console.log(refractor.listLanguages())

refractor.register(markdown)

console.log(refractor.listLanguages())

Yields:

[]
[
  'markup', // Note that `markup` (a lot of xml based languages) is a dep of markdown.
  'html',
  // …
  'markdown',
  'md'
]

Browser

It is not suggested to import refractor itself in the browser as that would include a 500kb (187kb minzipped) of code.

Instead import refractor/core.js and include only the needed syntaxes. For example:

import {refractor} from 'refractor/core.js'
import jsx from 'refractor/lang/jsx.js'

refractor.register(jsx)

console.log(refractor.highlight('<Dropdown primary />', 'jsx'))

…when using esbuild this results in 35.8kB of code (14kb minzipped).

Plugins

refractor does not support Prism plugins:

  1. Prism plugins often deal with the DOM, not Prism tokens
  2. Prism is made using global variables instead of a module format, so all syntaxes below are custom built to work so you can import just what you need

Syntaxes

If you’re using refractor/lib/core.js, no syntaxes are included. Checked syntaxes are included if you import refractor (or refractor/lib/common.js). Unchecked syntaxes are available through refractor/lib/all.js.

Note that Prism works as a singleton. That means that if you register a syntax anywhere in your project, it’ll become available everywhere!

Only these custom built syntaxes will work with refractor because Prism’s own syntaxes are made to work with global variables and are not requirable.

Related

Projects

License

MIT © Titus Wormer