@riebeckite/plugin-shortcodes 0.0.19 → 0.0.21

package/README.md

@@ -6,13 +6,15 @@ A generic shortcode system for Markdown, built on `remark-directive`.
 
 ## 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.
+`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.
 
-Output is rendered into `mdast` `html` nodes and wrapped in a `span` (leaf) or
-`div` (container) carrying `rb-shortcode rb-shortcode--<name>`.
+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
 
@@ -31,6 +33,8 @@ Styles ship in `style.css`.
 ## Syntax
 
 ```
+:badge[New]{variant=success}
+
 ::kbd[Ctrl+S]
 
 ::youtube[id=dQw4w9WgXcQ]
@@ -40,30 +44,206 @@ Container bodies support **Markdown**.
 :::
 ```
 
-- `::name[label]{key=value}` — leaf shortcode, rendered inline.
+- `: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.
 
-Unknown shortcodes emit a `shortcodes-unknown` diagnostic and stay on the page
-as escaped text. Malformed attributes emit `shortcodes-invalid` and are
-ignored.
+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
 
-| 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 |
+| Name | Kind | Inline | 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 | yes | label or `keys` | `<kbd>` elements split on `+` |
+| `badge` | leaf | yes | 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 | yes | `url`/`href`, `title`, `description`, `image`/`icon` | Link preview card |
+| `file` | leaf | yes | `url`/`src`/`path`, `name`/`label`, `size` | Download link |
+
+## Actual Rendering
+
+The following examples demonstrate all 12 built-in shortcodes. Each example shows the Markdown syntax followed by the shortcode itself, allowing you to see how it renders when the Shortcodes plugin is enabled.
+
+### Badge
+
+Display status indicators or labels inline with text.
+
+```md
+This feature is :badge[New]{variant=success}.
+
+Current status: :badge[Beta]{variant=warning}
+```
+
+This feature is :badge[New]{variant=success}.
+
+Current status: :badge[Beta]{variant=warning}
+
+### Keyboard (kbd)
+
+Display keyboard shortcuts using semantic `<kbd>` elements.
+
+```md
+Press :kbd[Ctrl+S] to save your changes.
+
+Use :kbd[Ctrl+K] to open search.
+```
+
+Press :kbd[Ctrl+S] to save your changes.
+
+Use :kbd[Ctrl+K] to open search.
+
+### Note
+
+Highlight useful information, tips, and other supplementary content.
+
+```md
+:::note[Tip]{type=info}
+You can use **Markdown** inside this container.
+
+- Lists
+- **Bold text**
+- [Links](https://example.com)
+:::
+```
+
+:::note[Tip]{type=info}
+You can use **Markdown** inside this container.
+
+- Lists
+- **Bold text**
+- [Links](https://example.com)
+:::
+
+### Callout
+
+Display important notices or warnings. `callout` is an alias of `note` with a different CSS class.
+
+```md
+:::callout[Warning]{type=warning}
+Remember to rebuild your site after changing the configuration file.
+:::
+```
+
+:::callout[Warning]{type=warning}
+Remember to rebuild your site after changing the configuration file.
+:::
+
+### Details
+
+Create collapsible sections that users can expand to reveal additional content.
+
+```md
+:::details[Show details]
+This content is hidden until the section is expanded.
+
+You can include **Markdown** and lists:
+
+- Item A
+- Item B
+:::
+```
+
+:::details[Show details]
+This content is hidden until the section is expanded.
+
+You can include **Markdown** and lists:
+
+- Item A
+- Item B
+:::
+
+### Spoiler
+
+Hide content behind an expandable section. `spoiler` works like `details` but uses a different CSS class.
+
+```md
+:::spoiler[Reveal spoiler]
+The hidden content appears when the user expands this section.
+
+**Markdown** is supported here too.
+:::
+```
+
+:::spoiler[Reveal spoiler]
+The hidden content appears when the user expands this section.
+
+**Markdown** is supported here too.
+:::
+
+### Figure
+
+Display images with optional captions and dimensions using semantic `<figure>` markup.
+
+```md
+::figure[Sample image]{src="https://placehold.co/800x400/png" alt="Sample placeholder image" caption="Figure 1: Example image"}
+```
+
+::figure[Sample image]{src="https://placehold.co/800x400/png" alt="Sample placeholder image" caption="Figure 1: Example image"}
+
+### YouTube
+
+Embed YouTube videos using the privacy-enhanced `youtube-nocookie.com` domain.
+
+```md
+::youtube[id=dQw4w9WgXcQ]
+```
+
+::youtube[id=dQw4w9WgXcQ]
+
+### Vimeo
+
+Embed Vimeo videos with the `dnt=1` privacy parameter.
+
+```md
+::vimeo[id=76979871]
+```
+
+::vimeo[id=76979871]
+
+### GitHub Gist
+
+Embed GitHub Gist code snippets directly into a page. A fallback link is provided for environments where JavaScript is disabled.
+
+```md
+::gist{user=octocat id=aa5a315d61ae9438b18d}
+```
+
+::gist{user=octocat id=aa5a315d61ae9438b18d}
+
+### Link Card
+
+Display external links as preview cards with titles and descriptions.
+
+```md
+::link-card[GitHub]{url="https://github.com" title="GitHub" description="A platform for hosting code and collaborating on software projects"}
+```
+
+::link-card[GitHub]{url="https://github.com" title="GitHub" description="A platform for hosting code and collaborating on software projects"}
+
+### File
+
+Create downloadable file links with optional filenames and file sizes.
+
+```md
+::file[Sample PDF]{url="https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" name="sample.pdf" size="13 KB"}
+```
+
+::file[Sample PDF]{url="https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" name="sample.pdf" size="13 KB"}
+
+The code blocks above show the original Markdown syntax. The shortcode expressions immediately below them serve as live rendering examples when processed by Riebeckite with the Shortcodes plugin enabled.
 
 ## Options
 
@@ -73,6 +253,7 @@ ignored.
 | `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 |
+| `inlineShortcodes` | `readonly string[]` | `[]` | Extra names allowed in the inline `:` form |
 
 ## Custom renderers
 
@@ -83,16 +264,19 @@ shortcodes({
   shortcodes: {
     mark: ({ label, attributes }) => `<mark>${label}</mark>`,
   },
+  inlineShortcodes: ["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`.
+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
 
@@ -101,11 +285,11 @@ re-exported from `@riebeckite/core`.
 - `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](../../../docs/docs/reference/plugin-api.en.md)
-
+- [Plugin guide](../../../docs/docs/reference/plugin-api.md)

package/README_ja.md

@@ -7,12 +7,13 @@
 ## 概要
 
 `shortcodes()` は `remark-directive` の記法を Markdown 処理時に HTML へ変換
-します。リーフ型（`::name[label]{key=value}`）とコンテナ型
-（`:::name[label]{attrs}` … `:::`）の両方に対応し、組み込みレンダラーに
-独自のレンダラーを重ねられる拡張可能なレジストリを備えます。
+します。インライン型（`:name[label]{key=value}`）、ブロックのリーフ型
+（`::name[label]{key=value}`）、コンテナ型（`:::name[label]{attrs}` … `:::`）
+に対応し、組み込みレンダラーに独自のレンダラーを重ねられる拡張可能な
+レジストリを備えます。
 
-出力は `mdast` の `html` ノードとして書き出され、リーフは `span`、コンテナは
-`div` で `rb-shortcode rb-shortcode--<name>` を付けてラップされます。
+インライン型は段落の中の `span` として、リーフ型とコンテナ型は `div` として
+描画されます。ラッパーには `rb-shortcode rb-shortcode--<name>` が付きます。
 
 ## 使い方
 
@@ -31,6 +32,8 @@ export default defineConfig({
 ## 記法
 
 ```
+:badge[新着]{variant=success}
+
 ::kbd[Ctrl+S]
 
 ::youtube[id=dQw4w9WgXcQ]
@@ -40,30 +43,206 @@ export default defineConfig({
 :::
 ```
 
-- `::name[label]{key=value}` — リーフ型。インラインで描画されます。
+- `:name[label]{key=value}` — インライン型。現在の段落の中の `span` として
+  描画されます。インラインで使えるのは `inlineShortcodes` に含まれる名前だけ
+  で、組み込みでは `badge`、`kbd`、`link-card`、`file` が該当します。
+- `::name[label]{key=value}` — ブロックのリーフ型。`div` として描画されます。
 - `:::name[label]{key=value}` … `:::` — コンテナ型。本文は通常の Markdown
   パイプラインで描画されます。
 
-未知のショートコードは `shortcodes-unknown` 診断を出し、エスケープした
-テキストとしてページに残します。不正な属性は `shortcodes-invalid` を出して
-無視します。
+ブロック専用のショートコードを `:` で書くと
+`shortcodes-inline-unsupported` 診断を出し、エスケープしたテキストとして
+ページに残します。未知のショートコードは `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` | ダウンロードリンク |
+| 名前 | 種類 | インライン | 属性 | 出力 |
+| ---- | ---- | ---------- | ---- | ---- |
+| `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` | ダウンロードリンク |
+
+## 実際のレンダリング
+
+以下の例では、組み込みショートコード全12種類の使い方を紹介します。各例では Markdown の記法と、その直下にショートコード自体を記載しています。Shortcodes プラグインが有効な場合、実際のレンダリング結果を確認できます。
+
+### バッジ（badge）
+
+文章の途中にステータスやラベルを表示できます。
+
+```md
+この機能は :badge[新着]{variant=success} です。
+
+現在の状態: :badge[ベータ版]{variant=warning}
+```
+
+この機能は :badge[新着]{variant=success} です。
+
+現在の状態: :badge[ベータ版]{variant=warning}
+
+### キーボード（kbd）
+
+キーボードショートカットを意味的に適切な `<kbd>` 要素で表示できます。
+
+```md
+変更を保存するには :kbd[Ctrl+S] を押してください。
+
+検索を開くには :kbd[Ctrl+K] を使用します。
+```
+
+変更を保存するには :kbd[Ctrl+S] を押してください。
+
+検索を開くには :kbd[Ctrl+K] を使用します。
+
+### ノート（note）
+
+ヒントや補足情報などを目立たせて表示できます。
+
+```md
+:::note[ヒント]{type=info}
+このコンテナ内では **Markdown** を使用できます。
+
+- リスト
+- **太字**
+- [リンク](https://example.com)
+:::
+```
+
+:::note[ヒント]{type=info}
+このコンテナ内では **Markdown** を使用できます。
+
+- リスト
+- **太字**
+- [リンク](https://example.com)
+:::
+
+### コールアウト（callout）
+
+重要な通知や警告を表示できます。`callout` は `note` のエイリアスで、異なる CSS クラスが適用されます。
+
+```md
+:::callout[注意]{type=warning}
+設定ファイルを変更した場合は、サイトを再ビルドしてください。
+:::
+```
+
+:::callout[注意]{type=warning}
+設定ファイルを変更した場合は、サイトを再ビルドしてください。
+:::
+
+### 折りたたみ（details）
+
+クリックすると追加のコンテンツを展開できるセクションを作成できます。
+
+```md
+:::details[詳細を表示]
+このコンテンツは、セクションを展開するまで非表示になります。
+
+**Markdown** やリストも使用できます。
+
+- 項目 A
+- 項目 B
+:::
+```
+
+:::details[詳細を表示]
+このコンテンツは、セクションを展開するまで非表示になります。
+
+**Markdown** やリストも使用できます。
+
+- 項目 A
+- 項目 B
+:::
+
+### スポイラー（spoiler）
+
+コンテンツを折りたたみセクション内に隠せます。`spoiler` は `details` と同様に動作しますが、異なる CSS クラスが適用されます。
+
+```md
+:::spoiler[ネタバレを表示]
+ユーザーがこのセクションを展開すると、隠されたコンテンツが表示されます。
+
+ここでも **Markdown** を使用できます。
+:::
+```
+
+:::spoiler[ネタバレを表示]
+ユーザーがこのセクションを展開すると、隠されたコンテンツが表示されます。
+
+ここでも **Markdown** を使用できます。
+:::
+
+### 画像（figure）
+
+意味的に適切な `<figure>` 要素を使用して、キャプションやサイズを指定した画像を表示できます。
+
+```md
+::figure[サンプル画像]{src="https://placehold.co/800x400/png" alt="サンプルのプレースホルダー画像" caption="Figure 1: 画像の表示例"}
+```
+
+::figure[サンプル画像]{src="https://placehold.co/800x400/png" alt="サンプルのプレースホルダー画像" caption="Figure 1: 画像の表示例"}
+
+### YouTube
+
+プライバシーに配慮した `youtube-nocookie.com` ドメインを使用して、YouTube 動画を埋め込めます。
+
+```md
+::youtube[id=dQw4w9WgXcQ]
+```
+
+::youtube[id=dQw4w9WgXcQ]
+
+### Vimeo
+
+`dnt=1` プライバシーパラメータを使用して、Vimeo 動画を埋め込めます。
+
+```md
+::vimeo[id=76979871]
+```
+
+::vimeo[id=76979871]
+
+### GitHub Gist
+
+GitHub Gist のコードスニペットをページ内に直接埋め込めます。JavaScript が無効な環境では、代替リンクが提供されます。
+
+```md
+::gist{user=octocat id=aa5a315d61ae9438b18d}
+```
+
+::gist{user=octocat id=aa5a315d61ae9438b18d}
+
+### リンクカード（link-card）
+
+外部リンクをタイトルや説明付きのプレビューカードとして表示できます。
+
+```md
+::link-card[GitHub]{url="https://github.com" title="GitHub" description="コードのホスティングとソフトウェア開発の共同作業を行うためのプラットフォーム"}
+```
+
+::link-card[GitHub]{url="https://github.com" title="GitHub" description="コードのホスティングとソフトウェア開発の共同作業を行うためのプラットフォーム"}
+
+### ファイル（file）
+
+ファイル名やサイズを指定したダウンロードリンクを作成できます。
+
+```md
+::file[サンプルPDF]{url="https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" name="sample.pdf" size="13 KB"}
+```
+
+::file[サンプルPDF]{url="https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf" name="sample.pdf" size="13 KB"}
+
+上記のコードブロックは元の Markdown 記法を示しています。その直下のショートコードは、Shortcodes プラグインを有効にした Riebeckite で処理された際の、実際のレンダリングを確認するための例です。
 
 ## オプション
 
@@ -73,6 +252,7 @@ export default defineConfig({
 | `language` | `string` | – | ラッパーの `lang` に付与する BCP-47 タグ |
 | `builtins` | `boolean` | `true` | 組み込みレンダラーを登録する |
 | `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | 組み込みに重ねる独自レンダラー |
+| `inlineShortcodes` | `readonly string[]` | `[]` | インラインの `:` 形式で使える名前に追加する |
 
 ## 独自レンダラー
 
@@ -83,12 +263,14 @@ shortcodes({
   shortcodes: {
     mark: ({ label, attributes }) => `<mark>${label}</mark>`,
   },
+  inlineShortcodes: ["mark"],
 });
 ```
 
 `ShortcodeRenderer` は `{ name, label, attributes, childrenHtml, context,
-container }` を受け取り、文字列を返します。コンテナ型では結果が
-`<div class="rb-shortcode rb-shortcode--<name>">` でラップされ、
+container }` を受け取り、文字列を返します。独自レンダラーをインラインの `:`
+形式で使うには、その名前を `inlineShortcodes` に追加します。コンテナ型では
+結果が `<div class="rb-shortcode rb-shortcode--<name>">` でラップされ、
 `childrenHtml` の位置に本文が差し込まれます。コンテナ用レンダラーは本文を
 置きたい位置で `input.childrenHtml` をそのまま出力してください。レンダラーは
 同期関数で、ユーザー入力のエスケープは各自で行う必要があります
@@ -102,11 +284,11 @@ container }` を受け取り、文字列を返します。コンテナ型では
 - `renderShortcode(request, options)` — 単一ショートコードの描画
 - `resolveShortcodeOptions(options?)` — オプションの正規化
 - `builtinShortcodes`, `builtinShortcodeNames` — 組み込みレジストリ
+- `builtinInlineShortcodes` — インラインの `:` 形式で使える組み込み名
 - 型: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
   `ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
   `RemarkShortcodesOptions`
 
 ## 関連
 
-- [プラグインガイド](../../../docs/docs/reference/plugin-api.md)
-
+- [プラグインガイド](../../../docs/docs/reference/plugin-api.ja.md)

package/dist/index.d.ts

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

package/dist/index.js

@@ -206,6 +206,12 @@ var builtinShortcodes = {
   "link-card": renderLinkCard,
   file: renderFile
 };
+var builtinInlineShortcodes = [
+  "badge",
+  "kbd",
+  "link-card",
+  "file"
+];
 var builtinShortcodeNames = Object.keys(builtinShortcodes);
 
 // src/remark.ts
@@ -236,14 +242,24 @@ function resolveShortcodeOptions(options = {}) {
   const builtins = options.builtins !== false;
   const custom = options.shortcodes ?? {};
   const shortcodes2 = builtins ? { ...builtinShortcodes, ...custom } : { ...custom };
+  const inlineShortcodes = new Set(
+    builtins ? builtinInlineShortcodes : []
+  );
+  for (const name of options.inlineShortcodes ?? []) {
+    inlineShortcodes.add(name);
+  }
   const resolved = {
     className: options.className ?? DEFAULT_SHORTCODE_CLASS_NAME,
     builtins,
-    shortcodes: shortcodes2
+    shortcodes: shortcodes2,
+    inlineShortcodes
   };
   if (options.language !== void 0) resolved.language = options.language;
   return resolved;
 }
+function isInlineShortcode(name, options) {
+  return options.inlineShortcodes.has(name);
+}
 function createShortcodeRenderContext(input) {
   return {
     contentIndex: input.contentIndex ?? /* @__PURE__ */ new Map(),
@@ -272,6 +288,7 @@ function renderShortcode(request, options) {
     url: firstUrl(attributes)
   });
   const container = request.container ?? false;
+  const block = request.block ?? container;
   const input = {
     name: request.name,
     label: request.label ?? "",
@@ -283,10 +300,10 @@ function renderShortcode(request, options) {
     input.childrenHtml = request.childrenHtml;
   }
   const body = renderer(input);
-  return wrapShortcode(body, request.name, container, options);
+  return wrapShortcode(body, request.name, block, options);
 }
-function wrapShortcode(body, name, container, options) {
-  const tag = container ? "div" : "span";
+function wrapShortcode(body, name, block, options) {
+  const tag = block ? "div" : "span";
   const classes = `${options.className} ${options.className}--${name}`;
   const languageAttribute = options.language === void 0 ? "" : ` lang="${escapeHtmlAttribute2(options.language)}"`;
   return `<${tag} class="${escapeHtmlAttribute2(
@@ -305,6 +322,7 @@ function firstUrl(attributes) {
 var SHORTCODES_SOURCE = "@riebeckite/plugin-shortcodes";
 var DIAGNOSTIC_UNKNOWN = "shortcodes-unknown";
 var DIAGNOSTIC_INVALID = "shortcodes-invalid";
+var DIAGNOSTIC_INLINE_UNSUPPORTED = "shortcodes-inline-unsupported";
 var ATTRIBUTE_NAME_PATTERN = /^[A-Za-z_][\w-]*$/;
 function remarkShortcodes(options = {}) {
   const resolved = resolveShortcodeOptions(options);
@@ -312,7 +330,7 @@ function remarkShortcodes(options = {}) {
     const targets = [];
     visit(
       tree,
-      ["containerDirective", "leafDirective"],
+      ["containerDirective", "leafDirective", "textDirective"],
       (node, index, parent) => {
         if (parent === void 0 || index === void 0) return;
         targets.push({ node, index, parent });
@@ -326,10 +344,37 @@ function remarkShortcodes(options = {}) {
 function transformDirective(target, resolved, options, file) {
   const { node, index, parent } = target;
   const name = node.name;
+  const inline = node.type === "textDirective";
   const container = node.type === "containerDirective";
   const { label, children } = extractLabel(node);
   const attributes = normalizeAttributes(node, file);
   const childrenHtml = container ? SHORTCODE_CHILDREN_MARKER : void 0;
+  if (inline && !isInlineShortcode(name, resolved)) {
+    const known = Object.hasOwn(resolved.shortcodes, name);
+    report(
+      file,
+      known ? DIAGNOSTIC_INLINE_UNSUPPORTED : DIAGNOSTIC_UNKNOWN,
+      known ? `Shortcode ":${name}" is block-only and cannot be used inline.` : `Unknown shortcode ":${name}" was left as escaped text.`,
+      node
+    );
+    parent.children.splice(
+      index,
+      1,
+      ...createFallback(
+        resolved.className,
+        name,
+        label,
+        attributes,
+        {
+          container: false,
+          block: false,
+          modifier: known ? "inline-unsupported" : "unknown"
+        },
+        children
+      )
+    );
+    return;
+  }
   const html = renderShortcode(
     {
       name,
@@ -337,6 +382,7 @@ function transformDirective(target, resolved, options, file) {
       attributes,
       childrenHtml,
       container,
+      block: !inline,
       context: createShortcodeRenderContext({
         name,
         label,
@@ -363,7 +409,7 @@ function transformDirective(target, resolved, options, file) {
         name,
         label,
         attributes,
-        container,
+        { container, block: !inline, modifier: "unknown" },
         children
       )
     );
@@ -431,11 +477,14 @@ function normalizeAttributes(node, file) {
   }
   return attributes;
 }
-function createFallback(className, name, label, attributes, container, children) {
-  const classes = `${className} ${className}--unknown`;
+function createFallback(className, name, label, attributes, shape, children) {
+  const classes = `${className} ${className}--${shape.modifier}`;
   const dataName = ` data-shortcode-name="${escapeHtmlAttribute3(name)}"`;
-  const directive = escapeHtml2(sourceText(name, label, attributes, container));
-  if (container) {
+  const inline = !shape.container && !shape.block;
+  const directive = escapeHtml2(
+    sourceText(name, label, attributes, shape.container, inline)
+  );
+  if (shape.container) {
     return [
       createHtml(
         `<div class="${escapeHtmlAttribute3(classes)}"${dataName}>${directive}`
@@ -444,14 +493,15 @@ function createFallback(className, name, label, attributes, container, children)
       createHtml("</div>")
     ];
   }
+  const tag = shape.block ? "div" : "span";
   return [
     createHtml(
-      `<span class="${escapeHtmlAttribute3(classes)}"${dataName}>${directive}</span>`
+      `<${tag} class="${escapeHtmlAttribute3(classes)}"${dataName}>${directive}</${tag}>`
     )
   ];
 }
-function sourceText(name, label, attributes, container) {
-  const fence = container ? ":::" : "::";
+function sourceText(name, label, attributes, container, inline) {
+  const fence = container ? ":::" : inline ? ":" : "::";
   const labelPart = label ? `[${label}]` : "";
   return `${fence}${name}${labelPart}${attributesText(attributes)}`;
 }
@@ -503,13 +553,16 @@ function shortcodes(options = {}) {
 var shortcodesPlugin = shortcodes;
 export {
   DEFAULT_SHORTCODE_CLASS_NAME,
+  DIAGNOSTIC_INLINE_UNSUPPORTED,
   DIAGNOSTIC_INVALID,
   DIAGNOSTIC_UNKNOWN,
   SHORTCODES_SOURCE,
   SHORTCODE_CHILDREN_MARKER,
+  builtinInlineShortcodes,
   builtinShortcodeNames,
   builtinShortcodes,
   createShortcodeRenderContext,
+  isInlineShortcode,
   remarkShortcodes,
   renderShortcode,
   resolveShortcodeOptions,

package/dist/src/builtins.d.ts

@@ -1,4 +1,5 @@
 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 builtinInlineShortcodes: readonly string[];
 export declare const builtinShortcodeNames: readonly string[];

package/dist/src/remark.d.ts

@@ -3,4 +3,5 @@ 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 const DIAGNOSTIC_INLINE_UNSUPPORTED = "shortcodes-inline-unsupported";
 export declare function remarkShortcodes(options?: RemarkShortcodesOptions): (tree: Root, file: unknown) => void;

package/dist/src/render.d.ts

@@ -8,6 +8,7 @@ export declare const DEFAULT_SHORTCODE_CLASS_NAME = "rb-shortcode";
  */
 export declare const SHORTCODE_CHILDREN_MARKER = "\0rb-shortcodes:children\0";
 export declare function resolveShortcodeOptions(options?: ShortcodeOptions): ResolvedShortcodeOptions;
+export declare function isInlineShortcode(name: string, options: ResolvedShortcodeOptions): boolean;
 export declare function createShortcodeRenderContext(input: {
     name: string;
     label?: string;

package/dist/src/types.d.ts

@@ -31,12 +31,14 @@ export type ShortcodeOptions = {
     builtins?: boolean;
     /** Custom renderers, merged on top of the built-ins by name. */
     shortcodes?: Record<string, ShortcodeRenderer>;
+    inlineShortcodes?: readonly string[];
 };
 export type ResolvedShortcodeOptions = {
     className: string;
     language?: string;
     builtins: boolean;
     shortcodes: Record<string, ShortcodeRenderer>;
+    inlineShortcodes: ReadonlySet<string>;
 };
 /** Input accepted by {@link renderShortcode}. */
 export type ShortcodeRenderRequest = {
@@ -45,6 +47,7 @@ export type ShortcodeRenderRequest = {
     attributes?: ShortcodeAttributes;
     childrenHtml?: string;
     container?: boolean;
+    block?: boolean;
     context?: PluginRenderContext;
 };
 /**
@@ -56,7 +59,7 @@ export type RemarkShortcodesOptions = ShortcodeOptions & {
     contentIndex?: Map<string, string>;
     contentSource?: ContentSource;
 };
-export type DirectiveName = "leafDirective" | "containerDirective";
+export type DirectiveName = "textDirective" | "leafDirective" | "containerDirective";
 export type DirectiveNode = Parent & {
     type: DirectiveName;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-shortcodes",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,11 +17,11 @@
   "dependencies": {
     "@types/mdast": "^4.0.4",
     "unist-util-visit": "^5.1.0",
-    "@riebeckite/core": "0.0.19"
+    "@riebeckite/core": "0.0.21"
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.19"
+    "@riebeckite/test": "0.0.21"
   },
   "publishConfig": {
     "access": "public"

package/style.css

@@ -245,7 +245,8 @@ div.rb-shortcode {
 
 /* fallback ---------------------------------------------------------------- */
 
-.rb-shortcode--unknown {
+.rb-shortcode--unknown,
+.rb-shortcode--inline-unsupported {
   color: var(--rb-shortcode-accent);
   font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
   font-size: 0.875em;