@riebeckite/plugin-shortcodes 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Rerurate_514
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,110 @@
+# @riebeckite/plugin-shortcodes
+
+A generic shortcode system for Markdown, built on `remark-directive`.
+
+[日本語](./README_ja.md)
+
+## Overview
+
+`shortcodes()` turns `remark-directive` syntax into HTML at Markdown time.
+It supports 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.
+
+Output is rendered into `mdast` `html` nodes and wrapped in a `span` (leaf) or
+`div` (container) carrying `rb-shortcode rb-shortcode--<name>`.
+
+## Usage
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { shortcodes } from "@riebeckite/plugin-shortcodes";
+
+export default defineConfig({
+  // ...
+  plugins: [shortcodes()],
+});
+```
+
+Styles ship in `style.css`.
+
+## Syntax
+
+```
+::kbd[Ctrl+S]
+
+::youtube[id=dQw4w9WgXcQ]
+
+:::note[Heads up]{type=warning}
+Container bodies support **Markdown**.
+:::
+```
+
+- `::name[label]{key=value}` — leaf shortcode, rendered inline.
+- `:::name[label]{key=value}` … `:::` — container shortcode; the body is
+  rendered by the normal Markdown pipeline.
+
+Unknown shortcodes emit a `shortcodes-unknown` diagnostic and stay on the page
+as escaped text. Malformed attributes emit `shortcodes-invalid` and are
+ignored.
+
+## Built-in shortcodes
+
+| Name | Kind | Attributes | Output |
+| ---- | ---- | ---------- | ------ |
+| `figure` | leaf / container | `src`/`url`/`image`, `alt`, `caption`, `width`, `height` | `<figure>` with image and caption |
+| `youtube` | leaf | `id`/`video` or `url`/`src`, `title` | Privacy-friendly `youtube-nocookie.com` embed |
+| `vimeo` | leaf | `id`/`video` or `url`/`src`, `title` | `player.vimeo.com` embed (`dnt=1`) |
+| `gist` | leaf | `user` + `id`, or `url`, `file` | GitHub Gist embed with `<noscript>` link |
+| `kbd` | leaf | label or `keys` | `<kbd>` elements split on `+` |
+| `badge` | leaf | label or `text`, `variant`/`type`/`color`, `title` | Inline badge |
+| `details` | container | label or `summary`, `open` | `<details>` disclosure |
+| `spoiler` | container | label or `summary`, `open` | `details` alias with a different class |
+| `note` | leaf / container | label or `title`, `type`/`variant` | Callout box |
+| `callout` | leaf / container | label or `title`, `type`/`variant` | `note` alias with a different class |
+| `link-card` | leaf | `url`/`href`, `title`, `description`, `image`/`icon` | Link preview card |
+| `file` | leaf | `url`/`src`/`path`, `name`/`label`, `size` | Download link |
+
+## Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `className` | `string` | `"rb-shortcode"` | Root CSS class of every wrapper |
+| `language` | `string` | – | BCP-47 tag applied to wrappers as `lang` |
+| `builtins` | `boolean` | `true` | Register the built-in renderers |
+| `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | Custom renderers, merged over the built-ins |
+
+## Custom renderers
+
+```ts
+import { shortcodes } from "@riebeckite/plugin-shortcodes";
+
+shortcodes({
+  shortcodes: {
+    mark: ({ label, attributes }) => `<mark>${label}</mark>`,
+  },
+});
+```
+
+A `ShortcodeRenderer` receives `{ name, label, attributes, childrenHtml,
+context, container }` and returns a string. 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
+- Types: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
+  `ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
+  `RemarkShortcodesOptions`
+
+## See also
+
+- [Plugin guide](../../docs/plugins_en.md)

package/README_ja.md

@@ -0,0 +1,111 @@
+# @riebeckite/plugin-shortcodes
+
+`remark-directive` を土台にした汎用ショートコード機能です。
+
+[English](./README.md)
+
+## 概要
+
+`shortcodes()` は `remark-directive` の記法を Markdown 処理時に HTML へ変換
+します。リーフ型（`::name[label]{key=value}`）とコンテナ型
+（`:::name[label]{attrs}` … `:::`）の両方に対応し、組み込みレンダラーに
+独自のレンダラーを重ねられる拡張可能なレジストリを備えます。
+
+出力は `mdast` の `html` ノードとして書き出され、リーフは `span`、コンテナは
+`div` で `rb-shortcode rb-shortcode--<name>` を付けてラップされます。
+
+## 使い方
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { shortcodes } from "@riebeckite/plugin-shortcodes";
+
+export default defineConfig({
+  // ...
+  plugins: [shortcodes()],
+});
+```
+
+スタイルは `style.css` に同梱されています。
+
+## 記法
+
+```
+::kbd[Ctrl+S]
+
+::youtube[id=dQw4w9WgXcQ]
+
+:::note[補足]{type=warning}
+コンテナの本文では **Markdown** が使えます。
+:::
+```
+
+- `::name[label]{key=value}` — リーフ型。インラインで描画されます。
+- `:::name[label]{key=value}` … `:::` — コンテナ型。本文は通常の Markdown
+  パイプラインで描画されます。
+
+未知のショートコードは `shortcodes-unknown` 診断を出し、エスケープした
+テキストとしてページに残します。不正な属性は `shortcodes-invalid` を出して
+無視します。
+
+## 組み込みショートコード
+
+| 名前 | 種類 | 属性 | 出力 |
+| ---- | ---- | ---- | ---- |
+| `figure` | リーフ / コンテナ | `src`/`url`/`image`, `alt`, `caption`, `width`, `height` | 画像とキャプションの `<figure>` |
+| `youtube` | リーフ | `id`/`video` または `url`/`src`, `title` | `youtube-nocookie.com` のプライバシー配慮埋め込み |
+| `vimeo` | リーフ | `id`/`video` または `url`/`src`, `title` | `player.vimeo.com` 埋め込み（`dnt=1`） |
+| `gist` | リーフ | `user` + `id`、または `url`, `file` | `<noscript>` リンク付きの Gist 埋め込み |
+| `kbd` | リーフ | ラベルまたは `keys` | `+` で分割した `<kbd>` |
+| `badge` | リーフ | ラベルまたは `text`, `variant`/`type`/`color`, `title` | インラインバッジ |
+| `details` | コンテナ | ラベルまたは `summary`, `open` | `<details>` 折りたたみ |
+| `spoiler` | コンテナ | ラベルまたは `summary`, `open` | クラス違いの `details` エイリアス |
+| `note` | リーフ / コンテナ | ラベルまたは `title`, `type`/`variant` | コールアウト |
+| `callout` | リーフ / コンテナ | ラベルまたは `title`, `type`/`variant` | クラス違いの `note` エイリアス |
+| `link-card` | リーフ | `url`/`href`, `title`, `description`, `image`/`icon` | リンクプレビューカード |
+| `file` | リーフ | `url`/`src`/`path`, `name`/`label`, `size` | ダウンロードリンク |
+
+## オプション
+
+| オプション | 型 | 既定値 | 説明 |
+| ---------- | -- | ------ | ---- |
+| `className` | `string` | `"rb-shortcode"` | すべてのラッパーのルート CSS クラス |
+| `language` | `string` | – | ラッパーの `lang` に付与する BCP-47 タグ |
+| `builtins` | `boolean` | `true` | 組み込みレンダラーを登録する |
+| `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | 組み込みに重ねる独自レンダラー |
+
+## 独自レンダラー
+
+```ts
+import { shortcodes } from "@riebeckite/plugin-shortcodes";
+
+shortcodes({
+  shortcodes: {
+    mark: ({ label, attributes }) => `<mark>${label}</mark>`,
+  },
+});
+```
+
+`ShortcodeRenderer` は `{ name, label, attributes, childrenHtml, context,
+container }` を受け取り、文字列を返します。コンテナ型では結果が
+`<div class="rb-shortcode rb-shortcode--<name>">` でラップされ、
+`childrenHtml` の位置に本文が差し込まれます。コンテナ用レンダラーは本文を
+置きたい位置で `input.childrenHtml` をそのまま出力してください。レンダラーは
+同期関数で、ユーザー入力のエスケープは各自で行う必要があります
+（`@riebeckite/core` の `escapeHtml` / `escapeHtmlAttribute` を再エクスポート
+しています）。
+
+## エクスポート
+
+- `shortcodes(options?)` / `shortcodesPlugin` — プラグインファクトリ
+- `remarkShortcodes(options?)` — 単体で使える remark トランスフォーム
+- `renderShortcode(request, options)` — 単一ショートコードの描画
+- `resolveShortcodeOptions(options?)` — オプションの正規化
+- `builtinShortcodes`, `builtinShortcodeNames` — 組み込みレジストリ
+- 型: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
+  `ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
+  `RemarkShortcodesOptions`
+
+## 関連
+
+- [プラグインガイド](../../docs/plugins_ja.md)

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { builtinShortcodeNames, builtinShortcodes } from "./src/builtins.js";
+import { DEFAULT_SHORTCODE_CLASS_NAME, SHORTCODE_CHILDREN_MARKER, createShortcodeRenderContext, renderShortcode, resolveShortcodeOptions } from "./src/render.js";
+import { DIAGNOSTIC_INVALID, DIAGNOSTIC_UNKNOWN, SHORTCODES_SOURCE, remarkShortcodes } from "./src/remark.js";
+import type { ShortcodeOptions } from "./src/types.js";
+export type { DirectiveNode, RemarkShortcodesOptions, ResolvedShortcodeOptions, ShortcodeAttributes, ShortcodeOptions, ShortcodeRenderInput, ShortcodeRenderer, ShortcodeRenderRequest, } from "./src/types.js";
+export { builtinShortcodeNames, builtinShortcodes };
+export { DEFAULT_SHORTCODE_CLASS_NAME, SHORTCODE_CHILDREN_MARKER, createShortcodeRenderContext, renderShortcode, resolveShortcodeOptions, };
+export { DIAGNOSTIC_INVALID, DIAGNOSTIC_UNKNOWN, SHORTCODES_SOURCE, remarkShortcodes, };
+export declare function shortcodes(options?: ShortcodeOptions): import("@riebeckite/core").RiebeckitePlugin<ShortcodeOptions>;
+export declare const shortcodesPlugin: typeof shortcodes;

