metalsmith-prism 4.3.0 → 5.0.1

package/README.md

@@ -1,45 +1,69 @@
 # metalsmith-prism
 
-A Metalsmith plugin that **adds Prism specific HTML markup** to code sections for syntax coloring. 
+A Metalsmith plugin that **adds Prism specific HTML markup** to code sections for syntax coloring.
 
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square&label=license)](http://opensource.org/licenses/MIT)
 [![NPM](http://img.shields.io/npm/v/metalsmith-prism.svg?style=flat-square&label=npm)](https://npmjs.org/package/metalsmith-prism)
 [![Linux Passing](https://img.shields.io/travis/Availity/metalsmith-prism.svg?style=flat-square&label=linux)](https://travis-ci.org/Availity/metalsmith-prism)
 [![Windows Passing](https://img.shields.io/appveyor/ci/robmcguinness/metalsmith-prism.svg?style=flat-square&label=windows)](https://ci.appveyor.com/project/robmcguinness/metalsmith-prism)
 
-While this plugin adds all the required Prism HTML markup, **prism.css** must be included on the page to provide the 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 `>= 14.x.x`
-+ NPM `>= 8.x.x`
-+ Metalsmith `>= v2.4.x`
+- 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:
+
+```javascript
+metalsmith(__dirname).use(
+  prism({
+    decode: true, // Decode HTML entities
+    lineNumbers: true, // Show line numbers
+    preLoad: ['java'], // Pre-load language dependencies
+  })
+);
+```
 
 ## Installation
 
 NPM:
+
 ```bash
   npm install metalsmith-prism --save-dev
 ```
 
 Yarn:
+
 ```bash
   yarn add metalsmith-prism
 ```
 
 ## Usage
 
-### Add Prism styles to page header. 
+### Add Prism styles to page header.
 
-If the `linenumbers` option is set to `true`, `prism-line-numbers.css` must be added to the page. 
+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](https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript) or [use a CDN](https://prismjs.com/#basic-usage-cdn). Please refer to the [Prism documentation](https://prismjs.com/index.html) for details.
 
 ```html
-<link href="/assets/prism.css" rel="stylesheet" />
-<link href="/assets/prism-line-numbers.css" rel="stylesheet" />
+<link href="/assets/prism.css" rel="stylesheet" /> <link href="/assets/prism-line-numbers.css" rel="stylesheet" />
 ```
 
 ### Add language definition to code block
@@ -54,9 +78,7 @@ The css files can be downloaded from the [Prism website](https://prismjs.com/dow
 const metalsmith = require('metalsmith');
 const prism = require('metalsmith-prism');
 
-metalsmith(__dirname)
-  .use(prism())
-  .build();
+metalsmith(__dirname).use(prism()).build();
 ```
 
 ### To use with Markdown code blocks rendered by [@metalsmith/markdown](https://github.com/metalsmith/markdown)
@@ -66,14 +88,13 @@ const metalsmith = require('metalsmith');
 const markdown = require('@metalsmith/markdown');
 const prism = require('metalsmith-prism');
 
-metalsmith(__dirname)
-  .use(markdown())
-  .use(prism())
-  .build();
+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](https://github.com/PrismJS/prism/tree/master/components).
 
 ## Options
@@ -83,21 +104,23 @@ Supports all programming languages that have a corresponding Prism.js component
 Always decode the html entities when processing language of type `markup`
 
 ```js
-Metalsmith(__dirname)
-  .use(prism({
-    decode: true
-  }))
+Metalsmith(__dirname).use(
+  prism({
+    decode: true,
+  })
+);
 ```
 
 **lineNumbers (optional)**
 
-Adds the additional HTML markup so line numbers can be added via the line-numbers CSS. 
+Adds the additional HTML markup so line numbers can be added via the line-numbers CSS.
 
 ```javascript
-Metalsmith(__dirname)
-  .use(metalsmithPrism({
-    lineNumbers: true
-  }))
+Metalsmith(__dirname).use(
+  metalsmithPrism({
+    lineNumbers: true,
+  })
+);
 ```
 
 **preLoad (optional)**
@@ -107,11 +130,13 @@ Pre-loads language component(s), such that each language component registers its
 Useful for loading syntax that extends other language components that are not automatically registered by Prism
 
 ```javascript
-Metalsmith(__dirname)
-  .use(prism({
-    preLoad: ["java", "scala"]
-  }))
+Metalsmith(__dirname).use(
+  prism({
+    preLoad: ['java', 'scala'],
+  })
+);
 ```
+
 ## Debug
 
 To enable debug logs, set the `DEBUG` environment variable to `metalsmith-prism`:
@@ -142,16 +167,11 @@ Add `metalsmith-prism` key to your `metalsmith.json` plugins key
   }
 }
 ```
-## Credits
-
-[Robert McGuinness]( https://github.com/robmcguinness) - for the initial implementation of the plugin.
-
 
+## Credits
 
+[Robert McGuinness](https://github.com/robmcguinness) - for the initial implementation of the plugin.
 
 ## License
 
 Code released under [the MIT license](https://github.com/wernerglinka/metalsmith-prism/blob/main/LICENSE).
-
-
-

package/lib/index.js

@@ -1,71 +1,63 @@
-'use strict';
+import { load } from 'cheerio';
+import { extname } from 'path';
+import Prism from 'prismjs';
+import loadLanguages from 'prismjs/components/index.js';
+import he from 'he';
 
-const cheerio = require( 'cheerio' );
-const debug = require( 'debug' )( 'metalsmith-prism' );
-const extname = require( 'path' ).extname;
-const languages = require( 'prismjs' ).languages;
-const Prism = require( 'prismjs' );
+// Import languages from Prism's default export
+const { languages } = Prism;
 
-const loadLanguages = require( 'prismjs/components/' );
+// Preload PHP
 loadLanguages( [ 'php' ] );
 
-const he = require( 'he' );
-
+/**
+ * Check if a file is HTML
+ * @param {string} filePath
+ * @returns {boolean}
+ */
 const isHTMLFile = ( filePath ) => {
   return /\.html|\.htm/.test( extname( filePath ) );
 };
 
+/**
+ * @typedef Options
+ * @property {boolean} [decode=false] - Whether to decode HTML entities
+ * @property {boolean} [lineNumbers=false] - Whether to add line numbers
+ * @property {string[]} [preLoad=[]] - Languages to preload
+ */
 
 /**
  * Metalsmith plugin to highlight code syntax with PrismJS
  *
- * @param {Object} options
- * @returns
+ * @param {Options} [options]
+ * @returns {import('metalsmith').Plugin}
  */
-
-module.exports = ( options ) => {
-
-  options = options || {};
-
+function metalsmithPrism( options = {} ) {
   if ( options.preLoad ) {
-    //list of available languages: https://github.com/PrismJS/prism/tree/master/components
     options.preLoad.forEach( ( language ) => {
       try {
-        require( `prismjs/components/prism-${ language }.js` );
+        loadLanguages( [ language ] );
       } catch ( e ) {
-        /* eslint no-console: 0 */
-        console.warn( `Failed to preload prism syntax: ${ language } !` );
+        console.warn( `Failed to preload prism syntax: ${ language }!` );
       }
     } );
   }
 
   /**
-   * requireLanguage
    * Require optional language package
-   *
-   * @param {*} language
+   * @param {string} language
    */
   function requireLanguage( language ) {
     if ( !languages[ language ] ) {
       try {
-        require( `prismjs/components/prism-${ language }.js` );
+        loadLanguages( [ language ] );
       } catch ( e ) {
-        /* eslint no-console: 0 */
-        console.warn( `Failed to load prism syntax: ${ language } !` );
+        console.warn( `Failed to load prism syntax: ${ language }!` );
       }
     }
   }
 
-
-  /**
-   * Prism hook "after-tokenize" used to add html for line numbers
-   * Neccessary as we don't have a browser
-   *
-   * Sources:
-   * https://github.com/PrismJS/prism/blob/master/plugins/line-numbers/prism-line-numbers.js#L109
-   * https://stackoverflow.com/questions/59508413/static-html-generation-with-prismjs-how-to-enable-line-numbers
-   *
-   */
+  // Set up line numbers
   const NEW_LINE_EXP = /\n(?!$)/g;
   let lineNumbersWrapper;
 
@@ -73,22 +65,19 @@ module.exports = ( options ) => {
     const match = env.code.match( NEW_LINE_EXP );
     const linesNum = match ? match.length + 1 : 1;
     const lines = new Array( linesNum + 1 ).join( '<span></span>' );
-
     lineNumbersWrapper = `<span aria-hidden="true" class="line-numbers-rows">${ lines }</span>`;
   } );
 
   return function( files, metalsmith, done ) {
-
     setImmediate( done );
 
     Object.keys( files ).forEach( file => {
-
       if ( !isHTMLFile( file ) ) {
         return;
       }
 
       const contents = files[ file ].contents.toString();
-      const $ = cheerio.load( contents, { decodeEntities: false }, true );
+      const $ = load( contents, { decodeEntities: false } );
       let highlighted = false;
       const code = $( 'code' );
 
@@ -99,10 +88,9 @@ module.exports = ( options ) => {
 
         const className = $this.attr( 'class' ) || '';
         const targets = className.split( 'language-' );
-        let addLineNmbers = false;
+        let addLineNumbers = false;
 
         if ( targets.length > 1 ) {
-
           const $pre = $this.parent( 'pre' );
 
           if ( $pre ) {
@@ -110,9 +98,8 @@ module.exports = ( options ) => {
             $pre.addClass( className );
 
             if ( options.lineNumbers ) {
-              debug( 'adding line numbers' );
               $pre.addClass( 'line-numbers' );
-              addLineNmbers = true;
+              addLineNumbers = true;
             }
           }
 
@@ -123,10 +110,13 @@ module.exports = ( options ) => {
           if ( !languages[ language ] ) {
             language = 'markup';
           }
-          const html = ( language === 'markup' && !options.decode ) ? $this.html() : he.decode( $this.html() );
-          const highlightedCode = Prism.highlight( html, Prism.languages[ language ] );
-          $this.html( addLineNmbers ? highlightedCode + lineNumbersWrapper : highlightedCode );
 
+          const html = ( language === 'markup' && !options.decode )
+            ? $this.html()
+            : he.decode( $this.html() );
+
+          const highlightedCode = Prism.highlight( html, languages[ language ] );
+          $this.html( addLineNumbers ? highlightedCode + lineNumbersWrapper : highlightedCode );
         }
       } );
 
@@ -135,4 +125,6 @@ module.exports = ( options ) => {
       }
     } );
   };
-};
+}
+
+export default metalsmithPrism;

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "metalsmith-prism",
-  "version": "4.3.0",
+  "version": "5.0.1",
   "description": "Syntax highlighting for Metalsmith HTML templates using Prism.js",
+  "type": "module",
   "main": "lib/index.js",
+  "exports": "./lib/index.js",
   "engines": {
-    "node": ">= 14.0.0"
+    "node": ">= 18.0.0"
   },
   "scripts": {
     "preversion": "npm run test",
@@ -39,9 +41,8 @@
     "prismjs": "^1.29.0"
   },
   "devDependencies": {
-    "babel-eslint": "^7.2.3",
     "chai": "^5.1.2",
-    "eslint": "^9.14.0",
+    "eslint": "^9.15.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.2.1",
     "mocha": "^10.8.2",