@riebeckite/plugin-rich-embed 0.0.12 → 0.0.14
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 +142 -142
- package/README_ja.md +132 -132
- package/package.json +4 -3
- package/style.css +1 -0
package/README.md
CHANGED
|
@@ -1,142 +1,142 @@
|
|
|
1
|
-
# @riebeckite/plugin-rich-embed
|
|
2
|
-
|
|
3
|
-
Build-time media embeds for ` ```embed ` code blocks.
|
|
4
|
-
|
|
5
|
-
[日本語](./README_ja.md)
|
|
6
|
-
|
|
7
|
-
## Overview
|
|
8
|
-
|
|
9
|
-
`richEmbed()` turns an ` ```embed ` fenced code block into a responsive
|
|
10
|
-
`<figure class="rb-rich-embed">`. Provider detection is pure string inspection:
|
|
11
|
-
the plugin never performs a network request at build time, and it ships no
|
|
12
|
-
client-side JavaScript.
|
|
13
|
-
|
|
14
|
-
## Usage
|
|
15
|
-
|
|
16
|
-
```ts
|
|
17
|
-
import { defineConfig } from "@riebeckite/core";
|
|
18
|
-
import { richEmbed } from "@riebeckite/plugin-rich-embed";
|
|
19
|
-
|
|
20
|
-
export default defineConfig({
|
|
21
|
-
// ...
|
|
22
|
-
plugins: [
|
|
23
|
-
richEmbed({
|
|
24
|
-
allowHosts: ["player.example.com"],
|
|
25
|
-
}),
|
|
26
|
-
],
|
|
27
|
-
});
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
## Syntax
|
|
31
|
-
|
|
32
|
-
The first non-empty line is the URL. Every following `key: value` line is an
|
|
33
|
-
option.
|
|
34
|
-
|
|
35
|
-
````md
|
|
36
|
-
```embed
|
|
37
|
-
https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
38
|
-
title: Demo video
|
|
39
|
-
caption: A short caption under the frame
|
|
40
|
-
aspect: 16/9
|
|
41
|
-
start: 30
|
|
42
|
-
```
|
|
43
|
-
````
|
|
44
|
-
|
|
45
|
-
| Block option | Description |
|
|
46
|
-
| ------------ | ----------- |
|
|
47
|
-
| `title` | `title` attribute of the `<iframe>` (also the link label for Gist) |
|
|
48
|
-
| `caption` | Rendered as `<figcaption class="rb-rich-embed__caption">` |
|
|
49
|
-
| `aspect` | Aspect ratio such as `16/9` or `4/3` (default `16/9`) |
|
|
50
|
-
| `start` | Start time in seconds (YouTube only) |
|
|
51
|
-
|
|
52
|
-
Unknown option keys are ignored. An invalid `aspect` falls back to `16/9`.
|
|
53
|
-
|
|
54
|
-
## Supported providers
|
|
55
|
-
|
|
56
|
-
| Provider | Recognised URLs | Output `src` |
|
|
57
|
-
| -------- | --------------- | ------------ |
|
|
58
|
-
| YouTube | `youtube.com/watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`, `/live/` | `https://www.youtube-nocookie.com/embed/<id>` |
|
|
59
|
-
| Vimeo | `vimeo.com/<numeric id>` | `https://player.vimeo.com/video/<id>` |
|
|
60
|
-
| Spotify | `open.spotify.com/(track\|album\|playlist\|episode\|show)/<id>` | `https://open.spotify.com/embed/<type>/<id>` |
|
|
61
|
-
| CodePen | `codepen.io/<user>/pen/<id>` | `https://codepen.io/<user>/embed/<id>` |
|
|
62
|
-
| GitHub Gist | `gist.github.com/...` | link card (gists cannot be iframed) |
|
|
63
|
-
|
|
64
|
-
When the host is not recognised, the block is left untouched and a warning
|
|
65
|
-
diagnostic is emitted. A generic `<iframe>` is only produced when the host is
|
|
66
|
-
listed in `allowHosts`.
|
|
67
|
-
|
|
68
|
-
## Options
|
|
69
|
-
|
|
70
|
-
| Option | Type | Default | Description |
|
|
71
|
-
| ------ | ---- | ------- | ----------- |
|
|
72
|
-
| `allowHosts` | `string[]` | `[]` | Hostnames allowed to use the generic iframe fallback |
|
|
73
|
-
| `providers` | `RichEmbedProvider[]` | all | Allowlist of providers to enable |
|
|
74
|
-
| `disable` | `RichEmbedProvider[]` | `[]` | Providers to disable (wins over `providers`) |
|
|
75
|
-
|
|
76
|
-
## Output HTML
|
|
77
|
-
|
|
78
|
-
```html
|
|
79
|
-
<figure
|
|
80
|
-
class="rb-rich-embed"
|
|
81
|
-
data-rich-embed="youtube"
|
|
82
|
-
data-rich-embed-marker="RIEBECKITE_EXTERNAL_RICHEMBED_MARKER"
|
|
83
|
-
>
|
|
84
|
-
<div class="rb-rich-embed__frame" style="--rb-rich-embed-aspect:16/9">
|
|
85
|
-
<iframe
|
|
86
|
-
src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
|
|
87
|
-
loading="lazy"
|
|
88
|
-
allowfullscreen
|
|
89
|
-
referrerpolicy="strict-origin-when-cross-origin"
|
|
90
|
-
title="Demo video"
|
|
91
|
-
></iframe>
|
|
92
|
-
</div>
|
|
93
|
-
<figcaption class="rb-rich-embed__caption">A short caption</figcaption>
|
|
94
|
-
</figure>
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
Gist blocks produce `div.rb-rich-embed__card > a.rb-rich-embed__link` instead of
|
|
98
|
-
an iframe.
|
|
99
|
-
|
|
100
|
-
### CSS hooks
|
|
101
|
-
|
|
102
|
-
- `.rb-rich-embed` — outer figure
|
|
103
|
-
- `.rb-rich-embed__frame` — responsive wrapper (reads `--rb-rich-embed-aspect`)
|
|
104
|
-
- `.rb-rich-embed__caption` — optional caption
|
|
105
|
-
- `.rb-rich-embed__card`, `.rb-rich-embed__link` — Gist link card
|
|
106
|
-
|
|
107
|
-
The stylesheet is shipped as `@riebeckite/plugin-rich-embed/style.css`.
|
|
108
|
-
|
|
109
|
-
## Diagnostics
|
|
110
|
-
|
|
111
|
-
Unsupported or invalid blocks keep their original code block and report a
|
|
112
|
-
warning through the vfile message channel:
|
|
113
|
-
|
|
114
|
-
- `source: "@riebeckite/plugin-rich-embed"`
|
|
115
|
-
- `ruleId: "unsupported-embed"`
|
|
116
|
-
|
|
117
|
-
## Security
|
|
118
|
-
|
|
119
|
-
- Only `https:` URLs are accepted.
|
|
120
|
-
- Provider output is constructed from validated path segments; dynamic
|
|
121
|
-
segments are passed through `encodeURIComponent`.
|
|
122
|
-
- A generic iframe requires an explicit `allowHosts` entry.
|
|
123
|
-
- No raw user HTML is ever emitted: titles, captions, and labels are written as
|
|
124
|
-
escaped text nodes.
|
|
125
|
-
|
|
126
|
-
## Limitations
|
|
127
|
-
|
|
128
|
-
- No OEMBED fetching or title/thumbnail discovery — everything is derived from
|
|
129
|
-
the URL and the block options.
|
|
130
|
-
- GitHub Gists cannot be embedded in an iframe, so they render as a link card.
|
|
131
|
-
- Generic embeds are emitted verbatim from the `https:` URL, so only allow hosts
|
|
132
|
-
you trust.
|
|
133
|
-
|
|
134
|
-
## Exports
|
|
135
|
-
|
|
136
|
-
- `richEmbed(options?)` — plugin factory
|
|
137
|
-
- `richEmbedPlugin` — alias of `richEmbed`
|
|
138
|
-
- Types: `RichEmbedOptions`, `RichEmbedProvider`
|
|
139
|
-
|
|
140
|
-
## See also
|
|
141
|
-
|
|
142
|
-
- [Plugin guide](../../../docs/en/plugin-
|
|
1
|
+
# @riebeckite/plugin-rich-embed
|
|
2
|
+
|
|
3
|
+
Build-time media embeds for ` ```embed ` code blocks.
|
|
4
|
+
|
|
5
|
+
[日本語](./README_ja.md)
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
`richEmbed()` turns an ` ```embed ` fenced code block into a responsive
|
|
10
|
+
`<figure class="rb-rich-embed">`. Provider detection is pure string inspection:
|
|
11
|
+
the plugin never performs a network request at build time, and it ships no
|
|
12
|
+
client-side JavaScript.
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { defineConfig } from "@riebeckite/core";
|
|
18
|
+
import { richEmbed } from "@riebeckite/plugin-rich-embed";
|
|
19
|
+
|
|
20
|
+
export default defineConfig({
|
|
21
|
+
// ...
|
|
22
|
+
plugins: [
|
|
23
|
+
richEmbed({
|
|
24
|
+
allowHosts: ["player.example.com"],
|
|
25
|
+
}),
|
|
26
|
+
],
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Syntax
|
|
31
|
+
|
|
32
|
+
The first non-empty line is the URL. Every following `key: value` line is an
|
|
33
|
+
option.
|
|
34
|
+
|
|
35
|
+
````md
|
|
36
|
+
```embed
|
|
37
|
+
https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
38
|
+
title: Demo video
|
|
39
|
+
caption: A short caption under the frame
|
|
40
|
+
aspect: 16/9
|
|
41
|
+
start: 30
|
|
42
|
+
```
|
|
43
|
+
````
|
|
44
|
+
|
|
45
|
+
| Block option | Description |
|
|
46
|
+
| ------------ | ----------- |
|
|
47
|
+
| `title` | `title` attribute of the `<iframe>` (also the link label for Gist) |
|
|
48
|
+
| `caption` | Rendered as `<figcaption class="rb-rich-embed__caption">` |
|
|
49
|
+
| `aspect` | Aspect ratio such as `16/9` or `4/3` (default `16/9`) |
|
|
50
|
+
| `start` | Start time in seconds (YouTube only) |
|
|
51
|
+
|
|
52
|
+
Unknown option keys are ignored. An invalid `aspect` falls back to `16/9`.
|
|
53
|
+
|
|
54
|
+
## Supported providers
|
|
55
|
+
|
|
56
|
+
| Provider | Recognised URLs | Output `src` |
|
|
57
|
+
| -------- | --------------- | ------------ |
|
|
58
|
+
| YouTube | `youtube.com/watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`, `/live/` | `https://www.youtube-nocookie.com/embed/<id>` |
|
|
59
|
+
| Vimeo | `vimeo.com/<numeric id>` | `https://player.vimeo.com/video/<id>` |
|
|
60
|
+
| Spotify | `open.spotify.com/(track\|album\|playlist\|episode\|show)/<id>` | `https://open.spotify.com/embed/<type>/<id>` |
|
|
61
|
+
| CodePen | `codepen.io/<user>/pen/<id>` | `https://codepen.io/<user>/embed/<id>` |
|
|
62
|
+
| GitHub Gist | `gist.github.com/...` | link card (gists cannot be iframed) |
|
|
63
|
+
|
|
64
|
+
When the host is not recognised, the block is left untouched and a warning
|
|
65
|
+
diagnostic is emitted. A generic `<iframe>` is only produced when the host is
|
|
66
|
+
listed in `allowHosts`.
|
|
67
|
+
|
|
68
|
+
## Options
|
|
69
|
+
|
|
70
|
+
| Option | Type | Default | Description |
|
|
71
|
+
| ------ | ---- | ------- | ----------- |
|
|
72
|
+
| `allowHosts` | `string[]` | `[]` | Hostnames allowed to use the generic iframe fallback |
|
|
73
|
+
| `providers` | `RichEmbedProvider[]` | all | Allowlist of providers to enable |
|
|
74
|
+
| `disable` | `RichEmbedProvider[]` | `[]` | Providers to disable (wins over `providers`) |
|
|
75
|
+
|
|
76
|
+
## Output HTML
|
|
77
|
+
|
|
78
|
+
```html
|
|
79
|
+
<figure
|
|
80
|
+
class="rb-rich-embed"
|
|
81
|
+
data-rich-embed="youtube"
|
|
82
|
+
data-rich-embed-marker="RIEBECKITE_EXTERNAL_RICHEMBED_MARKER"
|
|
83
|
+
>
|
|
84
|
+
<div class="rb-rich-embed__frame" style="--rb-rich-embed-aspect:16/9">
|
|
85
|
+
<iframe
|
|
86
|
+
src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
|
|
87
|
+
loading="lazy"
|
|
88
|
+
allowfullscreen
|
|
89
|
+
referrerpolicy="strict-origin-when-cross-origin"
|
|
90
|
+
title="Demo video"
|
|
91
|
+
></iframe>
|
|
92
|
+
</div>
|
|
93
|
+
<figcaption class="rb-rich-embed__caption">A short caption</figcaption>
|
|
94
|
+
</figure>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Gist blocks produce `div.rb-rich-embed__card > a.rb-rich-embed__link` instead of
|
|
98
|
+
an iframe.
|
|
99
|
+
|
|
100
|
+
### CSS hooks
|
|
101
|
+
|
|
102
|
+
- `.rb-rich-embed` — outer figure
|
|
103
|
+
- `.rb-rich-embed__frame` — responsive wrapper (reads `--rb-rich-embed-aspect`)
|
|
104
|
+
- `.rb-rich-embed__caption` — optional caption
|
|
105
|
+
- `.rb-rich-embed__card`, `.rb-rich-embed__link` — Gist link card
|
|
106
|
+
|
|
107
|
+
The stylesheet is shipped as `@riebeckite/plugin-rich-embed/style.css`.
|
|
108
|
+
|
|
109
|
+
## Diagnostics
|
|
110
|
+
|
|
111
|
+
Unsupported or invalid blocks keep their original code block and report a
|
|
112
|
+
warning through the vfile message channel:
|
|
113
|
+
|
|
114
|
+
- `source: "@riebeckite/plugin-rich-embed"`
|
|
115
|
+
- `ruleId: "unsupported-embed"`
|
|
116
|
+
|
|
117
|
+
## Security
|
|
118
|
+
|
|
119
|
+
- Only `https:` URLs are accepted.
|
|
120
|
+
- Provider output is constructed from validated path segments; dynamic
|
|
121
|
+
segments are passed through `encodeURIComponent`.
|
|
122
|
+
- A generic iframe requires an explicit `allowHosts` entry.
|
|
123
|
+
- No raw user HTML is ever emitted: titles, captions, and labels are written as
|
|
124
|
+
escaped text nodes.
|
|
125
|
+
|
|
126
|
+
## Limitations
|
|
127
|
+
|
|
128
|
+
- No OEMBED fetching or title/thumbnail discovery — everything is derived from
|
|
129
|
+
the URL and the block options.
|
|
130
|
+
- GitHub Gists cannot be embedded in an iframe, so they render as a link card.
|
|
131
|
+
- Generic embeds are emitted verbatim from the `https:` URL, so only allow hosts
|
|
132
|
+
you trust.
|
|
133
|
+
|
|
134
|
+
## Exports
|
|
135
|
+
|
|
136
|
+
- `richEmbed(options?)` — plugin factory
|
|
137
|
+
- `richEmbedPlugin` — alias of `richEmbed`
|
|
138
|
+
- Types: `RichEmbedOptions`, `RichEmbedProvider`
|
|
139
|
+
|
|
140
|
+
## See also
|
|
141
|
+
|
|
142
|
+
- [Plugin guide](../../../docs/en/reference/plugin-api.md)
|
package/README_ja.md
CHANGED
|
@@ -1,132 +1,132 @@
|
|
|
1
|
-
# @riebeckite/plugin-rich-embed
|
|
2
|
-
|
|
3
|
-
` ```embed ` コードブロックを、ビルド時に外部メディアの埋め込みへ変換するプラグインです。
|
|
4
|
-
|
|
5
|
-
[English](./README.md)
|
|
6
|
-
|
|
7
|
-
## 概要
|
|
8
|
-
|
|
9
|
-
`richEmbed()` は ` ```embed ` フェンスをレスポンシブな
|
|
10
|
-
`<figure class="rb-rich-embed">` に置き換えます。プロバイダの判定は URL の文字列解析だけで行うため、ビルド時にネットワークへアクセスしません。クライアント側 JavaScript も不要です。
|
|
11
|
-
|
|
12
|
-
## 使い方
|
|
13
|
-
|
|
14
|
-
```ts
|
|
15
|
-
import { defineConfig } from "@riebeckite/core";
|
|
16
|
-
import { richEmbed } from "@riebeckite/plugin-rich-embed";
|
|
17
|
-
|
|
18
|
-
export default defineConfig({
|
|
19
|
-
// ...
|
|
20
|
-
plugins: [
|
|
21
|
-
richEmbed({
|
|
22
|
-
allowHosts: ["player.example.com"],
|
|
23
|
-
}),
|
|
24
|
-
],
|
|
25
|
-
});
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## 構文
|
|
29
|
-
|
|
30
|
-
最初の空でない行が URL、それ以降の `key: value` 行がオプションです。
|
|
31
|
-
|
|
32
|
-
````md
|
|
33
|
-
```embed
|
|
34
|
-
https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
35
|
-
title: デモ動画
|
|
36
|
-
caption: 枠の下に表示するキャプション
|
|
37
|
-
aspect: 16/9
|
|
38
|
-
start: 30
|
|
39
|
-
```
|
|
40
|
-
````
|
|
41
|
-
|
|
42
|
-
| ブロックオプション | 説明 |
|
|
43
|
-
| ------------------ | ---- |
|
|
44
|
-
| `title` | `<iframe>` の `title` 属性（Gist ではリンクのラベル） |
|
|
45
|
-
| `caption` | `<figcaption class="rb-rich-embed__caption">` として出力 |
|
|
46
|
-
| `aspect` | `16/9` や `4/3` などのアスペクト比（既定は `16/9`） |
|
|
47
|
-
| `start` | 開始位置（秒、YouTube のみ） |
|
|
48
|
-
|
|
49
|
-
未知のキーは無視します。`aspect` が不正な場合は `16/9` に戻します。
|
|
50
|
-
|
|
51
|
-
## 対応プロバイダ
|
|
52
|
-
|
|
53
|
-
| プロバイダ | 認識する URL | 出力する `src` |
|
|
54
|
-
| ---------- | ------------ | -------------- |
|
|
55
|
-
| YouTube | `youtube.com/watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`, `/live/` | `https://www.youtube-nocookie.com/embed/<id>` |
|
|
56
|
-
| Vimeo | `vimeo.com/<数値ID>` | `https://player.vimeo.com/video/<id>` |
|
|
57
|
-
| Spotify | `open.spotify.com/(track\|album\|playlist\|episode\|show)/<id>` | `https://open.spotify.com/embed/<type>/<id>` |
|
|
58
|
-
| CodePen | `codepen.io/<user>/pen/<id>` | `https://codepen.io/<user>/embed/<id>` |
|
|
59
|
-
| GitHub Gist | `gist.github.com/...` | リンクカード（iframe 埋め込み不可） |
|
|
60
|
-
|
|
61
|
-
ホストを判別できない場合はブロックをそのまま残し、警告の診断を出します。汎用 `<iframe>` を出力するのは、ホストが `allowHosts` に含まれる場合だけです。
|
|
62
|
-
|
|
63
|
-
## オプション
|
|
64
|
-
|
|
65
|
-
| オプション | 型 | 既定値 | 説明 |
|
|
66
|
-
| ---------- | -- | ------ | ---- |
|
|
67
|
-
| `allowHosts` | `string[]` | `[]` | 汎用 iframe へのフォールバックを許可するホスト名 |
|
|
68
|
-
| `providers` | `RichEmbedProvider[]` | すべて | 有効にするプロバイダの許可リスト |
|
|
69
|
-
| `disable` | `RichEmbedProvider[]` | `[]` | 無効にするプロバイダ（`providers` より優先） |
|
|
70
|
-
|
|
71
|
-
## 出力 HTML
|
|
72
|
-
|
|
73
|
-
```html
|
|
74
|
-
<figure
|
|
75
|
-
class="rb-rich-embed"
|
|
76
|
-
data-rich-embed="youtube"
|
|
77
|
-
data-rich-embed-marker="RIEBECKITE_EXTERNAL_RICHEMBED_MARKER"
|
|
78
|
-
>
|
|
79
|
-
<div class="rb-rich-embed__frame" style="--rb-rich-embed-aspect:16/9">
|
|
80
|
-
<iframe
|
|
81
|
-
src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
|
|
82
|
-
loading="lazy"
|
|
83
|
-
allowfullscreen
|
|
84
|
-
referrerpolicy="strict-origin-when-cross-origin"
|
|
85
|
-
title="デモ動画"
|
|
86
|
-
></iframe>
|
|
87
|
-
</div>
|
|
88
|
-
<figcaption class="rb-rich-embed__caption">キャプション</figcaption>
|
|
89
|
-
</figure>
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Gist の場合は iframe の代わりに
|
|
93
|
-
`div.rb-rich-embed__card > a.rb-rich-embed__link` を出力します。
|
|
94
|
-
|
|
95
|
-
### CSS フック
|
|
96
|
-
|
|
97
|
-
- `.rb-rich-embed` — 外側の figure
|
|
98
|
-
- `.rb-rich-embed__frame` — レスポンシブなラッパー（`--rb-rich-embed-aspect` を参照）
|
|
99
|
-
- `.rb-rich-embed__caption` — 任意のキャプション
|
|
100
|
-
- `.rb-rich-embed__card`, `.rb-rich-embed__link` — Gist のリンクカード
|
|
101
|
-
|
|
102
|
-
スタイルシートは `@riebeckite/plugin-rich-embed/style.css` として配布されます。
|
|
103
|
-
|
|
104
|
-
## 診断
|
|
105
|
-
|
|
106
|
-
未対応または不正なブロックは元のコードブロックを保持し、vfile のメッセージとして警告を報告します。
|
|
107
|
-
|
|
108
|
-
- `source: "@riebeckite/plugin-rich-embed"`
|
|
109
|
-
- `ruleId: "unsupported-embed"`
|
|
110
|
-
|
|
111
|
-
## セキュリティ
|
|
112
|
-
|
|
113
|
-
- `https:` の URL だけを受理します。
|
|
114
|
-
- プロバイダの出力は検証済みのパスセグメントから組み立て、動的な部分は `encodeURIComponent` を通します。
|
|
115
|
-
- 汎用 iframe には `allowHosts` への明示的な登録が必要です。
|
|
116
|
-
- 生のユーザー HTML は出力しません。タイトル・キャプション・ラベルはすべてエスケープされるテキストノードとして書き込みます。
|
|
117
|
-
|
|
118
|
-
## 制限事項
|
|
119
|
-
|
|
120
|
-
- OEMBED の取得やタイトル・サムネイルの自動検出は行いません。URL とブロックオプションだけから組み立てます。
|
|
121
|
-
- GitHub Gist は iframe で埋め込めないため、リンクカードとして表示します。
|
|
122
|
-
- 汎用埋め込みは `https:` の URL をそのまま使うため、信頼できるホストだけを許可してください。
|
|
123
|
-
|
|
124
|
-
## エクスポート
|
|
125
|
-
|
|
126
|
-
- `richEmbed(options?)` — プラグインファクトリ
|
|
127
|
-
- `richEmbedPlugin` — `richEmbed` の別名
|
|
128
|
-
- 型: `RichEmbedOptions`, `RichEmbedProvider`
|
|
129
|
-
|
|
130
|
-
## 関連
|
|
131
|
-
|
|
132
|
-
- [プラグインガイド](../../../docs/ja/plugin-
|
|
1
|
+
# @riebeckite/plugin-rich-embed
|
|
2
|
+
|
|
3
|
+
` ```embed ` コードブロックを、ビルド時に外部メディアの埋め込みへ変換するプラグインです。
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
## 概要
|
|
8
|
+
|
|
9
|
+
`richEmbed()` は ` ```embed ` フェンスをレスポンシブな
|
|
10
|
+
`<figure class="rb-rich-embed">` に置き換えます。プロバイダの判定は URL の文字列解析だけで行うため、ビルド時にネットワークへアクセスしません。クライアント側 JavaScript も不要です。
|
|
11
|
+
|
|
12
|
+
## 使い方
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { defineConfig } from "@riebeckite/core";
|
|
16
|
+
import { richEmbed } from "@riebeckite/plugin-rich-embed";
|
|
17
|
+
|
|
18
|
+
export default defineConfig({
|
|
19
|
+
// ...
|
|
20
|
+
plugins: [
|
|
21
|
+
richEmbed({
|
|
22
|
+
allowHosts: ["player.example.com"],
|
|
23
|
+
}),
|
|
24
|
+
],
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 構文
|
|
29
|
+
|
|
30
|
+
最初の空でない行が URL、それ以降の `key: value` 行がオプションです。
|
|
31
|
+
|
|
32
|
+
````md
|
|
33
|
+
```embed
|
|
34
|
+
https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
35
|
+
title: デモ動画
|
|
36
|
+
caption: 枠の下に表示するキャプション
|
|
37
|
+
aspect: 16/9
|
|
38
|
+
start: 30
|
|
39
|
+
```
|
|
40
|
+
````
|
|
41
|
+
|
|
42
|
+
| ブロックオプション | 説明 |
|
|
43
|
+
| ------------------ | ---- |
|
|
44
|
+
| `title` | `<iframe>` の `title` 属性（Gist ではリンクのラベル） |
|
|
45
|
+
| `caption` | `<figcaption class="rb-rich-embed__caption">` として出力 |
|
|
46
|
+
| `aspect` | `16/9` や `4/3` などのアスペクト比（既定は `16/9`） |
|
|
47
|
+
| `start` | 開始位置（秒、YouTube のみ） |
|
|
48
|
+
|
|
49
|
+
未知のキーは無視します。`aspect` が不正な場合は `16/9` に戻します。
|
|
50
|
+
|
|
51
|
+
## 対応プロバイダ
|
|
52
|
+
|
|
53
|
+
| プロバイダ | 認識する URL | 出力する `src` |
|
|
54
|
+
| ---------- | ------------ | -------------- |
|
|
55
|
+
| YouTube | `youtube.com/watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`, `/live/` | `https://www.youtube-nocookie.com/embed/<id>` |
|
|
56
|
+
| Vimeo | `vimeo.com/<数値ID>` | `https://player.vimeo.com/video/<id>` |
|
|
57
|
+
| Spotify | `open.spotify.com/(track\|album\|playlist\|episode\|show)/<id>` | `https://open.spotify.com/embed/<type>/<id>` |
|
|
58
|
+
| CodePen | `codepen.io/<user>/pen/<id>` | `https://codepen.io/<user>/embed/<id>` |
|
|
59
|
+
| GitHub Gist | `gist.github.com/...` | リンクカード（iframe 埋め込み不可） |
|
|
60
|
+
|
|
61
|
+
ホストを判別できない場合はブロックをそのまま残し、警告の診断を出します。汎用 `<iframe>` を出力するのは、ホストが `allowHosts` に含まれる場合だけです。
|
|
62
|
+
|
|
63
|
+
## オプション
|
|
64
|
+
|
|
65
|
+
| オプション | 型 | 既定値 | 説明 |
|
|
66
|
+
| ---------- | -- | ------ | ---- |
|
|
67
|
+
| `allowHosts` | `string[]` | `[]` | 汎用 iframe へのフォールバックを許可するホスト名 |
|
|
68
|
+
| `providers` | `RichEmbedProvider[]` | すべて | 有効にするプロバイダの許可リスト |
|
|
69
|
+
| `disable` | `RichEmbedProvider[]` | `[]` | 無効にするプロバイダ（`providers` より優先） |
|
|
70
|
+
|
|
71
|
+
## 出力 HTML
|
|
72
|
+
|
|
73
|
+
```html
|
|
74
|
+
<figure
|
|
75
|
+
class="rb-rich-embed"
|
|
76
|
+
data-rich-embed="youtube"
|
|
77
|
+
data-rich-embed-marker="RIEBECKITE_EXTERNAL_RICHEMBED_MARKER"
|
|
78
|
+
>
|
|
79
|
+
<div class="rb-rich-embed__frame" style="--rb-rich-embed-aspect:16/9">
|
|
80
|
+
<iframe
|
|
81
|
+
src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"
|
|
82
|
+
loading="lazy"
|
|
83
|
+
allowfullscreen
|
|
84
|
+
referrerpolicy="strict-origin-when-cross-origin"
|
|
85
|
+
title="デモ動画"
|
|
86
|
+
></iframe>
|
|
87
|
+
</div>
|
|
88
|
+
<figcaption class="rb-rich-embed__caption">キャプション</figcaption>
|
|
89
|
+
</figure>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Gist の場合は iframe の代わりに
|
|
93
|
+
`div.rb-rich-embed__card > a.rb-rich-embed__link` を出力します。
|
|
94
|
+
|
|
95
|
+
### CSS フック
|
|
96
|
+
|
|
97
|
+
- `.rb-rich-embed` — 外側の figure
|
|
98
|
+
- `.rb-rich-embed__frame` — レスポンシブなラッパー（`--rb-rich-embed-aspect` を参照）
|
|
99
|
+
- `.rb-rich-embed__caption` — 任意のキャプション
|
|
100
|
+
- `.rb-rich-embed__card`, `.rb-rich-embed__link` — Gist のリンクカード
|
|
101
|
+
|
|
102
|
+
スタイルシートは `@riebeckite/plugin-rich-embed/style.css` として配布されます。
|
|
103
|
+
|
|
104
|
+
## 診断
|
|
105
|
+
|
|
106
|
+
未対応または不正なブロックは元のコードブロックを保持し、vfile のメッセージとして警告を報告します。
|
|
107
|
+
|
|
108
|
+
- `source: "@riebeckite/plugin-rich-embed"`
|
|
109
|
+
- `ruleId: "unsupported-embed"`
|
|
110
|
+
|
|
111
|
+
## セキュリティ
|
|
112
|
+
|
|
113
|
+
- `https:` の URL だけを受理します。
|
|
114
|
+
- プロバイダの出力は検証済みのパスセグメントから組み立て、動的な部分は `encodeURIComponent` を通します。
|
|
115
|
+
- 汎用 iframe には `allowHosts` への明示的な登録が必要です。
|
|
116
|
+
- 生のユーザー HTML は出力しません。タイトル・キャプション・ラベルはすべてエスケープされるテキストノードとして書き込みます。
|
|
117
|
+
|
|
118
|
+
## 制限事項
|
|
119
|
+
|
|
120
|
+
- OEMBED の取得やタイトル・サムネイルの自動検出は行いません。URL とブロックオプションだけから組み立てます。
|
|
121
|
+
- GitHub Gist は iframe で埋め込めないため、リンクカードとして表示します。
|
|
122
|
+
- 汎用埋め込みは `https:` の URL をそのまま使うため、信頼できるホストだけを許可してください。
|
|
123
|
+
|
|
124
|
+
## エクスポート
|
|
125
|
+
|
|
126
|
+
- `richEmbed(options?)` — プラグインファクトリ
|
|
127
|
+
- `richEmbedPlugin` — `richEmbed` の別名
|
|
128
|
+
- 型: `RichEmbedOptions`, `RichEmbedProvider`
|
|
129
|
+
|
|
130
|
+
## 関連
|
|
131
|
+
|
|
132
|
+
- [プラグインガイド](../../../docs/ja/reference/plugin-api.md)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@riebeckite/plugin-rich-embed",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.14",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"./style.css": "./style.css"
|
|
16
16
|
},
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@riebeckite/core": "0.0.
|
|
18
|
+
"@riebeckite/core": "0.0.14"
|
|
19
19
|
},
|
|
20
20
|
"publishConfig": {
|
|
21
21
|
"access": "public"
|
|
@@ -50,6 +50,7 @@
|
|
|
50
50
|
"./style.css"
|
|
51
51
|
],
|
|
52
52
|
"scripts": {
|
|
53
|
-
"build": "node ../../../scripts/build_package.mjs"
|
|
53
|
+
"build": "node ../../../scripts/build_package.mjs",
|
|
54
|
+
"test": "node --import tsx --test \"test/*.test.ts\""
|
|
54
55
|
}
|
|
55
56
|
}
|