package/dist/index.js

@@ -0,0 +1,509 @@
+// index.ts
+import { createStyleAsset, definePlugin } from "@riebeckite/core";
+
+// src/builtins.ts
+import { escapeHtml, escapeHtmlAttribute } from "@riebeckite/core";
+var YOUTUBE_ID_PATTERN = /(?:youtu\.be\/|v=|embed\/|shorts\/|live\/)([A-Za-z0-9_-]{6,})/;
+var VIMEO_ID_PATTERN = /vimeo\.com\/(?:video\/)?(\d+)/;
+var GIST_URL_PATTERN = /gist\.github\.com\/([^/]+)\/([0-9a-f]+)/i;
+var KEY_TOKEN_PATTERN = /[^a-z0-9-]+/g;
+function first(attributes, keys) {
+  for (const key of keys) {
+    const value = attributes[key];
+    if (value !== void 0 && value !== "") return value;
+  }
+  return "";
+}
+function token(value, fallback) {
+  const normalized = value.toLowerCase().replace(KEY_TOKEN_PATTERN, "-").replace(/^-+|-+$/g, "");
+  return normalized || fallback;
+}
+function renderFigure(input) {
+  const source = first(input.attributes, ["src", "url", "image", "path"]);
+  const caption = first(input.attributes, ["caption"]) || input.label;
+  const alt = first(input.attributes, ["alt"]) || caption;
+  const body = input.childrenHtml ?? "";
+  if (!source) {
+    return `<span class="rb-shortcode__figure-fallback">${escapeHtml(
+      caption || "figure"
+    )}</span>`;
+  }
+  const width = first(input.attributes, ["width"]);
+  const height = first(input.attributes, ["height"]);
+  const dimension = (width ? ` width="${escapeHtmlAttribute(width)}"` : "") + (height ? ` height="${escapeHtmlAttribute(height)}"` : "");
+  const captionHtml = caption ? `<figcaption class="rb-shortcode__caption">${escapeHtml(
+    caption
+  )}</figcaption>` : "";
+  return `<figure class="rb-shortcode__figure">
+  <img class="rb-shortcode__image" src="${escapeHtmlAttribute(
+    source
+  )}" alt="${escapeHtmlAttribute(alt)}"${dimension} loading="lazy" decoding="async">
+  ${body}
+  ${captionHtml}
+</figure>`;
+}
+function renderYouTube(input) {
+  const id = first(input.attributes, ["id", "video"]) || (first(input.attributes, ["url", "src"]).match(YOUTUBE_ID_PATTERN)?.[1] ?? "");
+  if (!id) {
+    return `<span class="rb-shortcode__video-fallback">${escapeHtml(
+      input.label || "youtube"
+    )}</span>`;
+  }
+  const title = first(input.attributes, ["title"]) || input.label || "YouTube video";
+  return `<div class="rb-shortcode__video">
+  <iframe class="rb-shortcode__iframe" src="https://www.youtube-nocookie.com/embed/${escapeHtmlAttribute(
+    id
+  )}" title="${escapeHtmlAttribute(
+    title
+  )}" loading="lazy" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+</div>`;
+}
+function renderVimeo(input) {
+  const id = first(input.attributes, ["id", "video"]) || (first(input.attributes, ["url", "src"]).match(VIMEO_ID_PATTERN)?.[1] ?? "");
+  if (!id) {
+    return `<span class="rb-shortcode__video-fallback">${escapeHtml(
+      input.label || "vimeo"
+    )}</span>`;
+  }
+  const title = first(input.attributes, ["title"]) || input.label || "Vimeo video";
+  return `<div class="rb-shortcode__video">
+  <iframe class="rb-shortcode__iframe" src="https://player.vimeo.com/video/${escapeHtmlAttribute(
+    id
+  )}?dnt=1" title="${escapeHtmlAttribute(
+    title
+  )}" loading="lazy" allow="fullscreen; picture-in-picture" allowfullscreen></iframe>
+</div>`;
+}
+function renderGist(input) {
+  let user = first(input.attributes, ["user", "username"]);
+  let id = first(input.attributes, ["id", "gist"]);
+  if (!user || !id) {
+    const match = first(input.attributes, ["url", "src"]).match(
+      GIST_URL_PATTERN
+    );
+    if (match) {
+      user = match[1];
+      id = match[2];
+    }
+  }
+  if (!user || !id) {
+    return `<span class="rb-shortcode__gist-fallback">${escapeHtml(
+      input.label || "gist"
+    )}</span>`;
+  }
+  const label = input.label || "Gist";
+  const gistUrl = `https://gist.github.com/${escapeHtmlAttribute(
+    user
+  )}/${escapeHtmlAttribute(id)}`;
+  const file = first(input.attributes, ["file"]);
+  const scriptUrl = `${gistUrl}.js${file ? `?file=${escapeHtmlAttribute(file)}` : ""}`;
+  return `<div class="rb-shortcode__gist">
+  <script src="${scriptUrl}"></script>
+  <noscript><a class="rb-shortcode__gist-link" href="${gistUrl}">${escapeHtml(
+    label
+  )}</a></noscript>
+</div>`;
+}
+function renderKbd(input) {
+  const keys = input.label || first(input.attributes, ["keys", "key", "text"]) || "";
+  const parts = keys.split("+").map((part) => part.trim());
+  return parts.filter((part) => part.length > 0).map(
+    (part) => `<kbd class="rb-shortcode__kbd">${escapeHtml(part)}</kbd>`
+  ).join('<span class="rb-shortcode__kbd-separator">+</span>');
+}
+function renderBadge(input) {
+  const label = input.label || first(input.attributes, ["text", "label"]) || "badge";
+  const variant = token(
+    first(input.attributes, ["variant", "type", "color"]),
+    "default"
+  );
+  const title = first(input.attributes, ["title"]);
+  const titleAttribute = title ? ` title="${escapeHtmlAttribute(title)}"` : "";
+  return `<span class="rb-shortcode__badge rb-shortcode__badge--${escapeHtmlAttribute(
+    variant
+  )}"${titleAttribute}>${escapeHtml(label)}</span>`;
+}
+function renderDetails(defaultSummary) {
+  return (input) => {
+    const summary = input.label || first(input.attributes, ["summary"]) || defaultSummary;
+    const open = first(input.attributes, ["open"]) !== "" && first(input.attributes, ["open"]) !== "false" ? " open" : "";
+    return `<details class="rb-shortcode__details"${open}>
+  <summary class="rb-shortcode__summary">${escapeHtml(summary)}</summary>
+  <div class="rb-shortcode__details-body">${input.childrenHtml ?? ""}</div>
+</details>`;
+  };
+}
+function renderNote(defaultType) {
+  return (input) => {
+    const type = token(
+      first(input.attributes, ["type", "variant"]) || defaultType,
+      defaultType
+    );
+    const title = first(input.attributes, ["title"]) || (input.container ? input.label : "");
+    const heading = title ? `<p class="rb-shortcode__note-title">${escapeHtml(title)}</p>` : "";
+    const body = input.childrenHtml ?? (input.label && !input.container ? `<p class="rb-shortcode__note-text">${escapeHtml(input.label)}</p>` : "");
+    return `<div class="rb-shortcode__note rb-shortcode__note--${escapeHtmlAttribute(
+      type
+    )}">
+  ${heading}
+  <div class="rb-shortcode__note-body">${body}</div>
+</div>`;
+  };
+}
+function renderLinkCard(input) {
+  const url = first(input.attributes, ["url", "href"]);
+  if (!url) {
+    return `<span class="rb-shortcode__link-card-fallback">${escapeHtml(
+      input.label || "link-card"
+    )}</span>`;
+  }
+  const title = first(input.attributes, ["title"]) || input.label || url;
+  const description = first(input.attributes, ["description"]);
+  const image = first(input.attributes, ["image", "icon"]);
+  const imageHtml = image ? `<img class="rb-shortcode__link-card-image" src="${escapeHtmlAttribute(
+    image
+  )}" alt="" loading="lazy" decoding="async">` : "";
+  const descriptionHtml = description ? `<span class="rb-shortcode__link-card-description">${escapeHtml(
+    description
+  )}</span>` : "";
+  return `<a class="rb-shortcode__link-card" href="${escapeHtmlAttribute(
+    url
+  )}" target="_blank" rel="noopener noreferrer">
+  ${imageHtml}
+  <span class="rb-shortcode__link-card-body">
+    <span class="rb-shortcode__link-card-title">${escapeHtml(title)}</span>
+    ${descriptionHtml}
+    <span class="rb-shortcode__link-card-url">${escapeHtml(url)}</span>
+  </span>
+</a>`;
+}
+function renderFile(input) {
+  const url = first(input.attributes, ["url", "src", "path", "href"]);
+  const label = first(input.attributes, ["name", "label"]) || input.label || url;
+  if (!url) {
+    return `<span class="rb-shortcode__file-fallback">${escapeHtml(
+      label || "file"
+    )}</span>`;
+  }
+  const size = first(input.attributes, ["size", "bytes"]);
+  const sizeHtml = size ? `<span class="rb-shortcode__file-size">${escapeHtml(size)}</span>` : "";
+  return `<a class="rb-shortcode__file" href="${escapeHtmlAttribute(
+    url
+  )}" download>
+  <span class="rb-shortcode__file-name">${escapeHtml(label)}</span>
+  ${sizeHtml}
+</a>`;
+}
+var builtinShortcodes = {
+  figure: renderFigure,
+  youtube: renderYouTube,
+  vimeo: renderVimeo,
+  gist: renderGist,
+  kbd: renderKbd,
+  badge: renderBadge,
+  details: renderDetails("Details"),
+  spoiler: renderDetails("Spoiler"),
+  note: renderNote("note"),
+  callout: renderNote("callout"),
+  "link-card": renderLinkCard,
+  file: renderFile
+};
+var builtinShortcodeNames = Object.keys(
+  builtinShortcodes
+);
+
+// src/render.ts
+import {
+  createUnavailableGeneratedOutputSink,
+  escapeHtmlAttribute as escapeHtmlAttribute2,
+  NoopLogger,
+  NoopTracer
+} from "@riebeckite/core";
+var DEFAULT_SHORTCODE_CLASS_NAME = "rb-shortcode";
+var SHORTCODE_CHILDREN_MARKER = "\0rb-shortcodes:children\0";
+var UNAVAILABLE_CACHE = {
+  async get() {
+    return void 0;
+  },
+  async set() {
+  },
+  async delete() {
+  },
+  async clear() {
+  }
+};
+function resolveShortcodeOptions(options = {}) {
+  const builtins = options.builtins !== false;
+  const custom = options.shortcodes ?? {};
+  const shortcodes2 = builtins ? { ...builtinShortcodes, ...custom } : { ...custom };
+  const resolved = {
+    className: options.className ?? DEFAULT_SHORTCODE_CLASS_NAME,
+    builtins,
+    shortcodes: shortcodes2
+  };
+  if (options.language !== void 0) resolved.language = options.language;
+  return resolved;
+}
+function createShortcodeRenderContext(input) {
+  return {
+    contentIndex: input.contentIndex ?? /* @__PURE__ */ new Map(),
+    diagnostics: [],
+    cache: UNAVAILABLE_CACHE,
+    output: createUnavailableGeneratedOutputSink(),
+    logger: new NoopLogger(),
+    tracer: new NoopTracer(),
+    contentSource: input.contentSource,
+    kind: `shortcode:${input.name}`,
+    path: `shortcode:${input.name}`,
+    raw: input.raw ?? input.label ?? "",
+    label: input.label ?? "",
+    url: input.url ?? "",
+    embed: false
+  };
+}
+function renderShortcode(request, options) {
+  const renderer = options.shortcodes[request.name];
+  if (!renderer) return "";
+  const attributes = request.attributes ?? {};
+  const context = request.context ?? createShortcodeRenderContext({
+    name: request.name,
+    label: request.label,
+    raw: request.label,
+    url: firstUrl(attributes)
+  });
+  const container = request.container ?? false;
+  const input = {
+    name: request.name,
+    label: request.label ?? "",
+    attributes,
+    context,
+    container
+  };
+  if (request.childrenHtml !== void 0) {
+    input.childrenHtml = request.childrenHtml;
+  }
+  const body = renderer(input);
+  return wrapShortcode(body, request.name, container, options);
+}
+function wrapShortcode(body, name, container, options) {
+  const tag = container ? "div" : "span";
+  const classes = `${options.className} ${options.className}--${name}`;
+  const languageAttribute = options.language === void 0 ? "" : ` lang="${escapeHtmlAttribute2(options.language)}"`;
+  return `<${tag} class="${escapeHtmlAttribute2(
+    classes
+  )}"${languageAttribute}>${body}</${tag}>`;
+}
+function firstUrl(attributes) {
+  for (const key of ["url", "src", "href", "path"]) {
+    const value = attributes[key];
+    if (value !== void 0 && value !== "") return value;
+  }
+  return "";
+}
+
+// src/remark.ts
+import { escapeHtml as escapeHtml2, escapeHtmlAttribute as escapeHtmlAttribute3 } from "@riebeckite/core";
+import { visit } from "unist-util-visit";
+var SHORTCODES_SOURCE = "@riebeckite/plugin-shortcodes";
+var DIAGNOSTIC_UNKNOWN = "shortcodes-unknown";
+var DIAGNOSTIC_INVALID = "shortcodes-invalid";
+var ATTRIBUTE_NAME_PATTERN = /^[A-Za-z_][\w-]*$/;
+function remarkShortcodes(options = {}) {
+  const resolved = resolveShortcodeOptions(options);
+  return (tree, file) => {
+    const targets = [];
+    visit(
+      tree,
+      ["containerDirective", "leafDirective"],
+      (node, index, parent) => {
+        if (parent === void 0 || index === void 0) return;
+        targets.push({ node, index, parent });
+      }
+    );
+    for (const target of targets.reverse()) {
+      transformDirective(target, resolved, options, file);
+    }
+  };
+}
+function transformDirective(target, resolved, options, file) {
+  const { node, index, parent } = target;
+  const name = node.name;
+  const container = node.type === "containerDirective";
+  const { label, children } = extractLabel(node);
+  const attributes = normalizeAttributes(node, file);
+  const childrenHtml = container ? SHORTCODE_CHILDREN_MARKER : void 0;
+  const html = renderShortcode(
+    {
+      name,
+      label,
+      attributes,
+      childrenHtml,
+      container,
+      context: createShortcodeRenderContext({
+        name,
+        label,
+        raw: label,
+        url: firstUrl2(attributes),
+        contentIndex: options.contentIndex,
+        contentSource: options.contentSource
+      })
+    },
+    resolved
+  );
+  if (!html) {
+    report(
+      file,
+      DIAGNOSTIC_UNKNOWN,
+      `Unknown shortcode "::${name}" was left as escaped text.`,
+      node
+    );
+    parent.children.splice(
+      index,
+      1,
+      ...createFallback(resolved.className, name, label, attributes, container, children)
+    );
+    return;
+  }
+  if (!container) {
+    parent.children.splice(index, 1, createHtml(html));
+    return;
+  }
+  const [before, after] = splitOnChildren(html);
+  parent.children.splice(
+    index,
+    1,
+    createHtml(before),
+    ...children,
+    createHtml(after)
+  );
+}
+function splitOnChildren(html) {
+  if (html.includes(SHORTCODE_CHILDREN_MARKER)) {
+    const [before, ...rest] = html.split(SHORTCODE_CHILDREN_MARKER);
+    return [before, rest.join(SHORTCODE_CHILDREN_MARKER)];
+  }
+  const closeIndex = html.lastIndexOf("</div>");
+  if (closeIndex < 0) return [html, ""];
+  return [html.slice(0, closeIndex), html.slice(closeIndex)];
+}
+function extractLabel(node) {
+  if (node.type === "containerDirective") {
+    const [firstChild, ...rest] = node.children;
+    if (isDirectiveLabel(firstChild)) {
+      return { label: textContent(firstChild), children: rest };
+    }
+    return { label: "", children: node.children };
+  }
+  return { label: textContent(node), children: [] };
+}
+function isDirectiveLabel(node) {
+  if (node === null || typeof node !== "object") return false;
+  const candidate = node;
+  return candidate.type === "paragraph" && candidate.data?.directiveLabel === true;
+}
+function textContent(node) {
+  if (node === null || typeof node !== "object") return "";
+  const value = node.value;
+  if (typeof value === "string") return value;
+  const children = node.children;
+  if (!Array.isArray(children)) return "";
+  return children.map((child) => textContent(child)).join("");
+}
+function normalizeAttributes(node, file) {
+  const raw = node.attributes ?? {};
+  const attributes = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value !== "string" || !ATTRIBUTE_NAME_PATTERN.test(key)) {
+      report(
+        file,
+        DIAGNOSTIC_INVALID,
+        `Ignoring malformed attribute "${key}" on shortcode "::${node.name}".`,
+        node
+      );
+      continue;
+    }
+    attributes[key] = value;
+  }
+  return attributes;
+}
+function createFallback(className, name, label, attributes, container, children) {
+  const classes = `${className} ${className}--unknown`;
+  const dataName = ` data-shortcode-name="${escapeHtmlAttribute3(name)}"`;
+  const directive = escapeHtml2(sourceText(name, label, attributes, container));
+  if (container) {
+    return [
+      createHtml(
+        `<div class="${escapeHtmlAttribute3(classes)}"${dataName}>${directive}`
+      ),
+      ...children,
+      createHtml("</div>")
+    ];
+  }
+  return [
+    createHtml(
+      `<span class="${escapeHtmlAttribute3(classes)}"${dataName}>${directive}</span>`
+    )
+  ];
+}
+function sourceText(name, label, attributes, container) {
+  const fence = container ? ":::" : "::";
+  const labelPart = label ? `[${label}]` : "";
+  return `${fence}${name}${labelPart}${attributesText(attributes)}`;
+}
+function attributesText(attributes) {
+  const entries = Object.entries(attributes);
+  if (entries.length === 0) return "";
+  const body = entries.map(([key, value]) => `${key}="${value}"`).join(" ");
+  return `{${body}}`;
+}
+function firstUrl2(attributes) {
+  for (const key of ["url", "src", "href", "path"]) {
+    const value = attributes[key];
+    if (value !== void 0 && value !== "") return value;
+  }
+  return "";
+}
+function report(file, ruleId, reason, node) {
+  const target = file;
+  target?.message(reason, {
+    place: node,
+    ruleId,
+    source: SHORTCODES_SOURCE
+  });
+}
+function createHtml(value) {
+  return { type: "html", value };
+}
+
+// index.ts
+var PLUGIN_NAME = "shortcodes";
+function shortcodes(options = {}) {
+  return definePlugin({
+    name: PLUGIN_NAME,
+    options,
+    extendMarkdownPipeline: (pipeline, context) => {
+      pipeline.use(remarkShortcodes, {
+        ...options,
+        contentIndex: context.contentIndex,
+        contentSource: context.contentSource
+      });
+    },
+    assets: [createStyleAsset(PLUGIN_NAME)]
+  });
+}
+var shortcodesPlugin = shortcodes;
+export {
+  DEFAULT_SHORTCODE_CLASS_NAME,
+  DIAGNOSTIC_INVALID,
+  DIAGNOSTIC_UNKNOWN,
+  SHORTCODES_SOURCE,
+  SHORTCODE_CHILDREN_MARKER,
+  builtinShortcodeNames,
+  builtinShortcodes,
+  createShortcodeRenderContext,
+  remarkShortcodes,
+  renderShortcode,
+  resolveShortcodeOptions,
+  shortcodes,
+  shortcodesPlugin
+};

