Skip to navigation Skip to main content
Eleventy
Eleventy Documentation
Blog
11ty is joining Font AwesomeIndieWeb Avatar for https://fontawesome.com/
Versions
Stable
2.0.1
Toggle Menu
Compare ×4000 file build
Eleventy 1.93s
Gatsby 29.05s

Syntax Highlighting Plugin

Contents

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.

  • This documentation applies to eleventy-plugin-syntaxhighlight v3.2.0 and newer.
  • GitHub.

Installation

Available on npm.

npm install @11ty/eleventy-plugin-syntaxhighlight

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

eleventy.config.js
import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(syntaxHighlight);
};
const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(syntaxHighlight);
};

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

Expand to see Advanced Options
eleventy.config.js
import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight";

export default function(eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight, {

    // Line separator for line breaks
    lineSeparator: "\n",

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

      // Added in 4.1.0 you can use callback functions too
      "data-language": function({ language, content, options }) {
        return language;
      }
    },
    codeAttributes: {},

    // Added in 5.0.0, throw errors on invalid language names
    errorOnInvalidLanguage: false,
  });
};
const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");

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

    // Line separator for line breaks
    lineSeparator: "\n",

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

      // Added in 4.1.0 you can use callback functions too
      "data-language": function({ language, content, options }) {
        return language;
      }
    },
    codeAttributes: {},

    // Added in 5.0.0, throw errors on invalid language names
    errorOnInvalidLanguage: false,
  });
};

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

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 (triple backtick ```)
  • Liquid Custom Tag {% highlight %}
  • Nunjucks Paired Shortcode {% highlight %}
  • JavaScript Function this.highlight() Added in Syntax Highlighter v4.0.0
  • WebC component <syntax-highlight> Added in Syntax Highlighter v4.2.0

Syntax Highlight Source Code

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

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

{% highlight js %}
function myFunction() {
  return true;
}
{% endhighlight %}
{% highlight "js" %}
function myFunction() {
  return true;
}
{% endhighlight %}
export default function (data) {
	let code = `
function myFunction() {
  return true;
}`;

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

The highlight JavaScript function was Added in Syntax Highlighter v4.0.0.

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

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

The highlight JavaScript function was Added in Syntax Highlighter v4.0.0.

Syntax webc
<!-- Requires WebC v0.6.2+ -->
<!-- Requires Syntax Highlighter v4.2.0+ -->

<syntax-highlight
	language="js"
	webc:import="npm:@11ty/eleventy-plugin-syntaxhighlight"
>
	function myFunction() { return true; }
</syntax-highlight>
Expand to see an example of importing this as a global component in your configuration file.
Filename .eleventy.js
const pluginWebc = require("@11ty/eleventy-plugin-webc");

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(pluginWebc, {
		// Array `components` requires Eleventy WebC v0.9.2+
		components: [
			"_components/**/*.webc",
			"npm:@11ty/eleventy-plugin-syntaxhighlight/*.webc",
		],
	});
};
Filename page.webc
<syntax-highlight language="js">
	function myFunction() { return true; }
</syntax-highlight>
Expand to see an example of importing for use anywhere on the page via front matter.
Filename page.webc
---
webc:
  components: ./node_modules/@11ty/eleventy-plugin-syntaxhighlight/syntax-highlight.webc
---

<syntax-highlight language="js">
	function myFunction() { return true; }
</syntax-highlight>

Will render like this in the browser:

function myFunction() {
	return true;
}

Show changes using diff- syntax

Added in Syntax Highlighter v3.2.2

Add the diff- prefix to the language name on the previous examples to show code changes. Use a + or - at the beginning of the line to denote the addition or removal of that line.

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

{% highlight diff-js %}
+function myFunction() {
   // …
-  return true;
 }
{% endhighlight %}
{% highlight "diff-js" %}
+function myFunction() {
   // …
-  return true;
}
{% endhighlight %}
export default function (data) {
  let code = `
+function myFunction() {
   // …
-  return true;
 }`;

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

The highlight JavaScript function was Added in Syntax Highlighter v4.0.0.

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

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

The highlight JavaScript function was Added in Syntax Highlighter v4.0.0.

<!-- Requires WebC v0.6.2+ -->
<!-- Requires Syntax Highlighter v4.2.0+ -->

<syntax-highlight
  language="diff-js"
  webc:import="npm:@11ty/eleventy-plugin-syntaxhighlight"
>
+function myFunction() {
   // …
-  return true;
 }
</syntax-highlight>

Will render like this in the browser:

+function myFunction() {
   // …
-  return true;
 }

Alternatively, you can use diff without another language name to enable plaintext line highlighting.

Don’t forget to add styles too! Here’s a 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;
}
INFO:
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 Official Plugins: