Shortcodes

A generic shortcode system for Markdown, built on remark-directive.

日本語

Overview

shortcodes() turns remark-directive syntax into HTML at Markdown time. It supports inline shortcodes (:name[label]{key=value}), block leaf shortcodes (::name[label]{key=value}), and container shortcodes (:::name[label]{attrs} … :::), and ships an extensible registry so projects can add their own renderers on top of the built-ins.

Inline shortcodes render as a span inside the surrounding paragraph; block and container shortcodes render as a div. Every wrapper carries rb-shortcode rb-shortcode--<name>.

Usage

import { defineConfig } from "@riebeckite/core";
import { shortcodes } from "@riebeckite/plugin-shortcodes";
 
export default defineConfig({
  // ...
  plugins: [shortcodes()],
});

Styles ship in style.css.

Syntax

:badge[New]{variant=success}
 
::kbd[Ctrl+S]
 
::youtube[id=dQw4w9WgXcQ]
 
:::note[Heads up]{type=warning}
Container bodies support **Markdown**.
:::

• :name[label]{key=value} — inline shortcode, rendered as a span inside the current paragraph. Only names in inlineShortcodes can be used inline; built-ins opt in with badge, kbd, link-card, and file.
• ::name[label]{key=value} — block leaf shortcode, rendered as a div.
• :::name[label]{key=value} … ::: — container shortcode; the body is rendered by the normal Markdown pipeline.

A shortcode that is only defined as a block emits a shortcodes-inline-unsupported diagnostic when written with : and stays on the page as escaped text. Unknown shortcodes emit a shortcodes-unknown diagnostic, and malformed attributes emit shortcodes-invalid and are ignored.

Built-in shortcodes

Options

Custom renderers

import { shortcodes } from "@riebeckite/plugin-shortcodes";
 
shortcodes({
  shortcodes: {
    mark: ({ label, attributes }) => `<mark>${label}</mark>`,
  },
  inlineShortcodes: ["mark"],
});

A ShortcodeRenderer receives { name, label, attributes, childrenHtml, context, container } and returns a string. A custom renderer can be used with the inline : form only when its name is listed in inlineShortcodes. For container shortcodes the plugin wraps the result in <div class="rb-shortcode rb-shortcode--<name>"> and replaces childrenHtml with the rendered body, so container renderers must echo input.childrenHtml where the body belongs. Renderers are synchronous and must escape any user input themselves — escapeHtml and escapeHtmlAttribute are re-exported from @riebeckite/core.

Exports

• shortcodes(options?) / shortcodesPlugin — plugin factory
• remarkShortcodes(options?) — standalone remark transform
• renderShortcode(request, options) — render a single shortcode
• resolveShortcodeOptions(options?) — normalize options
• builtinShortcodes, builtinShortcodeNames — the built-in registry
• builtinInlineShortcodes — built-in names allowed in the inline : form
• Types: ShortcodeRenderer, ShortcodeOptions, ResolvedShortcodeOptions, ShortcodeRenderInput, ShortcodeRenderRequest, ShortcodeAttributes, RemarkShortcodesOptions

See also

• Plugin guide