package/dist/src/builtins.d.ts

@@ -0,0 +1,4 @@
+import type { ShortcodeRenderInput } from "./types.js";
+/** Built-in renderers keyed by directive name. */
+export declare const builtinShortcodes: Record<string, (input: ShortcodeRenderInput) => string>;
+export declare const builtinShortcodeNames: readonly string[];

package/dist/src/remark.d.ts

@@ -0,0 +1,6 @@
+import type { Root } from "mdast";
+import type { RemarkShortcodesOptions } from "./types.js";
+export declare const SHORTCODES_SOURCE = "@riebeckite/plugin-shortcodes";
+export declare const DIAGNOSTIC_UNKNOWN = "shortcodes-unknown";
+export declare const DIAGNOSTIC_INVALID = "shortcodes-invalid";
+export declare function remarkShortcodes(options?: RemarkShortcodesOptions): (tree: Root, file: unknown) => void;

package/dist/src/render.d.ts

@@ -0,0 +1,19 @@
+import type { ContentSource, PluginRenderContext } from "@riebeckite/core";
+import type { ResolvedShortcodeOptions, ShortcodeOptions, ShortcodeRenderRequest } from "./types.js";
+export declare const DEFAULT_SHORTCODE_CLASS_NAME = "rb-shortcode";
+/**
+ * Sentinel echoed through {@link ShortcodeRenderInput.childrenHtml}. The remark
+ * transform splits the rendered wrapper on this marker and splices the real
+ * container body in its place.
+ */
+export declare const SHORTCODE_CHILDREN_MARKER = "\0rb-shortcodes:children\0";
+export declare function resolveShortcodeOptions(options?: ShortcodeOptions): ResolvedShortcodeOptions;
+export declare function createShortcodeRenderContext(input: {
+    name: string;
+    label?: string;
+    raw?: string;
+    url?: string;
+    contentIndex?: Map<string, string>;
+    contentSource?: ContentSource;
+}): PluginRenderContext;
+export declare function renderShortcode(request: ShortcodeRenderRequest, options: ResolvedShortcodeOptions): string;

