@r4ai/remark-embed

A remark plugin to embed the content of the URL.

Features

• Embed website using oEmbed by transformerOEmbed
  • YouTube
  • Spotify
  • SpeakerDeck
  • ...
• Generate link card using Open Graph metadata by transformerLinkCard
  • Twitter
  • Facebook
  • ...
• Fully customizable with transformers
  • You can define your own transformer

About this plugin

This plugin rewrite a paragraph containing only a URL, such as the following, into any element through the transformer.

https://example.com/hoge

[!note] Note that URLs such as the following will not be converted:

• according to https://example.com/hoge
• [example](https://example.com/hoge)

URL must be the only content in the paragraph.

Also, if there is no blank line before and after the paragraph, it will not be converted.

Transformer

Currently, this plugin provides the following transformers:

• transformerOEmbed - embeds the URL content by fetching the oEmbed metadata
• transformerLinkCard - generates a link card by fetching the Open Graph metadata

You can also define your own transformer. Please refer to the transformer in the ./src/transformers directory for details on how to define them.

Following is the algorithm of how this plugin will apply the transformers.

1. let elements be a list of link nodes such that each node's parent paragraph contains only one link
   Example: elements = [{ type: 'link', url: 'https://example.com/hoge' }]
2. for each element of elements, do the following in parallel:
   1. let url be the element's url value.
   2. for each transformer of transformers, do the following in sequence:
      1. if transformer.match(url) is true:
         1. replace the element's tag name with the result of transformer.tagName(url)
         2. replace the element's properties with the result of transformer.properties(url)
         3. replace the element's children with the result of transformer.children(url)

Installation

• Bun:

  bun add @r4ai/remark-embed

• Deno:

  deno add @r4ai/remark-embed

• NPM:

  npm install @r4ai/remark-embed

• PNPM:

  pnpm add @r4ai/remark-embed

• Yarn:

  yarn add @r4ai/remark-embed

Usage

import rehypeStringify from "rehype-stringify";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
import remarkEmbed from "@r4ai/remark-embed";
import { transformerOEmbed } from "@r4ai/remark-embed/transformers";

const md = `
<https://www.youtube.com/watch?v=jNQXAC9IVRw>
`;

const html = (
  await unified()
    .use(remarkParse)
    .use(remarkRehype)
    .use(remarkEmbed, {
      transformers: [transformerOEmbed()],
    })
    .use(rehypeStringify)
    .process(md)
).toString();

console.log(html);

Yields:

<p>
  <div class="oembed oembed-video">
    <iframe
      width="200"
      height="150"
      src="https://www.youtube.com/embed/jNQXAC9IVRw?feature=oembed"
      frameborder="0"
      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
      referrerpolicy="strict-origin-when-cross-origin"
      allowfullscreen
      title="Me at the zoo">
    </iframe>
  </div>
</p>

Documentation

See: https://jsr.io/@r4ai/remark-embed/doc