@ktsn/eleventy-plugin-code-demo

Add interactive HTML/CSS/JS code demos to an Eleventy site using Markdown code blocks.

This plugin is a fork of Aleksandr Hovhannisyan's eleventy-plugin-code-demo. It adds proprocess option to support more source code types, and ESModule support for JS code blocks.

This plugin adds a paired shortcode to your 11ty site that converts HTML, CSS, and JS Markdown code blocks into an interactive iframe. It was inspired by Maciej Mionskowski's idea in the following article: Building HTML, CSS, and JS code preview using iframe's srcdoc attribute. In short, iframes don't need a src; you can define their HTML markup inline with the HTMLIFrameElement.srcdoc attribute.

Note: Never supply persistent user-generated code to this shortcode, as doing so could expose your site to XSS. In most cases, you are never going to be doing this anyway. For example, code demos that you define statically in your source files are perfectly safe.

Getting Started
Plugin Options
Shortcode Arguments
Example Usage
Use Cases and Motivation

Getting Started

Install the package:

yarn add -D @ktsn/eleventy-plugin-code-demo

const { EleventyPluginCodeDemo } = require('@ktsn/eleventy-plugin-code-demo');

eleventyConfig.addPlugin(EleventyPluginCodeDemo, {
  // Use any shortcode name you want
  name: 'shortcodeName',

  /* Render whatever document structure you want. The HTML, CSS, and JS parsed
  from the shortcode's body are supplied to this function as an argument, so
  you can position them wherever you want, or add class names or data-attributes to html/body */
  renderDocument: ({ html, css, js }) => `
  <!DOCTYPE html>
  <html>
    <head>
      <style>${css}</style>
    </head>
    <body>
      ${html}
      <script>${js}</script>
    </body>
  </html>`,

  // key-value pairs for HTML attributes; these are applied to all code previews
  iframeAttributes: {
    height: '300',
    style: 'width: 100%;',
    frameborder: '0',
  },

  // Specify preprocessors. Object key is input source type. You must return an object having
  // output `type` (either 'js', 'css' or 'html') and proprocessed `output` string.
  preprocess: {
    ts: (source) => {
      return {
        type: 'js',
        output: compileTypeScript(source),
      };
    },
  },
});

See example usage for how to use the shortcode. There's also a demo folder running a sample Eleventy project. Refer to the plugin options for more details.

Plugin Options

Name	Type	Description
`name`	`string\|undefined`	Optional. The name to use for the shortcode. Defaults to `'codeDemo'` if not specified.
`renderDocument`	`(args: { html: string; css: string; js: string }) => string`	A render function to return custom markup for the document body of each iframe. This function will be called with the HTML, CSS, and JS parsed from your shortcode's children.
`iframeAttributes`	`Record<string, unknown>\|undefined`	Optional. An object specifying attribute-value pairs that should get set globally on all code demos.
`preprocess`	`Record<string, (source: string) => PreprocessOutput\|PreprocessOutput[]>\|undefined`	Optional. An object having source type key to a function returning preprocessor output.

Shortcode Arguments

The 11ty shortcode itself accepts the following arguments:

Name	Type	Description
`source`	`string`	Implicit argument to the shortcode when you use the paired shortcode syntax in Eleventy. Contains all your Markdown code blocks.
`title`	`string`	A non-empty title for the code demo iframe. Required. Code demos without a title will throw an error.
`props`	`Record<string, unknown>`	Named keyword arguments for any HTML attributes you want to set on the iframe. See Per-Usage HTML Attributes.

Refer to example usage to see these in action.

Example Usage

The following example creates a button with some simple CSS and a click listener:

{% codeDemo 'Demo of a button that shows an alert when clicked', width="400", height="400" %}
```html
<button>Click me!</button>
```
```css
* {
  box-sizing: border-box;
  padding: 0;
  margin: 0;
}
body,
html {
  height: 100%;
}
body {
  display: grid;
  place-content: center;
}
button {
  padding: 8px;
}
```
```js
const button = document.querySelector('button');
button.addEventListener('click', () => {
  alert('hello, 11ty!');
});
```
{% endcodeDemo %}