package/dist/src/types.d.ts

@@ -0,0 +1,64 @@
+import type { ContentSource, PluginRenderContext } from "@riebeckite/core";
+import type { Parent } from "mdast";
+/**
+ * Attributes parsed from a directive's `{ ... }` block. Values are always
+ * strings; shorthand `#id` / `.class` syntax is expanded by `remark-directive`.
+ */
+export type ShortcodeAttributes = Record<string, string>;
+/**
+ * Input passed to a {@link ShortcodeRenderer}.
+ *
+ * `childrenHtml` is present for container shortcodes. It contains a sentinel
+ * that the renderer must place where the container body belongs; the plugin
+ * swaps the sentinel for the rendered children. Renderers that need the body
+ * must echo `input.childrenHtml` verbatim.
+ */
+export type ShortcodeRenderInput = {
+    name: string;
+    label: string;
+    attributes: ShortcodeAttributes;
+    childrenHtml?: string;
+    context: PluginRenderContext;
+    container: boolean;
+};
+export type ShortcodeRenderer = (input: ShortcodeRenderInput) => string;
+export type ShortcodeOptions = {
+    /** Root CSS class applied to every wrapper. Defaults to `rb-shortcode`. */
+    className?: string;
+    /** Optional BCP-47 language tag applied to wrappers as `lang`. */
+    language?: string;
+    /** Register the built-in shortcode renderers. Defaults to `true`. */
+    builtins?: boolean;
+    /** Custom renderers, merged on top of the built-ins by name. */
+    shortcodes?: Record<string, ShortcodeRenderer>;
+};
+export type ResolvedShortcodeOptions = {
+    className: string;
+    language?: string;
+    builtins: boolean;
+    shortcodes: Record<string, ShortcodeRenderer>;
+};
+/** Input accepted by {@link renderShortcode}. */
+export type ShortcodeRenderRequest = {
+    name: string;
+    label?: string;
+    attributes?: ShortcodeAttributes;
+    childrenHtml?: string;
+    container?: boolean;
+    context?: PluginRenderContext;
+};
+/**
+ * Options for the standalone remark transform. It mirrors
+ * {@link ShortcodeOptions} and additionally forwards pipeline state so the
+ * render context handed to renderers can expose the content index.
+ */
+export type RemarkShortcodesOptions = ShortcodeOptions & {
+    contentIndex?: Map<string, string>;
+    contentSource?: ContentSource;
+};
+export type DirectiveName = "leafDirective" | "containerDirective";
+export type DirectiveNode = Parent & {
+    type: DirectiveName;
+    name: string;
+    attributes?: Record<string, unknown>;
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@riebeckite/plugin-shortcodes",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "@types/mdast": "^4.0.4",
+    "unist-util-visit": "^5.1.0",
+    "@riebeckite/core": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/shortcodes"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Remark directive shortcodes for Riebeckite Markdown.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "shortcodes",
+    "remark"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs"
+  }
+}

