wernerglinka / metalsmith-prism

Syntax highlighting for Metalsmith HTML templates using Prism.js

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.

Requirements

• Node >= 14.x.x
• NPM >= 8.x.x
• Metalsmith >= v2.4.x

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

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.

metalsmith-prism's Issues

No styles applied

Hi,

I'm sorry, I know generally github issues are not supposed to be for getting help. But I'm abit stuck here and afaik I did follow the readme steps.

I've never used prismjs, so I'm unsure this is related to metalsmith-prism at all.

• Ive installed metalsmith-prism: https://github.com/frederikprijck/blog/blob/master/package.json#L23
• added metalsmith-prism to my metalsmith build: https://github.com/frederikprijck/blog/blob/master/metalsmith.common.js#L40
• added a code block in my blog post: https://github.com/frederikprijck/blog/blob/master/src/articles/test.md

When running metalsmith, prism kicks as expected:

<code class="language-css">
  <span class="token selector">p</span> 
  <span class="token punctuation">{</span> 
  <span class="token property">color</span>
  <span class="token punctuation">:</span> red <span class="token punctuation">}</span>
</code>

and

<pre class="language-javascript line-numbers">  <code class="language-javascript">
  <span class="token keyword">const</span> someFunction <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=</span><span class="token operator">&gt;</span> <span class="token punctuation">{</span>
    console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'ok'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span><span class="token punctuation">;</span>
  </code>
</pre>

However, no styling is applied. I'm guessing I need to include themes, but as the readme doesn't mention anything I'm not sure if I need to or whether or not something is wrong in my setup.

Note: lineNumbers is set to true, but no (unstyled) line numbers are being applied neither.

---

The readme mentions:

To use with Markdown code blocks rendered by metalsmith-markdown

But it looks like doing so, doesn't change anything. So I'm not sure if this is still required when using markdown?

switch to ESLint

Tell everyone about metalsmith-prism in the metalsmith.io site

self not defined lint error in 2.0.0

node_modules\prismjs\prism.js:631
if (!self.Prism || !self.document || !document.querySelector) {
ReferenceError: self is not defined

appears self is _self but just used as self in that function

Make HTML decode configurable

I've run into an issue where the module "metalsmith-markdown" will escape the HTML characters within my code samples for me, turning < into <. However, when "metalsmith-prism" comes along and processes the same code sample, it doesn't decode the HTML entities for prism. The end result is that < turning into <, which messes up the original code sample.

I'm sure this was probably written this way for a good reason, so that's why I'm suggesting that making it configurable would at least provide a workaround to others working this way.

---

Example:

Here is some code

```markup
<html>
```

Becomes (after metalsmith-markdown)

<p>Here is some code</p>

<pre><code class="language-markup">
&lt;html&gt;
</code></pre>

Then (after metalsmith-prism)

<p>Here is some code</p>

<pre><code class="language-markup">
<span class="token entity" title="&lt;">&amp;lt;</span>html<span class="token entity" title="&gt;">&amp;gt;</span>
</code></pre>

If I remove the check for language === 'markup' check that decides on decoding, it comes out the other end correctly.

sunset support for node 10.x

Failed to load prism syntax: scala

With latest PR #20 getting the following error on npm test:

Failed to load prism syntax: scala
TypeError: Cannot set property 'keyword' of undefined
    at Object.extend (/Users/rmcguinness/Workspaces/open-source/metalsmith-prism/node_modules/prismjs/prism.js:79:15)
    at Object.<anonymous> (/Users/rmcguinness/Workspaces/open-source/metalsmith-prism/node_modules/prismjs/components/prism-scala.js:1:103)

Add support for specifying tag name

Howdy,

I've been using your metalsmith plugin, and I recently transitioned from using Markdown to using Jade for my blog post templating engine. I noticed that using the code(class='language-haskell') syntax doesn't format the code contents correctly. (It has gaps between lines). But when I use the pre(class='language-haskell') syntax, everything comes out fine. I'm not sure where this bug is happening. It looks odd in all browsers.

If there was a plugin option, say tagName that would allow one to specify the tag that they want prism to highlight, that would be great. Then you could even do something like... h1(class="language-haskell") foo bar = bar + (3 div bar) if you really wanted to.

Here's a screenshot of the odd behavior.

Using code:

Using pre:

— Taylor Zane Glaeser

Upgrade to Node 8 breaks plugin

After upgrading node to version 8 my build process breaks.

TypeError: Cannot read property 'tokenizePlaceholders' of undefined
    at /Users/.../node_modules/prismjs/components/prism-php.js:121:40
    at Object.run (/Users/.../node_modules/prismjs/prism.js:456:5)
    at Object.highlight (/Users/.../node_modules/prismjs/prism.js:287:11)
    at Object.<anonymous> (/Users/.../node_modules/metalsmith-prism/lib/index.js:94:41)
    at initialize.exports.each (/Users/.../node_modules/cheerio/lib/api/traversing.js:300:24)
    at _.each (/Users/.../node_modules/metalsmith-prism/lib/index.js:62:17)
    at /Users/.../node_modules/metalsmith-prism/node_modules/lodash/lodash.js:4917:15
    at baseForOwn (/Users/.../node_modules/metalsmith-prism/node_modules/lodash/lodash.js:3002:24)
    at /Users/.../node_modules/metalsmith-prism/node_modules/lodash/lodash.js:4886:18
    at Function.forEach (/Users/.../node_modules/metalsmith-prism/node_modules/lodash/lodash.js:9334:14)
    at Ware.<anonymous> (/Users/.../node_modules/metalsmith-prism/lib/index.js:51:7)
    at Ware.<anonymous> (/Users/.../node_modules/wrap-fn/index.js:45:19)
    at next (/Users/.../node_modules/ware/lib/index.js:85:20)
    at /Users/.../node_modules/wrap-fn/index.js:121:18
    at /Users/.../node_modules/metalsmith-in-place/node_modules/async/lib/async.js:52:16
    at done (/Users/.../node_modules/metalsmith-in-place/node_modules/async/lib/async.js:246:17)

Any idea what this could be? Any pointer is appreciated.

Having trouble getting to work with Markdown code

Hey, so I've got metalsmith-prism installed and I'm calling like so:

var metalsmith  = require('metalsmith');
var markdown  = require('metalsmith-markdown');
var prism  = require('metalsmith-prism');

metalsmith(__dirname)
  .use(markdown({
    gfm: true,
    tables: true,
    smartypants: true,
    smartLists: true,
    sanitize: false,
    langPrefix: 'language-'
  })
  .use(prism)
  .build()

But as you can see…

the code isn't getting parsed.

Any ideas? Is this a metalsmith-markdown issue?