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

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

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
  })
);

NPM:

  npm install metalsmith-prism --save-dev

Yarn:

  yarn add metalsmith-prism

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" />

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

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

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

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

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

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.

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'],
  })
);

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

Linux/Mac:

DEBUG=metalsmith-prism

Windows:

set "DEBUG=metalsmith-prism"

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

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

Robert McGuinness - for the initial implementation of the plugin.

Code released under the MIT license.