remark-embed-tag

An elegant addition to markdown syntax to embed video/music/game/other contents from various sources.

This is a remark plugin that renders a html embed from a simple tag syntax in markdown. This tag syntax is inspired by Hexo.

This plugin can be used with Astro, Gatsby, Docusaurus and all other frameworks that support remark plugins.

Write this in your markdown file:

{% steam 1260810 %}

and it will get transformed to

<iframe
  src="https://store.steampowered.com/widget/1260810/"
  frameborder="0"
  width="100%"
  height="190"
  ...
></iframe>

Install

npm install remark-embed-tag

Features

You can see widget showcase here.

Steam

{% steam appid [optional_desc] %}

• appid (required): The Steam appid of the game.
• optional_desc (optional): The description of the game. If not provided, the game description pulled from Steam will be used.

Example:

{% steam 1260810 %}

{% steam 1260810 "This is a game I made in 2021" %}

Youtube

{% youtube youtube_id [type] [useCookies] %}

• youtube_id (required): The Youtube video/playlist id.
• type (optional): The type of the embed. Default is video. Other options are playlist.
• useCookies (optional): Whether to use cookies. Default is true. If set to false, the embed will not store cookies which enhances privacy.

Example:

{% youtube PJgEu_Ecuf8 %}

{% youtube PL17274CE9C384D8C7 "playlist" %}

{% youtube PJgEu_Ecuf8 false %}

{% youtube PL17274CE9C384D8C7 "playlist" false %}

Spotify

{% spotify spotify_id [type] %}

• spotify_id (required): The Spotify track/album/playlist id.
• type (optional): The type of the embed. Default is track. Other options are album and artist.

Example:

{% spotify 2NniAhAtkRACaMeYt48xlD %}

{% spotify 2NniAhAtkRACaMeYt48xlD "track" %}

{% spotify 1NAmidJlEaVgA3MpcPFYGq "album" %}

{% spotify 2elBjNSdBE2Y3f0j1mjrql "artist" %}

Vimeo

{% vimeo vimeo_id %}

• vimeo_id (required): The Vimeo video id.

Example:

{% vimeo 383434750 %}

JsFiddle

{% jsfiddle fiddle_id [tabs] [skin] %}

• fiddle_id (required): The JsFiddle id.
• tabs (optional): The tabs to show. Default is js,resources,html,css,result.
• skin (optional): The skin of the embed. Default is light. Other options are dark.

Example:

{% jsfiddle NmudS %}

{% jsfiddle NmudS "js,html,result" %}

{% jsfiddle NmudS "js,html,result" "dark" %}

Generic IFrame

For all other embeds, you can use the generic iframe tag.

{% iframe src %}

• src (required): The source url of the iframe.

Supporting more services!

You are welcome to PR to this repo to add more services!

If you have a service that you want to add, you can also raise an issue to request it.

Usage

With Astro

See how to integrate remark plugins with Astro here.

With Gatsby

See how to integrate remark plugins with Gatsby here.

With Docusaurus

See how to integrate remark plugins with Docusaurus here.

No framework

import remark from "remark";
import embedTag from "remark-embed-tag";

remark()
  .use(embedTag)
  .process("Hello {% steam 1260810 %}", function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

// Output: Hello <iframe src="https://store.steampowered.com/widget/1260810/" frameborder="0" height="190"></iframe>

Advanced Usage

Turn on/off Specific Transformations

Every single transformation can be individually turned on/off. This is useful when you want to use only a subset of the transformation features in this plugin.

import remark from "remark";
import embedTag from "remark-embed-tag";

remark()
  .use(embedTag, {
    steam: false,
    spotify: false,
  })
  .process("Hello {% steam 1260810 %}", function (err, file) {
    if (err) throw err;
    console.log(String(file));
  });

// Output: Hello {% steam 1260810 %}
// No transformation is done for the steam tag

Fine-tuning iframe properties

You can also control the properties on the iframe generated by the plugin. The following properties can be set:

• width
• height
• title
• frameBorder
• loading
• allowFullScreen
• allowTransparency

For example, to set the width and height of the iframe:

{% steam 1260810 %}(width=100%, height=200)

Use this plugin with OEmbed-based plugins

I recommend using this plugin along with a OEmbed-based plugin like remark-oembed as a fallback.

This way, you can have a very robust embed system, working for content that both support OEmbed (like YouTube) and those that don't (like Steam). Even for content that support OEmbed, you can use this plugin to have more control over the iframe properties.

Credits

This embed-tag syntax is inspired by Hexo's tag embed. I used to be a Hexo user and I really liked the simplicity of the embed tag. Now, I am moving to Astro and I wanted to have the same feature. Hence, I created this plugin.

While coding, I referred to the following projects:

• remark-hexo
• remark-oembed
• hexo-tag-steamgame

This package is bootstraped with typescript-npm-package-starter