package/style.css

@@ -0,0 +1,252 @@
+.rb-shortcode {
+  --rb-shortcode-accent: var(--rb-color-accent, #686868);
+  --rb-shortcode-ink: var(--rb-color-ink, #1a1a1a);
+  --rb-shortcode-rule: color-mix(
+    in srgb,
+    var(--rb-shortcode-ink) 20%,
+    transparent
+  );
+  --rb-shortcode-surface: color-mix(
+    in srgb,
+    var(--rb-shortcode-ink) 5%,
+    transparent
+  );
+}
+
+div.rb-shortcode {
+  display: block;
+  margin-block: 1.25rem;
+}
+
+/* figure ------------------------------------------------------------------ */
+
+.rb-shortcode__figure {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin: 0;
+}
+
+.rb-shortcode__image {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border: 1px solid var(--rb-shortcode-rule);
+}
+
+.rb-shortcode__caption {
+  color: var(--rb-shortcode-accent);
+  font-size: 0.875em;
+  line-height: 1.7;
+}
+
+.rb-shortcode__figure-fallback,
+.rb-shortcode__video-fallback,
+.rb-shortcode__gist-fallback,
+.rb-shortcode__link-card-fallback,
+.rb-shortcode__file-fallback {
+  color: var(--rb-shortcode-accent);
+  font-style: italic;
+}
+
+/* video ------------------------------------------------------------------- */
+
+.rb-shortcode__video {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 1px solid var(--rb-shortcode-rule);
+  background: var(--rb-shortcode-surface);
+}
+
+.rb-shortcode__iframe {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+/* gist -------------------------------------------------------------------- */
+
+.rb-shortcode__gist {
+  overflow: hidden;
+  border: 1px solid var(--rb-shortcode-rule);
+}
+
+/* keyboard ---------------------------------------------------------------- */
+
+.rb-shortcode__kbd {
+  display: inline-block;
+  padding: 0.1em 0.4em;
+  border: 1px solid var(--rb-shortcode-rule);
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  background: var(--rb-shortcode-surface);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.85em;
+  line-height: 1.4;
+}
+
+.rb-shortcode__kbd-separator {
+  margin-inline: 0.15em;
+  color: var(--rb-shortcode-accent);
+}
+
+/* badge ------------------------------------------------------------------- */
+
+.rb-shortcode__badge {
+  display: inline-block;
+  padding: 0.1em 0.5em;
+  border: 1px solid currentcolor;
+  border-radius: 999px;
+  color: var(--rb-shortcode-accent);
+  font-size: 0.75em;
+  line-height: 1.6;
+  vertical-align: middle;
+}
+
+.rb-shortcode__badge--info {
+  color: #0b6bcb;
+}
+
+.rb-shortcode__badge--success {
+  color: #1a7f37;
+}
+
+.rb-shortcode__badge--warning {
+  color: #9a6700;
+}
+
+.rb-shortcode__badge--danger {
+  color: #cf222e;
+}
+
+/* details / spoiler ------------------------------------------------------- */
+
+.rb-shortcode__details {
+  border: 1px solid var(--rb-shortcode-rule);
+}
+
+.rb-shortcode__summary {
+  padding: 0.5rem 0.75rem;
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.rb-shortcode__details-body {
+  padding: 0.25rem 0.75rem 0.75rem;
+}
+
+/* note / callout ---------------------------------------------------------- */
+
+.rb-shortcode__note {
+  padding: 0.75rem 1rem;
+  border-left: 4px solid var(--rb-shortcode-accent);
+  background: var(--rb-shortcode-surface);
+}
+
+.rb-shortcode__note-title {
+  margin: 0 0 0.35rem;
+  font-weight: 700;
+}
+
+.rb-shortcode__note-body > :first-child,
+.rb-shortcode__details-body > :first-child {
+  margin-top: 0;
+}
+
+.rb-shortcode__note-body > :last-child,
+.rb-shortcode__details-body > :last-child {
+  margin-bottom: 0;
+}
+
+.rb-shortcode__note--tip {
+  border-left-color: #1a7f37;
+}
+
+.rb-shortcode__note--warning {
+  border-left-color: #9a6700;
+}
+
+.rb-shortcode__note--danger {
+  border-left-color: #cf222e;
+}
+
+/* link card --------------------------------------------------------------- */
+
+.rb-shortcode__link-card {
+  display: flex;
+  gap: 0.75rem;
+  padding: 0.75rem;
+  border: 1px solid var(--rb-shortcode-rule);
+  color: inherit;
+  text-decoration: none;
+}
+
+.rb-shortcode__link-card:hover,
+.rb-shortcode__link-card:focus-visible {
+  border-color: var(--rb-shortcode-accent);
+}
+
+.rb-shortcode__link-card-image {
+  width: 96px;
+  height: 96px;
+  flex: none;
+  object-fit: cover;
+}
+
+.rb-shortcode__link-card-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  min-width: 0;
+}
+
+.rb-shortcode__link-card-title {
+  font-weight: 700;
+}
+
+.rb-shortcode__link-card-description,
+.rb-shortcode__link-card-url {
+  color: var(--rb-shortcode-accent);
+  font-size: 0.875em;
+  line-height: 1.6;
+}
+
+.rb-shortcode__link-card-url {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* file -------------------------------------------------------------------- */
+
+.rb-shortcode__file {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.35rem 0.75rem;
+  border: 1px solid var(--rb-shortcode-rule);
+  color: inherit;
+  text-decoration: none;
+}
+
+.rb-shortcode__file:hover,
+.rb-shortcode__file:focus-visible {
+  border-color: var(--rb-shortcode-accent);
+}
+
+.rb-shortcode__file-size {
+  color: var(--rb-shortcode-accent);
+  font-size: 0.8125em;
+}
+
+/* fallback ---------------------------------------------------------------- */
+
+.rb-shortcode--unknown {
+  color: var(--rb-shortcode-accent);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.875em;
+}