Itch Embeds

Platen uses special notation for embedding itch.io widgets into your site with an image link.

When used, it inserts an <iframe> HTML element for your itch widget for you so you don’t have to remember how the embed URL is constructed or how to use an <iframe>.

Syntax #

Basic Block Syntax #

![itch:title](source)
{
  [#id]
  [background_color = "background_color"]
  [border_color     = "border_color"]
  [border_width     = "border_width"]
  [button_color     = "button_color"]
  [dark             = (true|false)]
  [linkback         = (true|false)]
  [preset           = "preset"]
  [square           = (true|false)]
  [text_color       = "text_color"]
}

Reference Link Block Syntax #

![itch:title][<ReferenceID>]
{
  [#id]
  [background_color = "background_color"]
  [border_color     = "border_color"]
  [border_width     = "border_width"]
  [button_color     = "button_color"]
  [dark             = (true|false)]
  [linkback         = (true|false)]
  [preset           = "preset"]
  [square           = (true|false)]
  [text_color       = "text_color"]
}

[<ReferenceID>]: source

Examples #

1. Minimal Example #

![itch:The Isle by Luke Geating](1637303)

<iframe src="https://itch.io/embed/1637303"
        title="The Isle by Luke Geating"
        frameborder="0"
        height="167"
        width="552"></iframe>

2. Square Embed with Linkback #

![itch:The Isle by Luke Geating](1637303)
{
  square   = true
  linkback = true
}

<iframe src="https://itch.io/embed/1637303?linkback=true"
        title="The Isle by Luke Geating"
        frameborder="0"
        height="167"
        width="208"></iframe>

3. Fully Custom Embed #

![itch:UNCONQUERED by Monkey's Paw Games](1765719)
{
  square           = false
  dark             = false
  linkback         = true
  background_color = "#d3d3ac"
  text_color       = "#000000"
  button_color     = "#e53b44"
  border_color     = "#fa5059"
  border_width     = 3
}

<iframe src="https://itch.io/embed/1765719?linkback=true&amp;bg_color=d3d3ac&amp;fg_color=000000&amp;link_color=e53b44&amp;border_color=fa5059&amp;border_width=3"
        title="UNCONQUERED by Monkey’s Paw Games"
        frameborder="0"
        height="167"
        width="552"></iframe>

4. Referencing preset #

![itch:](preset:UNCONQUERED)
{
  #1765719
  square=true
  border_width=5
}

<iframe src="https://itch.io/embed/1765719?linkback=true&amp;bg_color=d3d3ac&amp;fg_color=000000&amp;link_color=e53b44&amp;border_color=fa5059&amp;border_width=5"
        title="UNCONQUERED by Monkey&#39;s Paw Games"
        frameborder="0"
        height="167"
        width="208"></iframe>

Inputs #

This section describes how the normal markdown input for images works with the itch render hook.

Images use this syntax for their inputs:

![alt_text](source)

alt_text (as title) #

Specifies the title for the embed’s iframe. The title attribute is important for accessibility because it explains what the iframe leads to for folks using a screen reader.

This value must start with the prefix itch:. For example, with ![itch:My Game](12345), title’s value would be My Game.

This title can be anything you want, but it should clearly inform the site visitor about the purpose of this element. Usually, the name of the game or project is all that’s needed. If the publisher is someone else, you may want to include that information too.

Don’t use any markup for this value. The text is added to an HTML attribute, not rendered from Markdown.

If you’re using a preset that defines the title, you can omit this value except for the prefix. For example, ![itch:](MyGame) would be recognized as an itch embed but ![](MyGame) would not. If neither the image link nor the referenced preset define a title, Platen raises an error.

Specify the text without wrapping quotes, like this.

Required: true
Type: String

source (as id) #

Specify the ID for the project on itch. This is used to find and render your embed widget.

You can find the ID by navigating to the “Edit game” tab for your project on itch. The URL for that page will look like https://itch.io/game/edit/<id>. The number at the end of the URL is your project’s ID.

You can also find the ID by going to your project’s public page and clicking the “Embed” link in the list of links at the very bottom of the page. That causes a popup to appear for your embed widget. In the first line of the copyable HTML, you should see an attribute like src="https://itch.io/embed/<id>". The number at the end of that URL is your project’s ID.

Instead of specifying an itch project ID, you can specify the ID for a preset for the embed by prefixing the value with preset:. Specify the name of the preset, like ![itch:](preset:foo). If the preset is defined in a subfolder, specify the dot-path relative to data/platen/embeds/itch. For example, the preset defined in data/platen/embeds/itch/foo/bar/baz.yaml would be specified like ![button:](preset:foo.bar.baz). For more information, see Presets.

Specify the text without wrapping quotes, like this.

Required: true
Type: String

Attributes #

background_color #

Specifies the background color for the embed widget.

Specify the color as a hex value, with or without the leading #, with all six characters defined and wrapped in quotes. This value is case insensitive. For example, specify this value as "#E6E6FA" to set the color to lavender.

Required: false
Type: String

border_color #

Specifies the color of the border for the embed widget. This value is only effective when the borderWidth attribute isn’t set to 0.

Specify the color as a hex value, with or without the leading #, with all six characters defined and wrapped in quotes. This value is case insensitive. For example, specify this value as "#E6E6FA" to set the color to lavender.

Required: false
Type: String

border_width #

Specifies the width of the embed widget’s border in pixels. This value must be between 0 and 5, inclusive. When this value is 0, no border is displayed.

Required: false
Type: Int

button_color #

Specifies the background color for the purchase button on the embed widget.

Specify the color as a hex value, with or without the leading #, with all six characters defined and wrapped in quotes. This value is case insensitive. For example, specify this value as "#E6E6FA" to set the color to lavender.

Required: false
Type: String

dark #

Specifies that the embed widget should use itch’s default dark theme instead of the default light theme.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

id #

Specifies the itch project ID for the embed. This is an alternative to specifying it as the source in the image link. It’s only required when using a preset that doesn’t define the id.

Specify the ID as a bare string without any spaces and with a # prefix, like #my-id

Required: false
Type: String

linkback #

Specifies whether the project’s cover image should be a clickable link to the project page on itch. By default, the cover image isn’t a link.

This is particularly useful in combination with the square attribute, which doesn’t display the project’s linked title.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

preset #

Specifies the name of the preset to use for the embed. If the preset is defined in a subfolder, specify the dot-path relative to data/platen/embeds/itch. For example, the preset defined in data/platen/embeds/itch/foo/bar/baz.yaml would be specified like preset="foo.bar.baz". For more information, see Presets.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

square #

Specifies that the embed widget should display as a square instead of the long rectangle. In this display, only the cover is visible with the button for buying the project.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

text_color #

Specifies the text color for the embed widget. This only affects the text visible when the square isn’t set to true.

Specify the color as a hex value, with or without the leading #, with all six characters defined and wrapped in quotes. This value is case insensitive. For example, specify this value as "#E6E6FA" to set the color to lavender.

Required: false
Type: String

Presets #

To make it easier to reuse your itch embeds, you can define any number of presets in your site data. They use the same keys as the attributes.

To add a preset, create a YAML file in your site’s Data Folder as platen/embeds/itch/<ID>.yaml. For example, if your site uses the default data directory, to create a preset for UNCONQUERED you would create the file data/platen/embeds/itch/UNCONQUERED.yaml.

# data/platen/embeds/itch/UNCONQUERED.yaml
id:               1765719
title:            UNCONQUERED by Monkey's Paw Games
linkback:         true
background_color: "#d3d3ac"
text_color:       "#000000"
button_color:     "#e53b44"
border_color:     "#fa5059"
border_width:     3

You can reference a preset by specifying the preset’s file name (without the .yaml suffix) as the ID in the image link with the prefix preset:, like ![itch:](preset:UNCONQUERED).

You can override any value from the preset when you use it. If you specify a [title] in your image link, that value overwrites the one defined in the preset. Any attributes you specify also overwrite the values from the preset.

Presets can also define properties that aren’t available as attributes. The full set of properties are explained in the rest of this section.

allow #

Specifies a permissions policy for the <iframe>. The policy defines what features are available to the <iframe> (for example, access to the microphone, camera, battery, web-share, etc.) based on the origin of the request.

For more information about valid values for this setting, see Permissions Policy in the MDN web docs.

background_color #

Specifies the background color for the embed widget. Specify the color as a hex value, with or without the leading #. If you include the #, the value must be wrapped in quotes. This value is case insensitive.

These declarations for the background_color preset property are equivalent.

background_color: E6E6FA

background_color: '#E6E6FA'

border_color #

Specifies the color of the border for the embed widget. This value is only effective when the borderWidth attribute isn’t set to 0. Specify the color as a hex value, with or without the leading #. If you include the #, the value must be wrapped in quotes. This value is case insensitive.

These declarations for the border_color preset property are equivalent.

border_color: E6E6FA

border_color: '#E6E6FA'

border_width #

Specifies the width of the embed widget’s border in pixels. This value must be between 0 and 5, inclusive. When this value is 0, no border is displayed.

border_width: 3

border_width: 0

button_color #

Specifies the background color for the purchase button on the embed widget. Specify the color as a hex value, with or without the leading #. If you include the #, the value must be wrapped in quotes. This value is case insensitive.

These declarations for the button_color preset property are equivalent.

button_color: E6E6FA

button_color: '#E6E6FA'

dark #

Specifies that the embed widget should use itch’s default dark theme instead of the default light theme.

dark: true

dark: false

id #

Specifies the itch project ID for the embed. This is an alternative to specifying it as the source in the image link. It’s only required when using a preset that doesn’t define the id.

id: 12345

linkback #

Specifies whether the project’s cover image should be a clickable link to the project page on itch. By default, the cover image isn’t a link.

This is particularly useful in combination with the square attribute, which doesn’t display the project’s linked title.

linkback: true

linkback: false

loading #

Specifies how the browser should load the embed’s iframe. Set this value to lazy to defer loading of the iframe until it’s nearly in view. Set this value to eager to load the iframe immediately. The default value is eager. For more information about this attribute, see loading in the MDN web docs.

loading: eager

loading: lazy

sandbox #

Specifies extra restriction to apply to the content in the embed’s iframe. If this value is specified as an empty list ([]), it applies all restrictions. If this value is an list of valid values, those values are added to the allow list.

For more information about iframe sandboxes and the list of valid exception values, see sandbox in the MDN web docs.

sandbox: []

sandbox:
  - allow-scripts
  - allow-popups

square #

Specifies that the embed widget should display as a square instead of the long rectangle. In this display, only the cover is visible with the button for buying the project.

square: true

square: false

text_color #

Specifies the text color for the embed widget. This only affects the text visible when the square isn’t set to true. Specify the color as a hex value, with or without the leading #. If you include the #, the value must be wrapped in quotes. This value is case insensitive.

These declarations for the text_color preset property are equivalent.

text_color: E6E6FA

text_color: '#E6E6FA'

title #

Specifies the title for the embed’s iframe. The title attribute is important for accessibility because it explains what the iframe leads to for folks using a screen reader.

This title can be anything you want, but it should clearly inform the site visitor about the purpose of this element. Usually, the name of the game or project is all that’s needed. If the publisher is someone else, you may want to include that information too.

Don’t use any markup for this value. The text is added to an HTML attribute, not rendered from Markdown.

title: UNCONQUERED by Monkey's Paw Games

Configuration #

Several of the options for this markup can be configured in your site configuration or Platen’s parameter data. The most convenient option is to edit the data/_params/platen/markup.yaml file. Every configuration setting can by overridden by the attributes in your markup or properties in a preset.

The default values for this markup’s rendering options are defined below:

itch:
  dark:     false
  linkback: false
  square:   false

dark

If you want to default your itch embeds to using the dark theme, set this value to true. The dark attribute and preset property override this configuration setting.

linkback

If you want to default your itch embeds to including a link to the project’s page on its cover image, set this value to true. The linkbackattribute and preset property override this configuration setting.

square

If you want to default your itch embeds to display as squares with the cover image and purchase button, set this value to true. The square attribute and preset property override this configuration setting.