metalsmith-prism

A Metalsmith plugin that adds Prism specific HTML markup to code sections for syntax coloring. Now with full dual module support for both ESM and CommonJS environments.

Dual Module Support (ESM and CommonJS)

This plugin supports both ESM and CommonJS environments with no configuration needed:

• ESM: import prism from 'metalsmith-prism'
• CommonJS: const prism = require('metalsmith-prism')

The package detects your environment automatically and provides the appropriate module format. This makes it compatible with both modern ESM projects and legacy CommonJS codebases.

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:

• Supports both ESM and CommonJS environments
• Automatically handles language dependencies
• Supports HTML entity decoding
• Can add line numbers
• Works seamlessly with Markdown code blocks
• Supports all Prism.js language

Requirements

• Node >= 18.0.0
• Metalsmith >= v2.6.0

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

ESM:

import Metalsmith from 'metalsmith';
import prism from 'metalsmith-prism';

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

CommonJS:

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

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

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

ESM:

import Metalsmith from 'metalsmith';
import markdown from '@metalsmith/markdown';
import prism from 'metalsmith-prism';

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

CommonJS:

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(
  prism({
    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']
  })
);

Examples

Basic Usage

Transform a simple code block with JavaScript:

Input HTML:

<pre><code class="language-javascript">
const greeting = 'Hello, World!';
console.log(greeting);
</code></pre>

Output HTML (with syntax highlighting):

<pre class="language-javascript"><code class="language-javascript">
<span class="token keyword">const</span> greeting <span class="token operator">=</span> <span class="token string">'Hello, World!'</span><span class="token punctuation">;</span>
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>greeting<span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre>

With Line Numbers

Enable line numbers for longer code examples:

metalsmith(__dirname)
  .use(
    prism({
      lineNumbers: true
    })
  )
  .build();

This adds the line-numbers class and line number markup to your code blocks.

Working with Markdown

When using with @metalsmith/markdown, code blocks in markdown files are automatically processed:

Markdown file:

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

Build configuration:

metalsmith(__dirname)
  .use(markdown())
  .use(
    prism({
      preLoad: ['python'] // Ensure Python support is loaded
    })
  )
  .build();

Preloading Languages

For better performance with known languages, preload them:

metalsmith(__dirname)
  .use(
    prism({
      preLoad: ['python', 'ruby', 'go', 'rust']
    })
  )
  .build();

Handling Special Characters

For code with HTML entities, use the decode option:

metalsmith(__dirname)
  .use(
    prism({
      decode: true // Properly handle <, >, & etc.
    })
  )
  .build();

Debug

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

metalsmith.env('DEBUG', 'metalsmith-prism*');

CLI Usage

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

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

Test Coverage

This project maintains high statement and line coverage for the source code. Coverage is verified during the release process using the c8 coverage tool.

Credits

• Robert McGuinness - for the initial implementation of the plugin.
• Werner Glinka - current maintainer.

License

Code released under the MIT license.