metalsmith-prism

A Metalsmith plugin that adds Prism specific HTML markup to code sections for syntax coloring.

While this plugin adds all the required Prism HTML markup, prism.css must be included on the page to provide the syntax coloring. The plugin:

• Automatically handles language dependencies
• Supports HTML entity decoding
• Can add line numbers
• Works seamlessly with Markdown code blocks
• Supports all Prism.js languages

Requirements

• Node >= 18.x.x
• NPM >= 9.x.x
• Metalsmith >= v2.6.x

Quick Start

1. Install the plugin
2. Add Prism CSS to your page
3. Add language classes to your code blocks
4. Configure the plugin in your Metalsmith build

Example using all features:

metalsmith(__dirname).use(
  prism({
    decode: true, // Decode HTML entities
    lineNumbers: true, // Show line numbers
    preLoad: ['java'], // Pre-load language dependencies
  })
);

Installation

NPM:

  npm install metalsmith-prism --save-dev

Yarn:

  yarn add metalsmith-prism

Usage

Add Prism styles to page header.

If the linenumbers option is set to true, prism-line-numbers.css must be added to the page.

The css files can be downloaded from the Prism website or use a CDN. Please refer to the Prism documentation for details.

<link href="/assets/prism.css" rel="stylesheet" /> <link href="/assets/prism-line-numbers.css" rel="stylesheet" />

Add language definition to code block

<code class="language-css">p { color: red }</code>

Add metalsmith-prism plugin to metalsmith

const metalsmith = require('metalsmith');
const prism = require('metalsmith-prism');

metalsmith(__dirname).use(prism()).build();

To use with Markdown code blocks rendered by @metalsmith/markdown

const metalsmith = require('metalsmith');
const markdown = require('@metalsmith/markdown');
const prism = require('metalsmith-prism');

metalsmith(__dirname).use(markdown()).use(prism()).build();

Language support

The plugin default language support includes: markup, css, clike, javascript and php.

Supports all programming languages that have a corresponding Prism.js component file. Component files are found in the Prism.js components directory.

Options

decode (optional)

Always decode the html entities when processing language of type markup

Metalsmith(__dirname).use(
  prism({
    decode: true,
  })
);

lineNumbers (optional)

Adds the additional HTML markup so line numbers can be added via the line-numbers CSS.

Metalsmith(__dirname).use(
  metalsmithPrism({
    lineNumbers: true,
  })
);

preLoad (optional)

Pre-loads language component(s), such that each language component registers itself in the order given in the input array

Useful for loading syntax that extends other language components that are not automatically registered by Prism

Metalsmith(__dirname).use(
  prism({
    preLoad: ['java', 'scala'],
  })
);

Debug

To enable debug logs, set the DEBUG environment variable to metalsmith-prism:

Linux/Mac:

DEBUG=metalsmith-prism

Windows:

set "DEBUG=metalsmith-prism"

CLI Usage

Add metalsmith-prism key to your metalsmith.json plugins key

{
  "plugins": {
    "metalsmith-prism": {
      "lineNumbers": true,
      "decode": true
    }
  }
}

Credits

Robert McGuinness - for the initial implementation of the plugin.

License

Code released under the MIT license.