Eleventy-plugin-embed-itch-io NPM

Getting started

NPM Version NPM License

This is a plugin for Eleventy which automatically creates an Itch.io embed widget from a URL to a game's page.

Install the latest version of this package using npm npm install eleventy-plugin-embed-itch-io

Setup

Then add it to your Eleventy config file:

const embedItchIo = require("eleventy-plugin-embed-itch-io");

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

To embed a game widget into any Markdown page, use the shortcode embedItchIo and input the URL as parameter into a new line without any other content on the same line.

Markdown example:

Playing games is almost as fun a pastime activity as making games yourself. Although very time consuming both can be very rewarding.

{% embedItchIo "https://cavaleri.itch.io/getting-around-it" %}

This game though was just as painful to play as it was to make.

Rendered result

Itch.io widget for the game: Getting Around It

Advanced usage

Configurations

The following optional configurations can be used to alter the behaviour of this plugin. To change the configuration, set the target config object when adding the plugin in your eleventy config:

eleventyConfig.addPlugin(embedItchIo, {
  darkMode: true
});

Configuration	Default	Notes
iframeClass	`'itch-io-responsive-iframe'`	Class name for the iframe widget. Useful for appending additional styles.
iframeStyle	`'position: absolute; top: 0; left: 0; bottom: 0; right: 0; width: 100%; height: 100%; max-height: 175px;`	Override the inline style for the iframe widget.
containerClass	`'itch-io-container'`	Class name for the container div. Useful for appending additional styles.
containerStyle	`'position: relative; aspect-ratio: 552 / 167; width:100%; max-height: 175px;'`	Override the inline style for the container div.
cacheDuration	`'1w'`	Cache duration. Use the cache duration syntax from @11ty/eleventy-fetch to set this value.
darkMode	`false`	Use darkmode. Adds `?dark=true` get parameter to the iframe src. See widget example for demonstration.
useTransform	`false`	Toggle the behaviour of using transform to replace an url to embed the widget.
useShortcode	`true`	Toggle the behaviour of using shortcode to embed the widget.

Responsiveness

The widget is fully responsive by utilizing the aspect-ratio css property on the container div. However, the Itch.io widget has a max height of 175px before the widget is padded with black background colour. To work around this, the container div has a max height of 175px and a width of 100% to make sure we break the aspect ratio when going above 175px;

Availability

The plugin shortcode can be used on other languages as well. However, the plugin is fetching the Itch.io details asynchronously using addAsyncShortcode which is not supported currently by Handlebars.

Nunjucks example

<body>
    <p>Playing games is almost as fun a pastime activity as making games yourself. Although very time consuming both can be very rewarding.</p>
    {% embedItchIo "https://cavaleri.itch.io/getting-around-it" %}
    <p>This game though was just as painful to play as it was to make.</p>
</body>

An alternative option to using shortcodes if to enable the useTransform option for the plugin configuration. This option will replace any instance of a link to an Itch.io game which is surrounded by its own <p></p> tags. Elventy transforms are used in this case to embed the widget, so it alters Eleventy’s HTML output as it is being generated. It does not alter the source file.

Handlebars example (with `useTransform: true`)

<body>
    <p>Playing games is almost as fun a pastime activity as making games yourself. Although very time consuming both can be very rewarding.</p>
    <p>https://cavaleri.itch.io/getting-around-it</p>
    <p>This game though was just as painful to play as it was to make.</p>
</body>

Additional notes

The plugin will require an active internet connection to embed the widget. This is due to the fact that it will query the game page to obtain the unique game ID, which in turn is used to generate the html for the embedded widget.
If there is no internet access, or the plugin fails in any other way, it will return an empty string (or the original content without any alternations in case of enabling useTransform) while logging the relevant error in console.
This plugin is deliberately designed only to embed widgets when the URL is on its own line, and not inline with other text, when the useTransform option is enabled. To do this, it uses a regular expression to recognize Itch.io game URLs. Currently these are the limitations on what it can recognize in a HTML output:
- The URL must be wrapped in a paragraph tag: <p>
- It can also be wrapped in an anchor tag, (inside the paragraph): <a>
- The URL string can have whitespace around it