This renders as the following interactive button:

With this output HTML:

<iframe width="400" height="400" title="Demo of a button that shows an alert when clicked" srcdoc="<!doctypehtml><style>*{box-sizing:border-box;padding:0;margin:0}body,html{height:100%}body{display:grid;place-content:center}button{padding:8px}</style><body><button>Click me!</button><script>const button=document.querySelector('button');button.addEventListener('click',()=>{alert('hello, 11ty!')})</script>"></iframe>

A couple things to note:

The order of the code blocks does not matter.
Multiple code blocks of the same type (e.g., two CSS blocks) will be merged.
A title is required for accessibility, and an error will be thrown if you do not provide one.

Interpolating Code Blocks

You could also define your code blocks separately and interpolate them. The following example uses Liquid's {% capture %} tags to do this, but you could also use Nunjucks's {% set %} to achieve the same result:

{% capture html %}
```html
<button>Click me!</button>
```
{% endcapture %}
{% capture css %}
```css
button {
  padding: 8px;
}
```
{% endcapture %}
{% capture js %}
```js
const button = document.querySelector('button');
button.addEventListener('click', () => {
  alert('hello, 11ty!');
});
```
{% endcapture %}

{% codeDemo 'Title' %}
{{ html }}
{{ css }}
{{ js }}
{% endcodeDemo %}

If you're using Nunjucks, you'll need to use the safe filter to opt out of auto-escaping the HTML.

Per-Usage HTML Attributes

As we saw, you can set HTML attributes globally on all code demos in your .eleventy.js config using the iframeAttributes option, but you can also pass in attributes on a case-by-case basis. The example below leverages Nunjucks's support for keyword arguments to create a code demo that is 400 pixels tall:

{% codeDemo 'Title', height="400" %}
```html
<button>Click me!</button>
```
{% endcodeDemo %}

If you want to pass in an HTML attribute that normally does not accept any values—like allowfullscreen—you'll need to give it a value anyway, or your template language will think you're trying to pass in a variable named allowfullscreen. So rather than doing this:

{% codeDemo 'Title', allowfullscreen %}
{% endcodeDemo %}

Do this:

{% codeDemo 'Title', allowfullscreen="true" %}
{% endcodeDemo %}

Or this:

{% codeDemo 'Title', allowfullscreen="" %}
{% endcodeDemo %}

If you're using Liquid, keep an eye on this issue for keyword-argument support: 11ty/eleventy#2679. Or see my article here: Passing Object Arguments to Liquid Shortcodes in 11ty.

ESModule Support for JavaScript Block

JavaScript block can have import and export statements. You can specify filename for each block with the format of @filename: ./name.js to import it from another code block:

{% codeDemo 'ESModule example' %}

```js
// @filename: ./test.js
export const a = 1;
```

```js
import { a } from './test.js';
console.log(a);
```

{% endcodeDemo %}

Escaping and Minification

This package uses minify-html to efficiently minify the HTML, CSS, and JavaScript markup embedded in the iframe's srcdoc attribute. It also escapes HTML to prevent breaking your layouts. This means that:

All code comments are removed.
Double quotes (") and other HTML symbols are escaped as entities (e.g., ").
CSS is minified to the extent possible.
JavaScript is minified to the extent possible.
Whitespace between tags/lines of code/attributes is removed where possible, except from within HTML attributes, within JavaScript strings, and other places where it normally appears.

Use Cases and Motivation

On my site, I wanted to be able to create isolated, independent code demos containing only the markup, styling, and interactivity that I decided to give them, without having to reset styling from my website. I could use jsFiddle or Codepen, but those services typically load third-party JavaScript and may set third-party cookies.

I could create blank pages on my site and embed them as iframes, but that feels like overkill. Plus, I wanted to be able to show my users code snippets while keeping my demos in sync with the code. Stephanie Eckles wrote about how to add static code demos to an 11ty site, but I wanted to leverage iframes to:

Avoid having to wrangle with CSS specificity, and
Be able to write custom JavaScript isolated from the rest of the page.

ktsn/eleventy-plugin-code-demo