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 Prism, that’s 151 languages (as of [email protected]) and all themes.

Want to use highlight.js instead? Try lowlight!

Table of Contents

• Installation
• Usage
• API
  • refractor.register(syntax)
  • refractor.highlight(value, language)
  • refractor.registered(language)
• Browser
• Plugins
• Syntaxes
• Related
• License

Installation

npm:

npm install

Usage in the browser »

Note: Prism depends on clipboard.js, but that code isn’t included when running refractor.

Usage

var refractor = require('refractor')

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

console.log(nodes)

Yields:

[ { 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: ';' } ] } ]

Or, stringified with rehype:

var rehype = require('rehype')

var html = rehype()
  .stringify({type: 'root', children: nodes})
  .toString()

console.log(html)

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

refractor.register(syntax)

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

Example

var refractor = require('refractor/core.js')

refractor.register(require('refractor/lang/markdown.js'))

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

Yields:

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

refractor.highlight(value, language)

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

Returns

Virtual nodes representing the highlighted value (Array.<Node>).

Example

var refractor = require('refractor/core.js')

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

Yields:

[ { 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

var refractor = require('refractor/core.js')

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

refractor.register(require('refractor/lang/markdown.js'))

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

Yields:

false
true

Browser

I do not suggest using the pre-bundled files or requiring refractor itself in the browser as that would include a 352kb (128kb GZipped) of code.

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

var refractor = require('refractor/core.js')

refractor.register(require('refractor/lang/jsx.js'))

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

Yields:

[ { type: 'element',
    tagName: 'span',
    properties: { className: [ 'token', 'tag' ] },
    children:
     [ { type: 'element',
         tagName: 'span',
         properties: { className: [ 'token', 'tag' ] },
         children:
          [ { type: 'element',
              tagName: 'span',
              properties: { className: [ 'token', 'punctuation' ] },
              children: [ { type: 'text', value: '<' } ] },
            { type: 'text', value: 'Dropdown' } ] },
       { type: 'text', value: ' ' },
       { type: 'element',
         tagName: 'span',
         properties: { className: [ 'token', 'attr-name' ] },
         children: [ { type: 'text', value: 'primary' } ] },
       { type: 'text', value: ' ' },
       { type: 'element',
         tagName: 'span',
         properties: { className: [ 'token', 'punctuation' ] },
         children: [ { type: 'text', value: '/>' } ] } ] } ]

…When using browserify and minifying with tinyify this results in just 65kb of code (23kb with GZip).

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 require just what you need.

Syntaxes

All syntaxes are included if you require('refractor'). If you’re using refractor/core.js, checked syntaxes are always included, but unchecked syntaxes are not and must be required and registered.

Unlike in Prism, cssExtras and phpExtras are camel-cased instead of dash-cased.

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.

• clike
• css
• javascript — alias: js
• markup — alias: xml, html, mathml, svg
• abap
• actionscript
• ada
• apacheconf
• apl
• applescript
• arduino
• arff
• asciidoc
• asm6502
• aspnet
• autohotkey
• autoit
• bash — alias: shell
• basic
• batch
• bison
• brainfuck
• bro
• c
• clojure
• coffeescript
• cpp
• crystal
• csharp — alias: dotnet
• csp
• cssExtras
• d
• dart
• diff
• django — alias: jinja2
• docker — alias: dockerfile
• eiffel
• elixir
• elm
• erb
• erlang
• flow
• fortran
• fsharp
• gedcom
• gherkin
• git
• glsl
• go
• graphql
• groovy
• haml
• handlebars
• haskell
• haxe
• hpkp
• hsts
• http
• ichigojam
• icon
• inform7
• ini
• io
• j
• java
• jolie
• json — alias: jsonp
• jsx
• julia
• keyman
• kotlin
• latex
• less
• liquid
• lisp
• livescript
• lolcode
• lua
• makefile
• markdown
• markupTemplating
• matlab
• mel
• mizar
• monkey
• n4js
• nasm
• nginx
• nim
• nix
• nsis
• objectivec
• ocaml
• opencl
• oz
• parigp
• parser
• pascal — alias: objectpascal
• perl
• phpExtras
• php
• plsql
• powershell
• processing
• prolog
• properties
• protobuf
• pug
• puppet
• pure
• python
• q
• qore
• r
• reason
• renpy
• rest
• rip
• roboconf
• ruby
• rust
• sas
• sass
• scala
• scheme
• scss
• smalltalk
• smarty
• soy
• sql
• stylus
• swift
• tap
• tcl
• textile
• tsx
• tt2
• twig
• typescript — alias: ts
• vbnet
• velocity
• verilog
• vhdl
• vim
• visualBasic
• wasm
• wiki
• xeora — alias: xeoracube
• xojo
• xquery
• yaml

Related

• lowlight — Same, but based on highlight.js

License

MIT © Titus Wormer