@riebeckite/plugin-shortcodes 0.0.12 → 0.0.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -110
- package/README_ja.md +111 -111
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,110 +1,110 @@
|
|
|
1
|
-
# @riebeckite/plugin-shortcodes
|
|
2
|
-
|
|
3
|
-
A generic shortcode system for Markdown, built on `remark-directive`.
|
|
4
|
-
|
|
5
|
-
[日本語](./README_ja.md)
|
|
6
|
-
|
|
7
|
-
## Overview
|
|
8
|
-
|
|
9
|
-
`shortcodes()` turns `remark-directive` syntax into HTML at Markdown time.
|
|
10
|
-
It supports leaf shortcodes (`::name[label]{key=value}`) and container
|
|
11
|
-
shortcodes (`:::name[label]{attrs}` … `:::`), and ships an extensible registry
|
|
12
|
-
so projects can add their own renderers on top of the built-ins.
|
|
13
|
-
|
|
14
|
-
Output is rendered into `mdast` `html` nodes and wrapped in a `span` (leaf) or
|
|
15
|
-
`div` (container) carrying `rb-shortcode rb-shortcode--<name>`.
|
|
16
|
-
|
|
17
|
-
## Usage
|
|
18
|
-
|
|
19
|
-
```ts
|
|
20
|
-
import { defineConfig } from "@riebeckite/core";
|
|
21
|
-
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
22
|
-
|
|
23
|
-
export default defineConfig({
|
|
24
|
-
// ...
|
|
25
|
-
plugins: [shortcodes()],
|
|
26
|
-
});
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Styles ship in `style.css`.
|
|
30
|
-
|
|
31
|
-
## Syntax
|
|
32
|
-
|
|
33
|
-
```
|
|
34
|
-
::kbd[Ctrl+S]
|
|
35
|
-
|
|
36
|
-
::youtube[id=dQw4w9WgXcQ]
|
|
37
|
-
|
|
38
|
-
:::note[Heads up]{type=warning}
|
|
39
|
-
Container bodies support **Markdown**.
|
|
40
|
-
:::
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
- `::name[label]{key=value}` — leaf shortcode, rendered inline.
|
|
44
|
-
- `:::name[label]{key=value}` … `:::` — container shortcode; the body is
|
|
45
|
-
rendered by the normal Markdown pipeline.
|
|
46
|
-
|
|
47
|
-
Unknown shortcodes emit a `shortcodes-unknown` diagnostic and stay on the page
|
|
48
|
-
as escaped text. Malformed attributes emit `shortcodes-invalid` and are
|
|
49
|
-
ignored.
|
|
50
|
-
|
|
51
|
-
## Built-in shortcodes
|
|
52
|
-
|
|
53
|
-
| Name | Kind | Attributes | Output |
|
|
54
|
-
| ---- | ---- | ---------- | ------ |
|
|
55
|
-
| `figure` | leaf / container | `src`/`url`/`image`, `alt`, `caption`, `width`, `height` | `<figure>` with image and caption |
|
|
56
|
-
| `youtube` | leaf | `id`/`video` or `url`/`src`, `title` | Privacy-friendly `youtube-nocookie.com` embed |
|
|
57
|
-
| `vimeo` | leaf | `id`/`video` or `url`/`src`, `title` | `player.vimeo.com` embed (`dnt=1`) |
|
|
58
|
-
| `gist` | leaf | `user` + `id`, or `url`, `file` | GitHub Gist embed with `<noscript>` link |
|
|
59
|
-
| `kbd` | leaf | label or `keys` | `<kbd>` elements split on `+` |
|
|
60
|
-
| `badge` | leaf | label or `text`, `variant`/`type`/`color`, `title` | Inline badge |
|
|
61
|
-
| `details` | container | label or `summary`, `open` | `<details>` disclosure |
|
|
62
|
-
| `spoiler` | container | label or `summary`, `open` | `details` alias with a different class |
|
|
63
|
-
| `note` | leaf / container | label or `title`, `type`/`variant` | Callout box |
|
|
64
|
-
| `callout` | leaf / container | label or `title`, `type`/`variant` | `note` alias with a different class |
|
|
65
|
-
| `link-card` | leaf | `url`/`href`, `title`, `description`, `image`/`icon` | Link preview card |
|
|
66
|
-
| `file` | leaf | `url`/`src`/`path`, `name`/`label`, `size` | Download link |
|
|
67
|
-
|
|
68
|
-
## Options
|
|
69
|
-
|
|
70
|
-
| Option | Type | Default | Description |
|
|
71
|
-
| ------ | ---- | ------- | ----------- |
|
|
72
|
-
| `className` | `string` | `"rb-shortcode"` | Root CSS class of every wrapper |
|
|
73
|
-
| `language` | `string` | – | BCP-47 tag applied to wrappers as `lang` |
|
|
74
|
-
| `builtins` | `boolean` | `true` | Register the built-in renderers |
|
|
75
|
-
| `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | Custom renderers, merged over the built-ins |
|
|
76
|
-
|
|
77
|
-
## Custom renderers
|
|
78
|
-
|
|
79
|
-
```ts
|
|
80
|
-
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
81
|
-
|
|
82
|
-
shortcodes({
|
|
83
|
-
shortcodes: {
|
|
84
|
-
mark: ({ label, attributes }) => `<mark>${label}</mark>`,
|
|
85
|
-
},
|
|
86
|
-
});
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
A `ShortcodeRenderer` receives `{ name, label, attributes, childrenHtml,
|
|
90
|
-
context, container }` and returns a string. For container shortcodes the plugin
|
|
91
|
-
wraps the result in `<div class="rb-shortcode rb-shortcode--<name>">` and
|
|
92
|
-
replaces `childrenHtml` with the rendered body, so container renderers must echo
|
|
93
|
-
`input.childrenHtml` where the body belongs. Renderers are synchronous and must
|
|
94
|
-
escape any user input themselves — `escapeHtml` and `escapeHtmlAttribute` are
|
|
95
|
-
re-exported from `@riebeckite/core`.
|
|
96
|
-
|
|
97
|
-
## Exports
|
|
98
|
-
|
|
99
|
-
- `shortcodes(options?)` / `shortcodesPlugin` — plugin factory
|
|
100
|
-
- `remarkShortcodes(options?)` — standalone remark transform
|
|
101
|
-
- `renderShortcode(request, options)` — render a single shortcode
|
|
102
|
-
- `resolveShortcodeOptions(options?)` — normalize options
|
|
103
|
-
- `builtinShortcodes`, `builtinShortcodeNames` — the built-in registry
|
|
104
|
-
- Types: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
|
|
105
|
-
`ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
|
|
106
|
-
`RemarkShortcodesOptions`
|
|
107
|
-
|
|
108
|
-
## See also
|
|
109
|
-
|
|
110
|
-
- [Plugin guide](../../../docs/en/plugin-
|
|
1
|
+
# @riebeckite/plugin-shortcodes
|
|
2
|
+
|
|
3
|
+
A generic shortcode system for Markdown, built on `remark-directive`.
|
|
4
|
+
|
|
5
|
+
[日本語](./README_ja.md)
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
`shortcodes()` turns `remark-directive` syntax into HTML at Markdown time.
|
|
10
|
+
It supports leaf shortcodes (`::name[label]{key=value}`) and container
|
|
11
|
+
shortcodes (`:::name[label]{attrs}` … `:::`), and ships an extensible registry
|
|
12
|
+
so projects can add their own renderers on top of the built-ins.
|
|
13
|
+
|
|
14
|
+
Output is rendered into `mdast` `html` nodes and wrapped in a `span` (leaf) or
|
|
15
|
+
`div` (container) carrying `rb-shortcode rb-shortcode--<name>`.
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { defineConfig } from "@riebeckite/core";
|
|
21
|
+
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
22
|
+
|
|
23
|
+
export default defineConfig({
|
|
24
|
+
// ...
|
|
25
|
+
plugins: [shortcodes()],
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Styles ship in `style.css`.
|
|
30
|
+
|
|
31
|
+
## Syntax
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
::kbd[Ctrl+S]
|
|
35
|
+
|
|
36
|
+
::youtube[id=dQw4w9WgXcQ]
|
|
37
|
+
|
|
38
|
+
:::note[Heads up]{type=warning}
|
|
39
|
+
Container bodies support **Markdown**.
|
|
40
|
+
:::
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- `::name[label]{key=value}` — leaf shortcode, rendered inline.
|
|
44
|
+
- `:::name[label]{key=value}` … `:::` — container shortcode; the body is
|
|
45
|
+
rendered by the normal Markdown pipeline.
|
|
46
|
+
|
|
47
|
+
Unknown shortcodes emit a `shortcodes-unknown` diagnostic and stay on the page
|
|
48
|
+
as escaped text. Malformed attributes emit `shortcodes-invalid` and are
|
|
49
|
+
ignored.
|
|
50
|
+
|
|
51
|
+
## Built-in shortcodes
|
|
52
|
+
|
|
53
|
+
| Name | Kind | Attributes | Output |
|
|
54
|
+
| ---- | ---- | ---------- | ------ |
|
|
55
|
+
| `figure` | leaf / container | `src`/`url`/`image`, `alt`, `caption`, `width`, `height` | `<figure>` with image and caption |
|
|
56
|
+
| `youtube` | leaf | `id`/`video` or `url`/`src`, `title` | Privacy-friendly `youtube-nocookie.com` embed |
|
|
57
|
+
| `vimeo` | leaf | `id`/`video` or `url`/`src`, `title` | `player.vimeo.com` embed (`dnt=1`) |
|
|
58
|
+
| `gist` | leaf | `user` + `id`, or `url`, `file` | GitHub Gist embed with `<noscript>` link |
|
|
59
|
+
| `kbd` | leaf | label or `keys` | `<kbd>` elements split on `+` |
|
|
60
|
+
| `badge` | leaf | label or `text`, `variant`/`type`/`color`, `title` | Inline badge |
|
|
61
|
+
| `details` | container | label or `summary`, `open` | `<details>` disclosure |
|
|
62
|
+
| `spoiler` | container | label or `summary`, `open` | `details` alias with a different class |
|
|
63
|
+
| `note` | leaf / container | label or `title`, `type`/`variant` | Callout box |
|
|
64
|
+
| `callout` | leaf / container | label or `title`, `type`/`variant` | `note` alias with a different class |
|
|
65
|
+
| `link-card` | leaf | `url`/`href`, `title`, `description`, `image`/`icon` | Link preview card |
|
|
66
|
+
| `file` | leaf | `url`/`src`/`path`, `name`/`label`, `size` | Download link |
|
|
67
|
+
|
|
68
|
+
## Options
|
|
69
|
+
|
|
70
|
+
| Option | Type | Default | Description |
|
|
71
|
+
| ------ | ---- | ------- | ----------- |
|
|
72
|
+
| `className` | `string` | `"rb-shortcode"` | Root CSS class of every wrapper |
|
|
73
|
+
| `language` | `string` | – | BCP-47 tag applied to wrappers as `lang` |
|
|
74
|
+
| `builtins` | `boolean` | `true` | Register the built-in renderers |
|
|
75
|
+
| `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | Custom renderers, merged over the built-ins |
|
|
76
|
+
|
|
77
|
+
## Custom renderers
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
81
|
+
|
|
82
|
+
shortcodes({
|
|
83
|
+
shortcodes: {
|
|
84
|
+
mark: ({ label, attributes }) => `<mark>${label}</mark>`,
|
|
85
|
+
},
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
A `ShortcodeRenderer` receives `{ name, label, attributes, childrenHtml,
|
|
90
|
+
context, container }` and returns a string. For container shortcodes the plugin
|
|
91
|
+
wraps the result in `<div class="rb-shortcode rb-shortcode--<name>">` and
|
|
92
|
+
replaces `childrenHtml` with the rendered body, so container renderers must echo
|
|
93
|
+
`input.childrenHtml` where the body belongs. Renderers are synchronous and must
|
|
94
|
+
escape any user input themselves — `escapeHtml` and `escapeHtmlAttribute` are
|
|
95
|
+
re-exported from `@riebeckite/core`.
|
|
96
|
+
|
|
97
|
+
## Exports
|
|
98
|
+
|
|
99
|
+
- `shortcodes(options?)` / `shortcodesPlugin` — plugin factory
|
|
100
|
+
- `remarkShortcodes(options?)` — standalone remark transform
|
|
101
|
+
- `renderShortcode(request, options)` — render a single shortcode
|
|
102
|
+
- `resolveShortcodeOptions(options?)` — normalize options
|
|
103
|
+
- `builtinShortcodes`, `builtinShortcodeNames` — the built-in registry
|
|
104
|
+
- Types: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
|
|
105
|
+
`ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
|
|
106
|
+
`RemarkShortcodesOptions`
|
|
107
|
+
|
|
108
|
+
## See also
|
|
109
|
+
|
|
110
|
+
- [Plugin guide](../../../docs/en/reference/plugin-api.md)
|
package/README_ja.md
CHANGED
|
@@ -1,111 +1,111 @@
|
|
|
1
|
-
# @riebeckite/plugin-shortcodes
|
|
2
|
-
|
|
3
|
-
`remark-directive` を土台にした汎用ショートコード機能です。
|
|
4
|
-
|
|
5
|
-
[English](./README.md)
|
|
6
|
-
|
|
7
|
-
## 概要
|
|
8
|
-
|
|
9
|
-
`shortcodes()` は `remark-directive` の記法を Markdown 処理時に HTML へ変換
|
|
10
|
-
します。リーフ型（`::name[label]{key=value}`）とコンテナ型
|
|
11
|
-
（`:::name[label]{attrs}` … `:::`）の両方に対応し、組み込みレンダラーに
|
|
12
|
-
独自のレンダラーを重ねられる拡張可能なレジストリを備えます。
|
|
13
|
-
|
|
14
|
-
出力は `mdast` の `html` ノードとして書き出され、リーフは `span`、コンテナは
|
|
15
|
-
`div` で `rb-shortcode rb-shortcode--<name>` を付けてラップされます。
|
|
16
|
-
|
|
17
|
-
## 使い方
|
|
18
|
-
|
|
19
|
-
```ts
|
|
20
|
-
import { defineConfig } from "@riebeckite/core";
|
|
21
|
-
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
22
|
-
|
|
23
|
-
export default defineConfig({
|
|
24
|
-
// ...
|
|
25
|
-
plugins: [shortcodes()],
|
|
26
|
-
});
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
スタイルは `style.css` に同梱されています。
|
|
30
|
-
|
|
31
|
-
## 記法
|
|
32
|
-
|
|
33
|
-
```
|
|
34
|
-
::kbd[Ctrl+S]
|
|
35
|
-
|
|
36
|
-
::youtube[id=dQw4w9WgXcQ]
|
|
37
|
-
|
|
38
|
-
:::note[補足]{type=warning}
|
|
39
|
-
コンテナの本文では **Markdown** が使えます。
|
|
40
|
-
:::
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
- `::name[label]{key=value}` — リーフ型。インラインで描画されます。
|
|
44
|
-
- `:::name[label]{key=value}` … `:::` — コンテナ型。本文は通常の Markdown
|
|
45
|
-
パイプラインで描画されます。
|
|
46
|
-
|
|
47
|
-
未知のショートコードは `shortcodes-unknown` 診断を出し、エスケープした
|
|
48
|
-
テキストとしてページに残します。不正な属性は `shortcodes-invalid` を出して
|
|
49
|
-
無視します。
|
|
50
|
-
|
|
51
|
-
## 組み込みショートコード
|
|
52
|
-
|
|
53
|
-
| 名前 | 種類 | 属性 | 出力 |
|
|
54
|
-
| ---- | ---- | ---- | ---- |
|
|
55
|
-
| `figure` | リーフ / コンテナ | `src`/`url`/`image`, `alt`, `caption`, `width`, `height` | 画像とキャプションの `<figure>` |
|
|
56
|
-
| `youtube` | リーフ | `id`/`video` または `url`/`src`, `title` | `youtube-nocookie.com` のプライバシー配慮埋め込み |
|
|
57
|
-
| `vimeo` | リーフ | `id`/`video` または `url`/`src`, `title` | `player.vimeo.com` 埋め込み（`dnt=1`） |
|
|
58
|
-
| `gist` | リーフ | `user` + `id`、または `url`, `file` | `<noscript>` リンク付きの Gist 埋め込み |
|
|
59
|
-
| `kbd` | リーフ | ラベルまたは `keys` | `+` で分割した `<kbd>` |
|
|
60
|
-
| `badge` | リーフ | ラベルまたは `text`, `variant`/`type`/`color`, `title` | インラインバッジ |
|
|
61
|
-
| `details` | コンテナ | ラベルまたは `summary`, `open` | `<details>` 折りたたみ |
|
|
62
|
-
| `spoiler` | コンテナ | ラベルまたは `summary`, `open` | クラス違いの `details` エイリアス |
|
|
63
|
-
| `note` | リーフ / コンテナ | ラベルまたは `title`, `type`/`variant` | コールアウト |
|
|
64
|
-
| `callout` | リーフ / コンテナ | ラベルまたは `title`, `type`/`variant` | クラス違いの `note` エイリアス |
|
|
65
|
-
| `link-card` | リーフ | `url`/`href`, `title`, `description`, `image`/`icon` | リンクプレビューカード |
|
|
66
|
-
| `file` | リーフ | `url`/`src`/`path`, `name`/`label`, `size` | ダウンロードリンク |
|
|
67
|
-
|
|
68
|
-
## オプション
|
|
69
|
-
|
|
70
|
-
| オプション | 型 | 既定値 | 説明 |
|
|
71
|
-
| ---------- | -- | ------ | ---- |
|
|
72
|
-
| `className` | `string` | `"rb-shortcode"` | すべてのラッパーのルート CSS クラス |
|
|
73
|
-
| `language` | `string` | – | ラッパーの `lang` に付与する BCP-47 タグ |
|
|
74
|
-
| `builtins` | `boolean` | `true` | 組み込みレンダラーを登録する |
|
|
75
|
-
| `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | 組み込みに重ねる独自レンダラー |
|
|
76
|
-
|
|
77
|
-
## 独自レンダラー
|
|
78
|
-
|
|
79
|
-
```ts
|
|
80
|
-
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
81
|
-
|
|
82
|
-
shortcodes({
|
|
83
|
-
shortcodes: {
|
|
84
|
-
mark: ({ label, attributes }) => `<mark>${label}</mark>`,
|
|
85
|
-
},
|
|
86
|
-
});
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
`ShortcodeRenderer` は `{ name, label, attributes, childrenHtml, context,
|
|
90
|
-
container }` を受け取り、文字列を返します。コンテナ型では結果が
|
|
91
|
-
`<div class="rb-shortcode rb-shortcode--<name>">` でラップされ、
|
|
92
|
-
`childrenHtml` の位置に本文が差し込まれます。コンテナ用レンダラーは本文を
|
|
93
|
-
置きたい位置で `input.childrenHtml` をそのまま出力してください。レンダラーは
|
|
94
|
-
同期関数で、ユーザー入力のエスケープは各自で行う必要があります
|
|
95
|
-
（`@riebeckite/core` の `escapeHtml` / `escapeHtmlAttribute` を再エクスポート
|
|
96
|
-
しています）。
|
|
97
|
-
|
|
98
|
-
## エクスポート
|
|
99
|
-
|
|
100
|
-
- `shortcodes(options?)` / `shortcodesPlugin` — プラグインファクトリ
|
|
101
|
-
- `remarkShortcodes(options?)` — 単体で使える remark トランスフォーム
|
|
102
|
-
- `renderShortcode(request, options)` — 単一ショートコードの描画
|
|
103
|
-
- `resolveShortcodeOptions(options?)` — オプションの正規化
|
|
104
|
-
- `builtinShortcodes`, `builtinShortcodeNames` — 組み込みレジストリ
|
|
105
|
-
- 型: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
|
|
106
|
-
`ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
|
|
107
|
-
`RemarkShortcodesOptions`
|
|
108
|
-
|
|
109
|
-
## 関連
|
|
110
|
-
|
|
111
|
-
- [プラグインガイド](../../../docs/ja/plugin-
|
|
1
|
+
# @riebeckite/plugin-shortcodes
|
|
2
|
+
|
|
3
|
+
`remark-directive` を土台にした汎用ショートコード機能です。
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
## 概要
|
|
8
|
+
|
|
9
|
+
`shortcodes()` は `remark-directive` の記法を Markdown 処理時に HTML へ変換
|
|
10
|
+
します。リーフ型（`::name[label]{key=value}`）とコンテナ型
|
|
11
|
+
（`:::name[label]{attrs}` … `:::`）の両方に対応し、組み込みレンダラーに
|
|
12
|
+
独自のレンダラーを重ねられる拡張可能なレジストリを備えます。
|
|
13
|
+
|
|
14
|
+
出力は `mdast` の `html` ノードとして書き出され、リーフは `span`、コンテナは
|
|
15
|
+
`div` で `rb-shortcode rb-shortcode--<name>` を付けてラップされます。
|
|
16
|
+
|
|
17
|
+
## 使い方
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { defineConfig } from "@riebeckite/core";
|
|
21
|
+
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
22
|
+
|
|
23
|
+
export default defineConfig({
|
|
24
|
+
// ...
|
|
25
|
+
plugins: [shortcodes()],
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
スタイルは `style.css` に同梱されています。
|
|
30
|
+
|
|
31
|
+
## 記法
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
::kbd[Ctrl+S]
|
|
35
|
+
|
|
36
|
+
::youtube[id=dQw4w9WgXcQ]
|
|
37
|
+
|
|
38
|
+
:::note[補足]{type=warning}
|
|
39
|
+
コンテナの本文では **Markdown** が使えます。
|
|
40
|
+
:::
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- `::name[label]{key=value}` — リーフ型。インラインで描画されます。
|
|
44
|
+
- `:::name[label]{key=value}` … `:::` — コンテナ型。本文は通常の Markdown
|
|
45
|
+
パイプラインで描画されます。
|
|
46
|
+
|
|
47
|
+
未知のショートコードは `shortcodes-unknown` 診断を出し、エスケープした
|
|
48
|
+
テキストとしてページに残します。不正な属性は `shortcodes-invalid` を出して
|
|
49
|
+
無視します。
|
|
50
|
+
|
|
51
|
+
## 組み込みショートコード
|
|
52
|
+
|
|
53
|
+
| 名前 | 種類 | 属性 | 出力 |
|
|
54
|
+
| ---- | ---- | ---- | ---- |
|
|
55
|
+
| `figure` | リーフ / コンテナ | `src`/`url`/`image`, `alt`, `caption`, `width`, `height` | 画像とキャプションの `<figure>` |
|
|
56
|
+
| `youtube` | リーフ | `id`/`video` または `url`/`src`, `title` | `youtube-nocookie.com` のプライバシー配慮埋め込み |
|
|
57
|
+
| `vimeo` | リーフ | `id`/`video` または `url`/`src`, `title` | `player.vimeo.com` 埋め込み（`dnt=1`） |
|
|
58
|
+
| `gist` | リーフ | `user` + `id`、または `url`, `file` | `<noscript>` リンク付きの Gist 埋め込み |
|
|
59
|
+
| `kbd` | リーフ | ラベルまたは `keys` | `+` で分割した `<kbd>` |
|
|
60
|
+
| `badge` | リーフ | ラベルまたは `text`, `variant`/`type`/`color`, `title` | インラインバッジ |
|
|
61
|
+
| `details` | コンテナ | ラベルまたは `summary`, `open` | `<details>` 折りたたみ |
|
|
62
|
+
| `spoiler` | コンテナ | ラベルまたは `summary`, `open` | クラス違いの `details` エイリアス |
|
|
63
|
+
| `note` | リーフ / コンテナ | ラベルまたは `title`, `type`/`variant` | コールアウト |
|
|
64
|
+
| `callout` | リーフ / コンテナ | ラベルまたは `title`, `type`/`variant` | クラス違いの `note` エイリアス |
|
|
65
|
+
| `link-card` | リーフ | `url`/`href`, `title`, `description`, `image`/`icon` | リンクプレビューカード |
|
|
66
|
+
| `file` | リーフ | `url`/`src`/`path`, `name`/`label`, `size` | ダウンロードリンク |
|
|
67
|
+
|
|
68
|
+
## オプション
|
|
69
|
+
|
|
70
|
+
| オプション | 型 | 既定値 | 説明 |
|
|
71
|
+
| ---------- | -- | ------ | ---- |
|
|
72
|
+
| `className` | `string` | `"rb-shortcode"` | すべてのラッパーのルート CSS クラス |
|
|
73
|
+
| `language` | `string` | – | ラッパーの `lang` に付与する BCP-47 タグ |
|
|
74
|
+
| `builtins` | `boolean` | `true` | 組み込みレンダラーを登録する |
|
|
75
|
+
| `shortcodes` | `Record<string, ShortcodeRenderer>` | `{}` | 組み込みに重ねる独自レンダラー |
|
|
76
|
+
|
|
77
|
+
## 独自レンダラー
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { shortcodes } from "@riebeckite/plugin-shortcodes";
|
|
81
|
+
|
|
82
|
+
shortcodes({
|
|
83
|
+
shortcodes: {
|
|
84
|
+
mark: ({ label, attributes }) => `<mark>${label}</mark>`,
|
|
85
|
+
},
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`ShortcodeRenderer` は `{ name, label, attributes, childrenHtml, context,
|
|
90
|
+
container }` を受け取り、文字列を返します。コンテナ型では結果が
|
|
91
|
+
`<div class="rb-shortcode rb-shortcode--<name>">` でラップされ、
|
|
92
|
+
`childrenHtml` の位置に本文が差し込まれます。コンテナ用レンダラーは本文を
|
|
93
|
+
置きたい位置で `input.childrenHtml` をそのまま出力してください。レンダラーは
|
|
94
|
+
同期関数で、ユーザー入力のエスケープは各自で行う必要があります
|
|
95
|
+
（`@riebeckite/core` の `escapeHtml` / `escapeHtmlAttribute` を再エクスポート
|
|
96
|
+
しています）。
|
|
97
|
+
|
|
98
|
+
## エクスポート
|
|
99
|
+
|
|
100
|
+
- `shortcodes(options?)` / `shortcodesPlugin` — プラグインファクトリ
|
|
101
|
+
- `remarkShortcodes(options?)` — 単体で使える remark トランスフォーム
|
|
102
|
+
- `renderShortcode(request, options)` — 単一ショートコードの描画
|
|
103
|
+
- `resolveShortcodeOptions(options?)` — オプションの正規化
|
|
104
|
+
- `builtinShortcodes`, `builtinShortcodeNames` — 組み込みレジストリ
|
|
105
|
+
- 型: `ShortcodeRenderer`, `ShortcodeOptions`, `ResolvedShortcodeOptions`,
|
|
106
|
+
`ShortcodeRenderInput`, `ShortcodeRenderRequest`, `ShortcodeAttributes`,
|
|
107
|
+
`RemarkShortcodesOptions`
|
|
108
|
+
|
|
109
|
+
## 関連
|
|
110
|
+
|
|
111
|
+
- [プラグインガイド](../../../docs/ja/reference/plugin-api.md)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@riebeckite/plugin-shortcodes",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.13",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -17,11 +17,11 @@
|
|
|
17
17
|
"dependencies": {
|
|
18
18
|
"@types/mdast": "^4.0.4",
|
|
19
19
|
"unist-util-visit": "^5.1.0",
|
|
20
|
-
"@riebeckite/core": "0.0.
|
|
20
|
+
"@riebeckite/core": "0.0.13"
|
|
21
21
|
},
|
|
22
22
|
"devDependencies": {
|
|
23
23
|
"tsx": "^4.22.4",
|
|
24
|
-
"@riebeckite/test": "0.0.
|
|
24
|
+
"@riebeckite/test": "0.0.13"
|
|
25
25
|
},
|
|
26
26
|
"publishConfig": {
|
|
27
27
|
"access": "public"
|