remark-syntax-highlight

Syntax highlight code blocks with a custom highlight function in remark.

Why

Several markdown parsers accept a highlight function where you can highlight code in any way you want. It's especially useful if you're concerned about the bundle size and want to support a limited set of languages. However, with remark, you have to write a custom plugin to achieve the same behavior.

The official plugin for highlighting is remark-highlight.js, which uses highlight.js. However, it isn't possible to customize which languages are loaded. In addition, if you want to use something like prism.js instead of highlight.js, there's no similar plugin available.

This plugin is a tiny abstraction over remark's plugin API, allowing you to pass a custom highlight function.

Installation

npm install remark-syntax-highlight

or

yarn add remark-syntax-highlight

Usage

First, we need to wrap our worker:

import remark from 'remark';
import highlight from 'remark-syntax-highlight';

import html from 'remark-html';
import github from 'hast-util-sanitize/lib/github';
import merge from 'deepmerge';

// Import the highlighter, for example, say I want prism with javascript support
import { highlight, languages } from 'prismjs/components/prism-core';
import 'prismjs/components/prism-clike';
import 'prismjs/components/prism-javascript';

// Preserve className attributes when sanitizing the HTML
// This is necessary for syntax highlighting
const schema = merge(github, { attributes: { '*': ['className'] } });

remark()
  .use(html, { sanitize: schema })
  .use(highlight, {
    // Pass a highlight function to highlight the code
    highlight: (code, language) => {
      const grammar = languages[lang];

      if (grammar) {
        return highlight(code, grammar);
      }
    },
  })
  .process(markdown, function(err, file) {
    // do something
  });

You can return highlighted HTML code from the highlight, or null/undefined if no highlight was performed. The plugin will escape the HTML from the code if no highlight was performed.

You can also return a promise which resolves to the highlighted HTML. This can be useful if you want to load languages as needed.

Contributing

While developing, you can run the example app and open the console to see your changes:

yarn example

Make sure your code passes ESLint. Run the following to verify:

yarn lint

To fix formatting errors, run the following:

yarn lint -- --fix