@mdit/plugin-embed

Embed external content in your Markdown.

Usage

import { embed } from "@mdit/plugin-embed";
import MarkdownIt from "markdown-it";

const md = new MarkdownIt().use(embed, {
  config: [
    {
      name: "youtube",
      setup: (id: string) =>
        `<iframe width="560" height="315" src="https://www.youtube.com/embed/${id}" frameborder="0" allowfullscreen></iframe>`,
    },
    {
      name: "icon",
      allowInline: true,
      setup: (name: string) => `<i class="icon icon-${name}"></i>`,
    },
  ],
});

import { embed } from "@mdit/plugin-embed";
import MarkdownIt from "markdown-it";

const md = new MarkdownIt().use(embed, {
  config: [
    {
      name: "youtube",
      setup: (id) =>
        `<iframe width="560" height="315" src="https://www.youtube.com/embed/${id}" frameborder="0" allowfullscreen></iframe>`,
    },
    {
      name: "icon",
      allowInline: true,
      setup: (name) => `<i class="icon icon-${name}"></i>`,
    },
  ],
});

Syntax

The plugin parses embed syntax in the format:

{% name params %}

Where:

name is the embed type identifier
params are the parameters passed to the setup function

Escaping

To escape the embed syntax, use a backslash before the opening/closing brace:

\{% name params %}

You can also escape these markers in contents:

\{% name params-containing-\{%value%\} %}

Options

configRequiredEmbedConfig[]

An array of embed configurations.

interface EmbedConfig {
  /** Embed token name */
  name: string;

  /**
   * Setup function to generate embed HTML
   *
   * @param ref
   * @param isInline If `allowInline` is true, `isInline` represent that current matched content is
   *   inline
   * @returns
   */
  setup: (ref: string, isInline: boolean) => string;

  /**
   * Whether the embed can be used inline
   *
   * @default false
   */
  allowInline?: boolean;
}

config.namestring

The token name used in the embed syntax.

config.setup(ref: string, isInline: boolean) => string

A function that takes the parameters and returns the HTML string to embed.

config.allowInlineboolean

Defaultfalse

Whether the embed can be used inline. It is block-level only when set to false.

Examples

With usage example, the following embeds are supported:

Input:

{% youtube dQw4w9WgXcQ %}

Output:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  frameborder="0"
  allowfullscreen
></iframe>

Input:

Click the {% icon home %} button to go home.

Output:

Click the <i class="icon icon-home"></i> button to go home.