Stand with Ukraine 🇺🇦
Eleventy
The possum is Eleventy’s mascot

Eleventy Documentation

This is an older version of Eleventy. Go to the newest Eleventy docs (current path: /docs/plugins/syntaxhighlight/) or the full release history.
Menu

Syntax Highlighting Plugin #

A pack of Eleventy plugins for PrismJS syntax highlighting. No browser/client JavaScript here, these highlight transformations are all done at build-time. Supports individual line highlighting.

Contents #

Installation #

Available on npm.

npm install @11ty/eleventy-plugin-syntaxhighlight --save-dev

Open up your Eleventy config file (probably .eleventy.js) and use addPlugin:

Filename .eleventy.js
const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight);
};
You’re only allowed one module.exports in your configuration file, so make sure you only copy the require and the addPlugin lines above!

You are responsible for including your favorite PrismJS theme CSS and there are many ways to do that. The default themes are provided by several CDNs and could be easily included in a base layout, like in the example below;

<html lang="en">
  <head>
    <!-- Some html boilerplate omitted -->
    <link href="https://unpkg.com/prismjs@1.20.0/themes/prism-okaidia.css" rel="stylesheet">
  </head>

You could also download the css file or paste its content inside a style tag. This approach allows the use of other themes from a Prism extension repository.

Usage #

This plugin provides the following syntax highlighters using PrismJS, all of which currently support individual line highlighting.

Markdown Highlighter #

Optionally specify a language after the start of the markdown fenced code block.

Syntax Markdown
```js
function myFunction() {
  return true;
}
```

diff- syntax #

New in Syntax Highlighter v3.2.2

Use a + or - at the beginning of the line to denote the addition or removal of that line. Alternatively, you can use diff without another syntax for plaintext line highlighting.

Syntax Markdown
```diff-js
+function myFunction() {
   // …
-  return true;
 }
```
Rendered Markdown Output
+function myFunction() {
   // …
-  return true;
 }

Liquid Shortcode #

Syntax Liquid
{% highlight js %}
function myFunction() {
  return true;
}
{% endhighlight %}

diff- syntax #

New in Syntax Highlighter v3.2.2

Use a + or - at the beginning of the line to denote the addition or removal of that line. Alternatively, you can use diff without another syntax for plaintext line highlighting.

Syntax Liquid
{% highlight diff-js %}
+function myFunction() {
   // …
-  return true;
 }
{% endhighlight %}
Rendered Liquid Output
+function myFunction() {
   // …
-  return true;
 }

Nunjucks Shortcode #

Syntax Nunjucks
{% highlight "js" %}
function myFunction() {
  return true;
}
{% endhighlight %}

diff- syntax #

New in Syntax Highlighter v3.2.2

Use a + or - at the beginning of the line to denote the addition or removal of that line. Alternatively, you can use diff without another syntax for plaintext line highlighting.

Syntax Nunjucks
{% highlight "diff-js" %}
+function myFunction() {
   // …
-  return true;
}
{% endhighlight %}
Rendered Nunjucks Output
+function myFunction() {
   // …
-  return true;
 }

JavaScript Function (for 11ty.js) #

New in Syntax Highlighter v4.0.0

Syntax 11ty.js
module.exports = function(data) {
  let code = `
function myFunction() {
  return true;
}`;

  return this.highlight("js", code);
}

diff- syntax #

New in Syntax Highlighter v4.0.0

Syntax 11ty.js
module.exports = function(data) {
  let code = `
+function myFunction() {
  // …
-  return true;
}`;

  return this.highlight("diff-js", code);
}

Sample Diff CSS #

Syntax CSS
.token.deleted {
  background-color: hsl(350deg 100% 88% / 47%);
}
.token.inserted {
  background-color: hsl(120deg 73% 75% / 35%);
}

/* Make the + and - characters unselectable for copy/paste */
.token.prefix.unchanged,
.token.prefix.inserted,
.token.prefix.deleted {
	-webkit-user-select: none;
	user-select: none;
}

/* Optional: full-width background color */
.token.inserted:not(.prefix),
.token.deleted:not(.prefix) {
	display: block;
}

Advanced Options #

Optionally pass in an options object as the second argument to addPlugin to further customize this plugin pack.

const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight, {

    // Change which Eleventy template formats use syntax highlighters
    templateFormats: ["*"], // default

    // Use only a subset of template types (11ty.js added in v4.0.0)
    // templateFormats: ["liquid", "njk", "md", "11ty.js"],

    // init callback lets you customize Prism
    init: function({ Prism }) {
      Prism.languages.myCustomLanguage = /* */;
    },

    // Added in 3.1.1, add HTML attributes to the <pre> or <code> tags
    preAttributes: {
      tabindex: 0
    },
    codeAttributes: {},
  });
};
Starting with v3.2 of this plugin, this plugin now bundles the official Prism diff-highlight plugin. The previous line highlighting feature is considered deprecated but still available. Check out the old documentation if you want to learn how to use the deprecated line-highlighting feature.

Other pages in Plugins: