Skip to main content

@mdit/plugin-embed

Embed external content in your Markdown.

Usage

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%\} %}

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.

Options

config

  • Type: EmbedConfig[]
interface EmbedConfig {
  /**
   * Embed token name
   */
  name: string;

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

  /**
   * Whether the embed can be used inline
   * @default false
   */
  allowInline?: boolean;
}
  • Default: []
  • Details: An array of embed configurations.

Each configuration must have:

  • name: The token name used in the embed syntax
  • setup: A function that takes the parameters and returns the HTML string to embed
  • allowInline: Optional, whether the embed can be used inline (defaults to false, block-level only)