Features

Rainbow brackets

To enable rainbow brackets, add a tokenizeCallback property to defaultEditorProps and defaultCodeBlockProps. Note that editors will also require the matchBrackets() extension when mounted for rainbow brackets to work.

import { rainbowBrackets } from "prism-code-editor/ssr"

// Replace rehype with marked if you're using marked
/** @type {import("rehype-prism-code-editor").PcePluginOptions} */
const options = {
  defaultEditorProps: {
    tokenizeCallback: rainbowBrackets()
  },
  defaultCodeBlockProps: {
    tokenizeCallback: rainbowBrackets()
  }
}

The tokenizeCallback takes the parsed properties as a second argument. The example below will match the delimiters in Java generics together as well.

import { rainbowBrackets } from "prism-code-editor/ssr"

/** @type {import("rehype-prism-code-editor").PcePluginOptions} */
const options = {
  defaultCodeBlockProps: {
    tokenizeCallback(tokens, props) {
      if (props.language == "java") {
        rainbowBrackets("()[]{}<>")(tokens)
      } else {
        rainbowBrackets()(tokens)
      }
    }
  }
}

To remove the tokenize callback for individual code blocks, you can add tokenizeCallback=null to the meta of the code block.

Custom render function

You can provide a custom render function to wrap the default render function or completely override it. The example below wraps the output to add a title with a file name for code blocks. Add a title meta property to the code block, and you should see a <figcaption> element with the specified title.

/** @type {import("rehype-prism-code-editor").PcePluginOptions} */
const options = {
  customRenderer({ title, ...props }, defaultRenderer, isEditor) {
    if (isEditor) return defaultRenderer(props)

    return `<div class="code-block">${
      title ? `<figcaption class="code-title"><span>${title}</span></figcaption>` : ""
    }${defaultRenderer(props)}</div>`
  }
}

Passing extra options to the client

The previous example shows how a custom render function can access extra meta properties you define. In addition, any properties the default render function doesn’t use are stringified to JSON. This JSON will be parsed by forEachCodeBlock() or mountEditorsUnder().

```js myProp
console.log("Hi")
```

We can now check if a code block had the myProp meta property inside the forEachCodeBlock callback.

import {
  forEachCodeBlock,
  highlightBracketPairsOnHover
} from "prism-code-editor/client"

const codeBlocks = forEachCodeBlock<{
  myProp?: boolean
}>(document, (codeBlock, props) => {
  if (props.myProp) highlightBracketPairsOnHover(codeBlock)
})

Tip

It might be a good idea to pre- or postfix your meta property names with e.g. _ or $. This makes them distinguishable from other meta properties and eliminates any chance of name collisions in future releases.

Line highlighting

In addition to all features described in the code blocks guide, code blocks support adding extra classes to lines with properties wrapped in {}. This is intended for line highlighting.

You can either highlight a single line, or a range of lines, and you can combine multiple highlights by separating them with commas. Below is an example:

```js ins={1-2,4}
// Line 1 - Targeted by range "1-2"
// Line 2 - Targeted by range "1-2"
// Line 3
// Line 4 - Targeted by line number
```

This will render as follows:

// Line 1 - Targeted by range "1-2"
// Line 2 - Targeted by range "1-2"
// Line 3
// Line 4 - Targeted by line number

The property name (in this case ins) becomes the class added. None of the themes add styles to highlight any lines, so you must do it yourself. The example below adds a semi-transparent background to the lines along with a border on the left using an inset box shadow.

.pce-line.del {
  background: #ff11002e;
  box-shadow: inset 2px 0 0 #b4554bd0;
}

.pce-line.ins {
  background: #18b30024;
  box-shadow: inset 2px 0 0 #487f3bd0;
}

.pce-line.highlight {
  background: #80808035;
  box-shadow: inset 2px 0 0 #808080bb;
}

If you’re using line numbers, you can make sure the line number element inherits the shadow and background.

.pce-line::before {
  background: inherit;
  box-shadow: inherit;
}

Note

The line highlighting syntax is incompatible with markdown-it-attrs since both use curly braces. If this causes any issues, consider changing the delimiter of markdown-it-attrs.

Meta parsing

The meta parsing uses HTML-attribute-like syntax. The parser will attempt to parse the property value as a boolean, null, or a number, and fall back to a string otherwise. If the value is wrapped by {}, then the property name is added to an array of classes added to the lines. This array is stored in the classes property, which cannot be used as a property name. For example ins={2-4} del={1,3} becomes {classes: [undefined, "del", "ins", "ins del", "ins"]}. You can see the regular expressions used for parsing below:

let range = /(\d+)(?:\s*-\s*(\d+))?/g
let prop = /([^\s"'{}=]+)(?:\s*=\s*("[^"]*"|'[^']*'|\{[^}]*\}|[^\s"'{}=]+))?/g

Inline highlighting

To enable highlighting of inline code, pass an object to the inline option. This object currently accepts an optional tokenizeCallback property to enable rainbow brackets for example.

import { rainbowBrackets } from "prism-code-editor/ssr"

/** @type {import("rehype-prism-code-editor").PcePluginOptions} */
const options = {
  inline: {
    tokenizeCallback: rainbowBrackets()
  }
}

To specify the language used for syntax highlighting, add a {:language} marker at the end of the code snippet. E.g. `code.replace(/\r\n?/g, "\n"){:js}` becomes code.replace(/\r\n?/g, "\n").