@riebeckite/plugin-responsive-image 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.
Files changed (3) hide show
  1. package/README.md +93 -93
  2. package/README_ja.md +73 -73
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,93 +1,93 @@
1
- # @riebeckite/plugin-responsive-image
2
-
3
- Upgrades existing `<img>` elements with lazy loading and responsive
4
- `<picture>` / `srcset` markup, using only image variants that are already
5
- present in the content manifest.
6
-
7
- [日本語](./README_ja.md)
8
-
9
- ## Overview
10
-
11
- `responsiveImage()` runs as a build-time HTML layer:
12
-
13
- 1. It always adds `loading="lazy"` and `decoding="async"` to `<img>` elements
14
- unless those attributes are already set.
15
- 2. It adds a `sizes` attribute when one is missing.
16
- 3. It looks for sibling variants that already exist in the manifest
17
- (`photo.webp`, `photo.avif`, `photo-640.webp`, `photo-640.png`, …). When
18
- variants are found the `<img>` becomes a `<picture>` element with grouped
19
- `<source>` elements. When no variants are found the `<img>` is left in place
20
- with just the added attributes.
21
-
22
- The plugin never fabricates URLs and never writes files. It only references
23
- assets that the manifest already knows about.
24
-
25
- ## Usage
26
-
27
- ```ts
28
- import { defineConfig } from "@riebeckite/core";
29
- import { attachment } from "@riebeckite/plugin-attachment";
30
- import { obsidianMarkdown } from "@riebeckite/plugin-obsidian-markdown";
31
- import { responsiveImage } from "@riebeckite/plugin-responsive-image";
32
-
33
- export default defineConfig({
34
- // ...
35
- plugins: [obsidianMarkdown(), attachment(), responsiveImage()],
36
- });
37
- ```
38
-
39
- `responsiveImage()` uses `order: 100`, so it runs after the media and
40
- attachment renderers.
41
-
42
- ## Options
43
-
44
- | Option | Type | Default | Description |
45
- | ------ | ---- | ------- | ----------- |
46
- | `lazy` | `boolean` | `true` | Adds `loading="lazy"` when absent |
47
- | `decoding` | `boolean` | `true` | Adds `decoding="async"` when absent |
48
- | `sizes` | `string` | `"100vw"` | Fallback `sizes` value added when absent |
49
- | `widths` | `number[]` | `[640, 1280, 1920]` | Width variants to look up |
50
- | `formats` | `string[]` | `["webp", "avif"]` | Format variants to look up |
51
- | `className` | `string` | `"rb-responsive-image"` | Class applied to `<picture>` |
52
- | `generate` | `boolean` | `false` | Reserved |
53
- | `outputDir` | `string` | unset | Reserved |
54
-
55
- ## Variant discovery
56
-
57
- Variants are matched against the asset paths the manifest already contains:
58
-
59
- - format variants: `photo.webp`, `photo.avif`
60
- - width variants: `photo-640.webp`, `photo-1280.avif`, `photo-1920.png`
61
- - width variants in the original format: `photo-640.png`
62
-
63
- The plugin maps the original `<img src>` back to a manifest asset by trying the
64
- site asset URL (`/attachments/photo.png`) and the attachment URL
65
- (`/assets/attachments/photo.png`). If the source cannot be matched to a manifest
66
- asset, the `<img>` is left untouched.
67
-
68
- ## Limitation: no image encoding
69
-
70
- This plugin is a deterministic discovery/HTML layer. It does **not** encode or
71
- generate new image files by default. `PluginAsset` only supports `style` and
72
- `script` module specifiers, so Core currently exposes no supported way for a
73
- plugin to emit arbitrary binary files into the build output.
74
-
75
- `generate` and `outputDir` are reserved for a future release and do nothing
76
- today. Adding real encoding requires a Core file-emission API; until then,
77
- pre-generate the variants yourself (for example with an external image tool) and
78
- commit them next to the original image. Sites copy referenced vault assets into
79
- `public/` through `apps/web/scripts/build_images.ts`.
80
-
81
- ## Exports
82
-
83
- - `responsiveImage(options?)` / `responsiveImagePlugin` — plugin factory
84
- - `resolveResponsiveImageOptions(options?)` — resolve defaults
85
- - `buildResponsiveSrcset(existingPaths, src, options?)` — pure srcset planner
86
- - `applyResponsiveImages(html, existingPaths, options?)` — HTML transform
87
- - `collectKnownAssetPaths(manifest)` — manifest asset set helper
88
- - Types: `ResponsiveImageOptions`, `ResolvedResponsiveImageOptions`,
89
- `ResponsiveImagePlan`, `ResponsiveImageSource`, `ResponsiveImageVariant`
90
-
91
- ## See also
92
-
93
- - [Plugin guide](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-responsive-image
2
+
3
+ Upgrades existing `<img>` elements with lazy loading and responsive
4
+ `<picture>` / `srcset` markup, using only image variants that are already
5
+ present in the content manifest.
6
+
7
+ [日本語](./README_ja.md)
8
+
9
+ ## Overview
10
+
11
+ `responsiveImage()` runs as a build-time HTML layer:
12
+
13
+ 1. It always adds `loading="lazy"` and `decoding="async"` to `<img>` elements
14
+ unless those attributes are already set.
15
+ 2. It adds a `sizes` attribute when one is missing.
16
+ 3. It looks for sibling variants that already exist in the manifest
17
+ (`photo.webp`, `photo.avif`, `photo-640.webp`, `photo-640.png`, …). When
18
+ variants are found the `<img>` becomes a `<picture>` element with grouped
19
+ `<source>` elements. When no variants are found the `<img>` is left in place
20
+ with just the added attributes.
21
+
22
+ The plugin never fabricates URLs and never writes files. It only references
23
+ assets that the manifest already knows about.
24
+
25
+ ## Usage
26
+
27
+ ```ts
28
+ import { defineConfig } from "@riebeckite/core";
29
+ import { attachment } from "@riebeckite/plugin-attachment";
30
+ import { obsidianMarkdown } from "@riebeckite/plugin-obsidian-markdown";
31
+ import { responsiveImage } from "@riebeckite/plugin-responsive-image";
32
+
33
+ export default defineConfig({
34
+ // ...
35
+ plugins: [obsidianMarkdown(), attachment(), responsiveImage()],
36
+ });
37
+ ```
38
+
39
+ `responsiveImage()` uses `order: 100`, so it runs after the media and
40
+ attachment renderers.
41
+
42
+ ## Options
43
+
44
+ | Option | Type | Default | Description |
45
+ | ------ | ---- | ------- | ----------- |
46
+ | `lazy` | `boolean` | `true` | Adds `loading="lazy"` when absent |
47
+ | `decoding` | `boolean` | `true` | Adds `decoding="async"` when absent |
48
+ | `sizes` | `string` | `"100vw"` | Fallback `sizes` value added when absent |
49
+ | `widths` | `number[]` | `[640, 1280, 1920]` | Width variants to look up |
50
+ | `formats` | `string[]` | `["webp", "avif"]` | Format variants to look up |
51
+ | `className` | `string` | `"rb-responsive-image"` | Class applied to `<picture>` |
52
+ | `generate` | `boolean` | `false` | Reserved |
53
+ | `outputDir` | `string` | unset | Reserved |
54
+
55
+ ## Variant discovery
56
+
57
+ Variants are matched against the asset paths the manifest already contains:
58
+
59
+ - format variants: `photo.webp`, `photo.avif`
60
+ - width variants: `photo-640.webp`, `photo-1280.avif`, `photo-1920.png`
61
+ - width variants in the original format: `photo-640.png`
62
+
63
+ The plugin maps the original `<img src>` back to a manifest asset by trying the
64
+ site asset URL (`/attachments/photo.png`) and the attachment URL
65
+ (`/assets/attachments/photo.png`). If the source cannot be matched to a manifest
66
+ asset, the `<img>` is left untouched.
67
+
68
+ ## Limitation: no image encoding
69
+
70
+ This plugin is a deterministic discovery/HTML layer. It does **not** encode or
71
+ generate new image files by default. `PluginAsset` only supports `style` and
72
+ `script` module specifiers, so Core currently exposes no supported way for a
73
+ plugin to emit arbitrary binary files into the build output.
74
+
75
+ `generate` and `outputDir` are reserved for a future release and do nothing
76
+ today. Adding real encoding requires a Core file-emission API; until then,
77
+ pre-generate the variants yourself (for example with an external image tool) and
78
+ commit them next to the original image. Sites copy referenced vault assets into
79
+ `public/` through `apps/web/scripts/build_images.ts`.
80
+
81
+ ## Exports
82
+
83
+ - `responsiveImage(options?)` / `responsiveImagePlugin` — plugin factory
84
+ - `resolveResponsiveImageOptions(options?)` — resolve defaults
85
+ - `buildResponsiveSrcset(existingPaths, src, options?)` — pure srcset planner
86
+ - `applyResponsiveImages(html, existingPaths, options?)` — HTML transform
87
+ - `collectKnownAssetPaths(manifest)` — manifest asset set helper
88
+ - Types: `ResponsiveImageOptions`, `ResolvedResponsiveImageOptions`,
89
+ `ResponsiveImagePlan`, `ResponsiveImageSource`, `ResponsiveImageVariant`
90
+
91
+ ## See also
92
+
93
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,73 +1,73 @@
1
- # @riebeckite/plugin-responsive-image
2
-
3
- 既存の `<img>` に遅延読み込みと、レスポンシブな `<picture>` / `srcset` を付与するプラグインです。参照するのは、すでにコンテンツマニフェストに存在する画像バリアントだけです。
4
-
5
- [English](./README.md)
6
-
7
- ## できること
8
-
9
- `responsiveImage()` はビルド時の HTML レイヤーとして動作します。
10
-
11
- 1. `<img>` に `loading="lazy"` と `decoding="async"` を付与します。すでに属性がある場合は変更しません。
12
- 2. `sizes` がなければ追加します。
13
- 3. マニフェスト上に存在する兄弟バリアント（`photo.webp`、`photo.avif`、`photo-640.webp`、`photo-640.png` など）を探します。見つかれば `<img>` を `<picture>` に置き換え、形式ごとの `<source>` を並べます。見つからなければ `<img>` のまま、追加属性だけを残します。
14
-
15
- URL を捏造することはありません。ファイルを書き出すこともありません。マニフェストが把握しているアセットだけを参照します。
16
-
17
- ## 設定
18
-
19
- ```ts
20
- import { defineConfig } from "@riebeckite/core";
21
- import { attachment } from "@riebeckite/plugin-attachment";
22
- import { obsidianMarkdown } from "@riebeckite/plugin-obsidian-markdown";
23
- import { responsiveImage } from "@riebeckite/plugin-responsive-image";
24
-
25
- export default defineConfig({
26
- // ...
27
- plugins: [obsidianMarkdown(), attachment(), responsiveImage()],
28
- });
29
- ```
30
-
31
- `responsiveImage()` は `order: 100` で動作するため、メディアと添付ファイルのレンダラーより後に実行されます。
32
-
33
- ## オプション
34
-
35
- | オプション | 型 | 既定値 | 内容 |
36
- | --- | --- | --- | --- |
37
- | `lazy` | `boolean` | `true` | 未指定時に `loading="lazy"` を付与 |
38
- | `decoding` | `boolean` | `true` | 未指定時に `decoding="async"` を付与 |
39
- | `sizes` | `string` | `"100vw"` | 未指定時に追加する `sizes` |
40
- | `widths` | `number[]` | `[640, 1280, 1920]` | 探索する幅バリアント |
41
- | `formats` | `string[]` | `["webp", "avif"]` | 探索する形式バリアント |
42
- | `className` | `string` | `"rb-responsive-image"` | `<picture>` に付与するクラス |
43
- | `generate` | `boolean` | `false` | 予約 |
44
- | `outputDir` | `string` | 未設定 | 予約 |
45
-
46
- ## バリアントの探索
47
-
48
- バリアントは、マニフェストに登録済みのアセットパスと照合します。
49
-
50
- - 形式バリアント: `photo.webp`、`photo.avif`
51
- - 幅バリアント: `photo-640.webp`、`photo-1280.avif`、`photo-1920.png`
52
- - 元の形式の幅バリアント: `photo-640.png`
53
-
54
- 元の `<img src>` は、サイトのアセット URL（`/attachments/photo.png`）と添付ファイル URL（`/assets/attachments/photo.png`）の両方を試して、マニフェスト上のアセットに対応付けます。対応するアセットが見つからない `<img>` はそのまま残します。
55
-
56
- ## 制約: 画像のエンコードはしない
57
-
58
- このプラグインは、決定的な探索と HTML 変換だけを担当します。既定では新しい画像ファイルを生成しません。`PluginAsset` は `style` と `script` のモジュール指定子しか扱えず、プラグインが任意のバイナリファイルをビルド成果物へ出力する手段を Core は提供していません。
59
-
60
- `generate` と `outputDir` は将来のリリース向けの予約で、現在は何もしません。実際のエンコードには Core のファイル出力 API が必要です。それまでは、外部の画像ツールなどでバリアントを事前生成し、元画像の隣にコミットしてください。サイト側では `apps/web/scripts/build_images.ts` が、参照されたボールト内アセットを `public/` へコピーします。
61
-
62
- ## 公開 API
63
-
64
- - `responsiveImage(options?)` / `responsiveImagePlugin` — プラグインファクトリ
65
- - `resolveResponsiveImageOptions(options?)` — 既定値の解決
66
- - `buildResponsiveSrcset(existingPaths, src, options?)` — 純粋な srcset 計画
67
- - `applyResponsiveImages(html, existingPaths, options?)` — HTML 変換
68
- - `collectKnownAssetPaths(manifest)` — マニフェストのアセット集合を取得
69
- - 型: `ResponsiveImageOptions`、`ResolvedResponsiveImageOptions`、`ResponsiveImagePlan`、`ResponsiveImageSource`、`ResponsiveImageVariant`
70
-
71
- ## ????
72
-
73
- - [?????????](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-responsive-image
2
+
3
+ 既存の `<img>` に遅延読み込みと、レスポンシブな `<picture>` / `srcset` を付与するプラグインです。参照するのは、すでにコンテンツマニフェストに存在する画像バリアントだけです。
4
+
5
+ [English](./README.md)
6
+
7
+ ## できること
8
+
9
+ `responsiveImage()` はビルド時の HTML レイヤーとして動作します。
10
+
11
+ 1. `<img>` に `loading="lazy"` と `decoding="async"` を付与します。すでに属性がある場合は変更しません。
12
+ 2. `sizes` がなければ追加します。
13
+ 3. マニフェスト上に存在する兄弟バリアント（`photo.webp`、`photo.avif`、`photo-640.webp`、`photo-640.png` など）を探します。見つかれば `<img>` を `<picture>` に置き換え、形式ごとの `<source>` を並べます。見つからなければ `<img>` のまま、追加属性だけを残します。
14
+
15
+ URL を捏造することはありません。ファイルを書き出すこともありません。マニフェストが把握しているアセットだけを参照します。
16
+
17
+ ## 設定
18
+
19
+ ```ts
20
+ import { defineConfig } from "@riebeckite/core";
21
+ import { attachment } from "@riebeckite/plugin-attachment";
22
+ import { obsidianMarkdown } from "@riebeckite/plugin-obsidian-markdown";
23
+ import { responsiveImage } from "@riebeckite/plugin-responsive-image";
24
+
25
+ export default defineConfig({
26
+ // ...
27
+ plugins: [obsidianMarkdown(), attachment(), responsiveImage()],
28
+ });
29
+ ```
30
+
31
+ `responsiveImage()` は `order: 100` で動作するため、メディアと添付ファイルのレンダラーより後に実行されます。
32
+
33
+ ## オプション
34
+
35
+ | オプション | 型 | 既定値 | 内容 |
36
+ | --- | --- | --- | --- |
37
+ | `lazy` | `boolean` | `true` | 未指定時に `loading="lazy"` を付与 |
38
+ | `decoding` | `boolean` | `true` | 未指定時に `decoding="async"` を付与 |
39
+ | `sizes` | `string` | `"100vw"` | 未指定時に追加する `sizes` |
40
+ | `widths` | `number[]` | `[640, 1280, 1920]` | 探索する幅バリアント |
41
+ | `formats` | `string[]` | `["webp", "avif"]` | 探索する形式バリアント |
42
+ | `className` | `string` | `"rb-responsive-image"` | `<picture>` に付与するクラス |
43
+ | `generate` | `boolean` | `false` | 予約 |
44
+ | `outputDir` | `string` | 未設定 | 予約 |
45
+
46
+ ## バリアントの探索
47
+
48
+ バリアントは、マニフェストに登録済みのアセットパスと照合します。
49
+
50
+ - 形式バリアント: `photo.webp`、`photo.avif`
51
+ - 幅バリアント: `photo-640.webp`、`photo-1280.avif`、`photo-1920.png`
52
+ - 元の形式の幅バリアント: `photo-640.png`
53
+
54
+ 元の `<img src>` は、サイトのアセット URL（`/attachments/photo.png`）と添付ファイル URL（`/assets/attachments/photo.png`）の両方を試して、マニフェスト上のアセットに対応付けます。対応するアセットが見つからない `<img>` はそのまま残します。
55
+
56
+ ## 制約: 画像のエンコードはしない
57
+
58
+ このプラグインは、決定的な探索と HTML 変換だけを担当します。既定では新しい画像ファイルを生成しません。`PluginAsset` は `style` と `script` のモジュール指定子しか扱えず、プラグインが任意のバイナリファイルをビルド成果物へ出力する手段を Core は提供していません。
59
+
60
+ `generate` と `outputDir` は将来のリリース向けの予約で、現在は何もしません。実際のエンコードには Core のファイル出力 API が必要です。それまでは、外部の画像ツールなどでバリアントを事前生成し、元画像の隣にコミットしてください。サイト側では `apps/web/scripts/build_images.ts` が、参照されたボールト内アセットを `public/` へコピーします。
61
+
62
+ ## 公開 API
63
+
64
+ - `responsiveImage(options?)` / `responsiveImagePlugin` — プラグインファクトリ
65
+ - `resolveResponsiveImageOptions(options?)` — 既定値の解決
66
+ - `buildResponsiveSrcset(existingPaths, src, options?)` — 純粋な srcset 計画
67
+ - `applyResponsiveImages(html, existingPaths, options?)` — HTML 変換
68
+ - `collectKnownAssetPaths(manifest)` — マニフェストのアセット集合を取得
69
+ - 型: `ResponsiveImageOptions`、`ResolvedResponsiveImageOptions`、`ResponsiveImagePlan`、`ResponsiveImageSource`、`ResponsiveImageVariant`
70
+
71
+ ## ????
72
+
73
+ - [?????????](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-responsive-image",
3
- "version": "0.0.12",
3
+ "version": "0.0.13",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -15,11 +15,11 @@
15
15
  "./style.css": "./style.css"
16
16
  },
17
17
  "dependencies": {
18
- "@riebeckite/core": "0.0.12"
18
+ "@riebeckite/core": "0.0.13"
19
19
  },
20
20
  "devDependencies": {
21
21
  "tsx": "^4.22.4",
22
- "@riebeckite/test": "0.0.12"
22
+ "@riebeckite/test": "0.0.13"
23
23
  },
24
24
  "publishConfig": {
25
25
  "access": "public"