@riebeckite/plugin-plantuml 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 +99 -99
  2. package/README_ja.md +81 -81
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,99 +1,99 @@
1
- # @riebeckite/plugin-plantuml
2
-
3
- PlantUML diagram rendering for ` ```plantuml ` code blocks. Diagrams are turned into
4
- a PlantUML server image URL at build time; the build itself never talks to the
5
- network and no client JavaScript is shipped.
6
-
7
- [日本語](./README_ja.md)
8
-
9
- ## Usage
10
-
11
- ```ts
12
- import { defineConfig } from "@riebeckite/core";
13
- import { plantuml } from "@riebeckite/plugin-plantuml";
14
-
15
- export default defineConfig({
16
- // ...
17
- plugins: [plantuml()],
18
- });
19
- ```
20
-
21
- `plantuml` is also exported under the alias `plantumlPlugin`.
22
-
23
- ## Behavior
24
-
25
- Each ` ```plantuml ` code block is replaced with a `figure.rb-plantuml` whose
26
- diagram is an `<img>` pointing at the PlantUML server.
27
-
28
- ```html
29
- <figure class="rb-plantuml" data-plantuml data-plantuml-marker="..." data-plantuml-source="...">
30
- <div class="rb-plantuml__frame">
31
- <img class="rb-plantuml__image" src="https://www.plantuml.com/plantuml/svg/..." alt="..." loading="lazy" />
32
- </div>
33
- <details class="rb-plantuml__fallback">
34
- <summary>Diagram source</summary>
35
- <pre><code>...</code></pre>
36
- </details>
37
- <figcaption class="rb-plantuml__caption">...</figcaption>
38
- </figure>
39
- ```
40
-
41
- The caption comes from the code block `title` or from a `%% caption: ...` line in
42
- the source. Because `%%` is not PlantUML comment syntax, the `%% caption:` line is
43
- removed from the diagram source before it is encoded. When there is no caption,
44
- the `<img>` alternative text is `PlantUML diagram`. With `fallback` enabled the
45
- original PlantUML source is kept in a collapsible `<details>` element.
46
-
47
- ## URL encoding
48
-
49
- The image URL is built at build time with PlantUML's *text encoding*:
50
-
51
- 1. Encode the source as UTF-8 bytes.
52
- 2. Compress them with raw DEFLATE (RFC 1951 — no zlib header or Adler-32).
53
- 3. Re-encode the bytes with PlantUML's custom base64 variant (alphabet
54
- `0-9A-Za-z-_`, packing 3 bytes into four 6-bit characters).
55
-
56
- The algorithm lives in `src/plantuml-encoder.ts`. It loads `node:zlib` through a
57
- dynamic `import` so a client bundle never pulls in a Node builtin. Encoding is
58
- fully build-time; no request is made to the PlantUML server.
59
-
60
- ## Options
61
-
62
- | Option | Type | Default | Description |
63
- | ------ | ---- | ------- | ----------- |
64
- | `server` | `string` | `"https://www.plantuml.com/plantuml"` | Base URL of the PlantUML server. `http(s)` only |
65
- | `format` | `"svg" \| "png"` | `"svg"` | Requested image format |
66
- | `caption` | `boolean` | `true` | Show `title` / `%% caption:` as `figcaption` |
67
- | `fallback` | `boolean` | `true` | Keep the diagram source in `<details>` |
68
-
69
- ## Output HTML / CSS
70
-
71
- The plugin ships `style.css` and emits stable class names: `rb-plantuml`,
72
- `rb-plantuml__frame`, `rb-plantuml__image`, `rb-plantuml__caption`, and
73
- `rb-plantuml__fallback`. Styling follows the `--rb-color-*` custom properties
74
- when present and switches to dark colors under `html[data-theme="dark"]` /
75
- `html.dark`.
76
-
77
- ## Diagnostics
78
-
79
- Encoding failures are reported with `file.message(...)`. Diagnostics use
80
- `source: "@riebeckite/plugin-plantuml"` and `ruleId` either `encoder-error`
81
- (encoding failed) or `empty-source` (no diagram source).
82
-
83
- ## Limitations
84
-
85
- - The configured PlantUML server must be reachable when a reader views the
86
- page. Offline readers see no diagram.
87
- - To self-host, point `server` at your own PlantUML base URL.
88
- - Because the build never contacts the server, diagram syntax is not validated
89
- at build time.
90
-
91
- ## Exports
92
-
93
- - `plantuml(options?)` — plugin factory
94
- - `plantumlPlugin` — alias of `plantuml`
95
- - Types: `PlantumlOptions`, `PlantumlFormat`
96
-
97
- ## See also
98
-
99
- - [Plugin guide](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-plantuml
2
+
3
+ PlantUML diagram rendering for ` ```plantuml ` code blocks. Diagrams are turned into
4
+ a PlantUML server image URL at build time; the build itself never talks to the
5
+ network and no client JavaScript is shipped.
6
+
7
+ [日本語](./README_ja.md)
8
+
9
+ ## Usage
10
+
11
+ ```ts
12
+ import { defineConfig } from "@riebeckite/core";
13
+ import { plantuml } from "@riebeckite/plugin-plantuml";
14
+
15
+ export default defineConfig({
16
+ // ...
17
+ plugins: [plantuml()],
18
+ });
19
+ ```
20
+
21
+ `plantuml` is also exported under the alias `plantumlPlugin`.
22
+
23
+ ## Behavior
24
+
25
+ Each ` ```plantuml ` code block is replaced with a `figure.rb-plantuml` whose
26
+ diagram is an `<img>` pointing at the PlantUML server.
27
+
28
+ ```html
29
+ <figure class="rb-plantuml" data-plantuml data-plantuml-marker="..." data-plantuml-source="...">
30
+ <div class="rb-plantuml__frame">
31
+ <img class="rb-plantuml__image" src="https://www.plantuml.com/plantuml/svg/..." alt="..." loading="lazy" />
32
+ </div>
33
+ <details class="rb-plantuml__fallback">
34
+ <summary>Diagram source</summary>
35
+ <pre><code>...</code></pre>
36
+ </details>
37
+ <figcaption class="rb-plantuml__caption">...</figcaption>
38
+ </figure>
39
+ ```
40
+
41
+ The caption comes from the code block `title` or from a `%% caption: ...` line in
42
+ the source. Because `%%` is not PlantUML comment syntax, the `%% caption:` line is
43
+ removed from the diagram source before it is encoded. When there is no caption,
44
+ the `<img>` alternative text is `PlantUML diagram`. With `fallback` enabled the
45
+ original PlantUML source is kept in a collapsible `<details>` element.
46
+
47
+ ## URL encoding
48
+
49
+ The image URL is built at build time with PlantUML's *text encoding*:
50
+
51
+ 1. Encode the source as UTF-8 bytes.
52
+ 2. Compress them with raw DEFLATE (RFC 1951 — no zlib header or Adler-32).
53
+ 3. Re-encode the bytes with PlantUML's custom base64 variant (alphabet
54
+ `0-9A-Za-z-_`, packing 3 bytes into four 6-bit characters).
55
+
56
+ The algorithm lives in `src/plantuml-encoder.ts`. It loads `node:zlib` through a
57
+ dynamic `import` so a client bundle never pulls in a Node builtin. Encoding is
58
+ fully build-time; no request is made to the PlantUML server.
59
+
60
+ ## Options
61
+
62
+ | Option | Type | Default | Description |
63
+ | ------ | ---- | ------- | ----------- |
64
+ | `server` | `string` | `"https://www.plantuml.com/plantuml"` | Base URL of the PlantUML server. `http(s)` only |
65
+ | `format` | `"svg" \| "png"` | `"svg"` | Requested image format |
66
+ | `caption` | `boolean` | `true` | Show `title` / `%% caption:` as `figcaption` |
67
+ | `fallback` | `boolean` | `true` | Keep the diagram source in `<details>` |
68
+
69
+ ## Output HTML / CSS
70
+
71
+ The plugin ships `style.css` and emits stable class names: `rb-plantuml`,
72
+ `rb-plantuml__frame`, `rb-plantuml__image`, `rb-plantuml__caption`, and
73
+ `rb-plantuml__fallback`. Styling follows the `--rb-color-*` custom properties
74
+ when present and switches to dark colors under `html[data-theme="dark"]` /
75
+ `html.dark`.
76
+
77
+ ## Diagnostics
78
+
79
+ Encoding failures are reported with `file.message(...)`. Diagnostics use
80
+ `source: "@riebeckite/plugin-plantuml"` and `ruleId` either `encoder-error`
81
+ (encoding failed) or `empty-source` (no diagram source).
82
+
83
+ ## Limitations
84
+
85
+ - The configured PlantUML server must be reachable when a reader views the
86
+ page. Offline readers see no diagram.
87
+ - To self-host, point `server` at your own PlantUML base URL.
88
+ - Because the build never contacts the server, diagram syntax is not validated
89
+ at build time.
90
+
91
+ ## Exports
92
+
93
+ - `plantuml(options?)` — plugin factory
94
+ - `plantumlPlugin` — alias of `plantuml`
95
+ - Types: `PlantumlOptions`, `PlantumlFormat`
96
+
97
+ ## See also
98
+
99
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,81 +1,81 @@
1
- # @riebeckite/plugin-plantuml
2
-
3
- `plantuml` コードブロックを PlantUML の図として表示するプラグインです。ビルド時に PlantUML サーバーの画像 URL を組み立てるだけで、ビルド中にネットワークへアクセスしません。クライアント用の JavaScript も配布しません。
4
-
5
- [English](./README.md)
6
-
7
- ## 設定する
8
-
9
- ```ts
10
- import { defineConfig } from "@riebeckite/core";
11
- import { plantuml } from "@riebeckite/plugin-plantuml";
12
-
13
- export default defineConfig({
14
- // ...
15
- plugins: [plantuml()],
16
- });
17
- ```
18
-
19
- `plantuml` は `plantumlPlugin` という別名でもエクスポートしています。
20
-
21
- ## どのように描画されるか
22
-
23
- ` ```plantuml ` のコードブロックは `figure.rb-plantuml` に置き換わります。図そのものは `<img>` で、PlantUML サーバーが返す画像を指します。
24
-
25
- ```html
26
- <figure class="rb-plantuml" data-plantuml data-plantuml-marker="..." data-plantuml-source="...">
27
- <div class="rb-plantuml__frame">
28
- <img class="rb-plantuml__image" src="https://www.plantuml.com/plantuml/svg/..." alt="..." loading="lazy" />
29
- </div>
30
- <details class="rb-plantuml__fallback">
31
- <summary>Diagram source</summary>
32
- <pre><code>...</code></pre>
33
- </details>
34
- <figcaption class="rb-plantuml__caption">...</figcaption>
35
- </figure>
36
- ```
37
-
38
- キャプションはコードブロックの `title`、またはソース中の `%% caption: ...` 行から取得します。`%%` は PlantUML のコメント記法ではないため、`%% caption:` 行は図のソースから取り除いてからエンコードします。キャプションがない場合、`<img>` の代替テキストは `PlantUML diagram` になります。`fallback` を有効にすると、元の PlantUML ソースを折りたたみ表示で残します。
39
-
40
- ## URL のエンコード
41
-
42
- 画像 URL は `text encoding` を使ってビルド時に組み立てます。手順は次のとおりです。
43
-
44
- 1. ソースを UTF-8 のバイト列にする
45
- 2. raw DEFLATE(RFC 1951、zlib ヘッダーや Adler-32 を含まない)で圧縮する
46
- 3. PlantUML 独自の base64(アルファベット `0-9A-Za-z-_`、3 バイトを 6 ビットずつ 4 文字へ)で再エンコードする
47
-
48
- この処理は `src/plantuml-encoder.ts` に実装しています。`node:zlib` は動的 `import` で読み込むため、クライアント向けのバンドルに Node 組み込みモジュールが混入しません。エンコードはビルド時に完結し、PlantUML サーバーへの問い合わせは行いません。
49
-
50
- ## オプション
51
-
52
- | 項目 | 既定値 | 説明 |
53
- | --- | --- | --- |
54
- | `server` | `https://www.plantuml.com/plantuml` | 図を配信する PlantUML サーバーのベース URL。`http(s)` のみ |
55
- | `format` | `"svg"` | 要求する画像形式。`"svg"` または `"png"` |
56
- | `caption` | `true` | `title` または `%% caption:` をキャプションとして表示する |
57
- | `fallback` | `true` | 元の PlantUML ソースを `<details>` に残す |
58
-
59
- ## 出力される HTML / CSS
60
-
61
- プラグインは `style.css` を公開し、`rb-plantuml`、`rb-plantuml__frame`、`rb-plantuml__image`、`rb-plantuml__caption`、`rb-plantuml__fallback` という安定したクラス名で出力します。CSS 変数 `--rb-color-*` があればそれに追従し、`html[data-theme="dark"]` / `html.dark` で暗色に切り替わります。
62
-
63
- ## 診断
64
-
65
- エンコードに失敗した場合は `file.message(...)` で診断を出します。診断の `source` は `@riebeckite/plugin-plantuml`、`ruleId` は `encoder-error`(エンコード失敗)または `empty-source`(空のソース)です。
66
-
67
- ## 制限
68
-
69
- - 表示時に設定した PlantUML サーバーへ到達できる必要があります。オフラインの閲覧環境では図は表示されません
70
- - 自前の PlantUML サーバーを使う場合は `server` にそのベース URL を指定してください
71
- - ビルド時にサーバーへ問い合わせないため、構文が正しいかどうかはビルド時には判定しません
72
-
73
- ## 主なエクスポート
74
-
75
- - `plantuml(options?)`: プラグインを作成する
76
- - `plantumlPlugin`: `plantuml` の別名
77
- - 型: `PlantumlOptions`、`PlantumlFormat`
78
-
79
- ## 関連資料
80
-
81
- - [プラグインシステム](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-plantuml
2
+
3
+ `plantuml` コードブロックを PlantUML の図として表示するプラグインです。ビルド時に PlantUML サーバーの画像 URL を組み立てるだけで、ビルド中にネットワークへアクセスしません。クライアント用の JavaScript も配布しません。
4
+
5
+ [English](./README.md)
6
+
7
+ ## 設定する
8
+
9
+ ```ts
10
+ import { defineConfig } from "@riebeckite/core";
11
+ import { plantuml } from "@riebeckite/plugin-plantuml";
12
+
13
+ export default defineConfig({
14
+ // ...
15
+ plugins: [plantuml()],
16
+ });
17
+ ```
18
+
19
+ `plantuml` は `plantumlPlugin` という別名でもエクスポートしています。
20
+
21
+ ## どのように描画されるか
22
+
23
+ ` ```plantuml ` のコードブロックは `figure.rb-plantuml` に置き換わります。図そのものは `<img>` で、PlantUML サーバーが返す画像を指します。
24
+
25
+ ```html
26
+ <figure class="rb-plantuml" data-plantuml data-plantuml-marker="..." data-plantuml-source="...">
27
+ <div class="rb-plantuml__frame">
28
+ <img class="rb-plantuml__image" src="https://www.plantuml.com/plantuml/svg/..." alt="..." loading="lazy" />
29
+ </div>
30
+ <details class="rb-plantuml__fallback">
31
+ <summary>Diagram source</summary>
32
+ <pre><code>...</code></pre>
33
+ </details>
34
+ <figcaption class="rb-plantuml__caption">...</figcaption>
35
+ </figure>
36
+ ```
37
+
38
+ キャプションはコードブロックの `title`、またはソース中の `%% caption: ...` 行から取得します。`%%` は PlantUML のコメント記法ではないため、`%% caption:` 行は図のソースから取り除いてからエンコードします。キャプションがない場合、`<img>` の代替テキストは `PlantUML diagram` になります。`fallback` を有効にすると、元の PlantUML ソースを折りたたみ表示で残します。
39
+
40
+ ## URL のエンコード
41
+
42
+ 画像 URL は `text encoding` を使ってビルド時に組み立てます。手順は次のとおりです。
43
+
44
+ 1. ソースを UTF-8 のバイト列にする
45
+ 2. raw DEFLATE(RFC 1951、zlib ヘッダーや Adler-32 を含まない)で圧縮する
46
+ 3. PlantUML 独自の base64(アルファベット `0-9A-Za-z-_`、3 バイトを 6 ビットずつ 4 文字へ)で再エンコードする
47
+
48
+ この処理は `src/plantuml-encoder.ts` に実装しています。`node:zlib` は動的 `import` で読み込むため、クライアント向けのバンドルに Node 組み込みモジュールが混入しません。エンコードはビルド時に完結し、PlantUML サーバーへの問い合わせは行いません。
49
+
50
+ ## オプション
51
+
52
+ | 項目 | 既定値 | 説明 |
53
+ | --- | --- | --- |
54
+ | `server` | `https://www.plantuml.com/plantuml` | 図を配信する PlantUML サーバーのベース URL。`http(s)` のみ |
55
+ | `format` | `"svg"` | 要求する画像形式。`"svg"` または `"png"` |
56
+ | `caption` | `true` | `title` または `%% caption:` をキャプションとして表示する |
57
+ | `fallback` | `true` | 元の PlantUML ソースを `<details>` に残す |
58
+
59
+ ## 出力される HTML / CSS
60
+
61
+ プラグインは `style.css` を公開し、`rb-plantuml`、`rb-plantuml__frame`、`rb-plantuml__image`、`rb-plantuml__caption`、`rb-plantuml__fallback` という安定したクラス名で出力します。CSS 変数 `--rb-color-*` があればそれに追従し、`html[data-theme="dark"]` / `html.dark` で暗色に切り替わります。
62
+
63
+ ## 診断
64
+
65
+ エンコードに失敗した場合は `file.message(...)` で診断を出します。診断の `source` は `@riebeckite/plugin-plantuml`、`ruleId` は `encoder-error`(エンコード失敗)または `empty-source`(空のソース)です。
66
+
67
+ ## 制限
68
+
69
+ - 表示時に設定した PlantUML サーバーへ到達できる必要があります。オフラインの閲覧環境では図は表示されません
70
+ - 自前の PlantUML サーバーを使う場合は `server` にそのベース URL を指定してください
71
+ - ビルド時にサーバーへ問い合わせないため、構文が正しいかどうかはビルド時には判定しません
72
+
73
+ ## 主なエクスポート
74
+
75
+ - `plantuml(options?)`: プラグインを作成する
76
+ - `plantumlPlugin`: `plantuml` の別名
77
+ - 型: `PlantumlOptions`、`PlantumlFormat`
78
+
79
+ ## 関連資料
80
+
81
+ - [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-plantuml",
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,7 +15,7 @@
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
  "publishConfig": {
21
21
  "access": "public"