refractor

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 — 271 languages

Want to use highlight.js instead? Try lowlight!

Install
Use
Demo
API
Browser
Plugins
Syntaxes
Related
Projects

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.

Demo

Try out an interactive demo (Replit)

API

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

`refractor.register(syntax)`

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])`

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/lib/core.js and include only the needed syntaxes. For example:

import {refractor} from 'refractor/lib/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:

Prism plugins often deal with the DOM, not Prism tokens
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.

lowlight — Same, but based on highlight.js

Projects

react-syntax-highlighter — React component for syntax highlighting
rehype-prism — Syntax highlighting in rehype
react-refractor — Syntax highlighter for React

rmadsen / refractor Goto Github PK

refractor's Introduction

refractor

Contents

Install

Use

Demo

API

refractor.register(syntax)

Example

refractor.alias(name[, alias])

Signatures

Parameters

Example

refractor.highlight(value, language)

Returns

Example

refractor.registered(language)

Example

refractor.listLanguages()

Returns

Example

Browser

Plugins

Syntaxes

Related

Projects

License

refractor's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org

`refractor.register(syntax)`

`refractor.alias(name[, alias])`

`refractor.highlight(value, language)`

`refractor.registered(language)`

`refractor.listLanguages()`