@riebeckite/plugin-mermaid 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 +84 -84
- package/README_ja.md +59 -59
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,84 +1,84 @@
|
|
|
1
|
-
# @riebeckite/plugin-mermaid
|
|
2
|
-
|
|
3
|
-
Mermaid diagram rendering for ` ```mermaid ` code blocks.
|
|
4
|
-
|
|
5
|
-
[日本語](./README_ja.md)
|
|
6
|
-
|
|
7
|
-
## Overview
|
|
8
|
-
|
|
9
|
-
`mermaid()` replaces mermaid code blocks with a `<figure class="rr-mermaid">`
|
|
10
|
-
that renders to SVG. Diagrams are rendered at build time with a headless browser by
|
|
11
|
-
default, with an automatic client-side fallback. It runs with `order: -10`.
|
|
12
|
-
|
|
13
|
-
## Usage
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import { defineConfig } from "@riebeckite/core";
|
|
17
|
-
import { mermaid } from "@riebeckite/plugin-mermaid";
|
|
18
|
-
|
|
19
|
-
export default defineConfig({
|
|
20
|
-
// ...
|
|
21
|
-
plugins: [
|
|
22
|
-
mermaid({
|
|
23
|
-
render: "build",
|
|
24
|
-
theme: { light: "default", dark: "dark" },
|
|
25
|
-
}),
|
|
26
|
-
],
|
|
27
|
-
});
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
## Behavior
|
|
31
|
-
|
|
32
|
-
### Build
|
|
33
|
-
|
|
34
|
-
- Replaces each ` ```mermaid ` `<pre>` with a `figure.rr-mermaid` containing:
|
|
35
|
-
- `figcaption.rr-mermaid__caption` — from the code block title or a
|
|
36
|
-
`%% caption: ...` line in the source
|
|
37
|
-
- `div.rr-mermaid__canvas` — the diagram (`role="img"`, labelled by the
|
|
38
|
-
caption when present)
|
|
39
|
-
- `details.rr-mermaid__fallback` — collapsible diagram source
|
|
40
|
-
- Static SVG is rendered at build time when `render` is `"build"` or
|
|
41
|
-
`"both"` by running the Mermaid browser API in Puppeteer's headless Chromium.
|
|
42
|
-
Rendering uses Chromium's layout engine, not JSDOM polyfills or custom
|
|
43
|
-
`getBBox` / text-width estimation
|
|
44
|
-
- Mermaid runs with `securityLevel: "strict"`, the selected theme, transparent
|
|
45
|
-
background, and a unique SVG id per diagram
|
|
46
|
-
- Invalid diagrams report `ruleId: "invalid-diagram"`; Chromium renderer
|
|
47
|
-
failures report `ruleId: "renderer-error"`. When build SVG is unavailable,
|
|
48
|
-
the figure remains `data-mermaid="pending"` for client fallback
|
|
49
|
-
|
|
50
|
-
### Client (`initMermaidDiagrams`)
|
|
51
|
-
|
|
52
|
-
- Loads Mermaid from the CDN (jsDelivr, Mermaid 11) unless `globalThis.mermaid`
|
|
53
|
-
or an injected instance is provided
|
|
54
|
-
- Renders every `[data-mermaid="pending"]` figure; failures set
|
|
55
|
-
`data-mermaid="error"` (placeholder message via CSS)
|
|
56
|
-
- When `theme` is `{ light, dark }`, the theme is chosen from
|
|
57
|
-
`html[data-theme]` or `prefers-color-scheme`
|
|
58
|
-
|
|
59
|
-
## Options
|
|
60
|
-
|
|
61
|
-
| Option | Type | Default | Description |
|
|
62
|
-
| ------ | ---- | ------- | ----------- |
|
|
63
|
-
| `render` | `"build" \| "client" \| "both"` | `"build"` | When diagrams are rendered |
|
|
64
|
-
| `theme` | `string \| { light: string; dark: string }` | `{ light: "default", dark: "dark" }` | Mermaid theme |
|
|
65
|
-
| `caption` | `boolean` | `true` | Show title / `%% caption:` as `figcaption` |
|
|
66
|
-
| `fallback` | `boolean` | `true` | Show the diagram source in `<details>` |
|
|
67
|
-
|
|
68
|
-
`render` modes:
|
|
69
|
-
|
|
70
|
-
- `"build"` — render SVG at build time; diagrams that fail fall back to client
|
|
71
|
-
rendering
|
|
72
|
-
- `"client"` — skip build-time rendering, render in the browser only
|
|
73
|
-
- `"both"` — compatibility alias. It currently behaves like `"build"`: build
|
|
74
|
-
first, then client fallback only when build rendering fails
|
|
75
|
-
|
|
76
|
-
## Exports
|
|
77
|
-
|
|
78
|
-
- `mermaid(options?)` — plugin factory
|
|
79
|
-
- Types: `MermaidOptions`, `MermaidClientOptions`, `MermaidRenderMode`,
|
|
80
|
-
`MermaidTheme`
|
|
81
|
-
|
|
82
|
-
## See also
|
|
83
|
-
|
|
84
|
-
- [Plugin guide](../../../docs/en/plugin-
|
|
1
|
+
# @riebeckite/plugin-mermaid
|
|
2
|
+
|
|
3
|
+
Mermaid diagram rendering for ` ```mermaid ` code blocks.
|
|
4
|
+
|
|
5
|
+
[日本語](./README_ja.md)
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
`mermaid()` replaces mermaid code blocks with a `<figure class="rr-mermaid">`
|
|
10
|
+
that renders to SVG. Diagrams are rendered at build time with a headless browser by
|
|
11
|
+
default, with an automatic client-side fallback. It runs with `order: -10`.
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { defineConfig } from "@riebeckite/core";
|
|
17
|
+
import { mermaid } from "@riebeckite/plugin-mermaid";
|
|
18
|
+
|
|
19
|
+
export default defineConfig({
|
|
20
|
+
// ...
|
|
21
|
+
plugins: [
|
|
22
|
+
mermaid({
|
|
23
|
+
render: "build",
|
|
24
|
+
theme: { light: "default", dark: "dark" },
|
|
25
|
+
}),
|
|
26
|
+
],
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Behavior
|
|
31
|
+
|
|
32
|
+
### Build
|
|
33
|
+
|
|
34
|
+
- Replaces each ` ```mermaid ` `<pre>` with a `figure.rr-mermaid` containing:
|
|
35
|
+
- `figcaption.rr-mermaid__caption` — from the code block title or a
|
|
36
|
+
`%% caption: ...` line in the source
|
|
37
|
+
- `div.rr-mermaid__canvas` — the diagram (`role="img"`, labelled by the
|
|
38
|
+
caption when present)
|
|
39
|
+
- `details.rr-mermaid__fallback` — collapsible diagram source
|
|
40
|
+
- Static SVG is rendered at build time when `render` is `"build"` or
|
|
41
|
+
`"both"` by running the Mermaid browser API in Puppeteer's headless Chromium.
|
|
42
|
+
Rendering uses Chromium's layout engine, not JSDOM polyfills or custom
|
|
43
|
+
`getBBox` / text-width estimation
|
|
44
|
+
- Mermaid runs with `securityLevel: "strict"`, the selected theme, transparent
|
|
45
|
+
background, and a unique SVG id per diagram
|
|
46
|
+
- Invalid diagrams report `ruleId: "invalid-diagram"`; Chromium renderer
|
|
47
|
+
failures report `ruleId: "renderer-error"`. When build SVG is unavailable,
|
|
48
|
+
the figure remains `data-mermaid="pending"` for client fallback
|
|
49
|
+
|
|
50
|
+
### Client (`initMermaidDiagrams`)
|
|
51
|
+
|
|
52
|
+
- Loads Mermaid from the CDN (jsDelivr, Mermaid 11) unless `globalThis.mermaid`
|
|
53
|
+
or an injected instance is provided
|
|
54
|
+
- Renders every `[data-mermaid="pending"]` figure; failures set
|
|
55
|
+
`data-mermaid="error"` (placeholder message via CSS)
|
|
56
|
+
- When `theme` is `{ light, dark }`, the theme is chosen from
|
|
57
|
+
`html[data-theme]` or `prefers-color-scheme`
|
|
58
|
+
|
|
59
|
+
## Options
|
|
60
|
+
|
|
61
|
+
| Option | Type | Default | Description |
|
|
62
|
+
| ------ | ---- | ------- | ----------- |
|
|
63
|
+
| `render` | `"build" \| "client" \| "both"` | `"build"` | When diagrams are rendered |
|
|
64
|
+
| `theme` | `string \| { light: string; dark: string }` | `{ light: "default", dark: "dark" }` | Mermaid theme |
|
|
65
|
+
| `caption` | `boolean` | `true` | Show title / `%% caption:` as `figcaption` |
|
|
66
|
+
| `fallback` | `boolean` | `true` | Show the diagram source in `<details>` |
|
|
67
|
+
|
|
68
|
+
`render` modes:
|
|
69
|
+
|
|
70
|
+
- `"build"` — render SVG at build time; diagrams that fail fall back to client
|
|
71
|
+
rendering
|
|
72
|
+
- `"client"` — skip build-time rendering, render in the browser only
|
|
73
|
+
- `"both"` — compatibility alias. It currently behaves like `"build"`: build
|
|
74
|
+
first, then client fallback only when build rendering fails
|
|
75
|
+
|
|
76
|
+
## Exports
|
|
77
|
+
|
|
78
|
+
- `mermaid(options?)` — plugin factory
|
|
79
|
+
- Types: `MermaidOptions`, `MermaidClientOptions`, `MermaidRenderMode`,
|
|
80
|
+
`MermaidTheme`
|
|
81
|
+
|
|
82
|
+
## See also
|
|
83
|
+
|
|
84
|
+
- [Plugin guide](../../../docs/en/reference/plugin-api.md)
|
package/README_ja.md
CHANGED
|
@@ -1,59 +1,59 @@
|
|
|
1
|
-
# @riebeckite/plugin-mermaid
|
|
2
|
-
|
|
3
|
-
`mermaid` コードブロックを SVG の図として表示するプラグインです。既定ではビルド時に描画し、描画できなかった図だけをブラウザ側で再試行します。
|
|
4
|
-
|
|
5
|
-
[English](./README.md)
|
|
6
|
-
|
|
7
|
-
## 設定する
|
|
8
|
-
|
|
9
|
-
```ts
|
|
10
|
-
import { defineConfig } from "@riebeckite/core";
|
|
11
|
-
import { mermaid } from "@riebeckite/plugin-mermaid";
|
|
12
|
-
|
|
13
|
-
export default defineConfig({
|
|
14
|
-
// ...
|
|
15
|
-
plugins: [
|
|
16
|
-
mermaid({
|
|
17
|
-
render: "build",
|
|
18
|
-
theme: { light: "default", dark: "dark" },
|
|
19
|
-
}),
|
|
20
|
-
],
|
|
21
|
-
});
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
このプラグインは `order: -10` で実行されます。Mermaid のコードブロックを先に処理したい場合に適した順序です。
|
|
25
|
-
|
|
26
|
-
## どのように描画されるか
|
|
27
|
-
|
|
28
|
-
` ```mermaid ` のコードブロックは `figure.rr-mermaid` に置き換わります。図のタイトルはコードブロックの title、またはソース内の `%% caption: ...` 行から取得します。図には代替テキスト相当の `role="img"` を付け、必要に応じて元の記法を折りたたみ表示します。
|
|
29
|
-
|
|
30
|
-
`render: "build"` または `"both"` では、Puppeteer が起動するヘッドレス Chromium 上で Mermaid を実行し、静的な SVG を生成します。簡易な DOM 実装や寸法の推測には頼らないため、ブラウザと同じレイアウトエンジンで図を作れます。Mermaid は `securityLevel: "strict"` で実行されます。
|
|
31
|
-
|
|
32
|
-
構文エラーは `invalid-diagram`、描画環境の問題は `renderer-error` として区別して診断します。ビルドで SVG を作れなかった図には `data-mermaid="pending"` が付き、クライアント側が描画を引き継ぎます。
|
|
33
|
-
|
|
34
|
-
## クライアント側の再試行
|
|
35
|
-
|
|
36
|
-
`initMermaidDiagrams` は保留中の図だけを描画します。Mermaid のインスタンスがなければ jsDelivr から Mermaid 11 を読み込みます。描画に失敗した場合は `data-mermaid="error"` となり、CSS のプレースホルダー表示に切り替わります。
|
|
37
|
-
|
|
38
|
-
明暗別のテーマを指定した場合は、`html[data-theme]` を優先し、なければ OS の配色設定に従います。
|
|
39
|
-
|
|
40
|
-
## オプション
|
|
41
|
-
|
|
42
|
-
| 項目 | 既定値 | 説明 |
|
|
43
|
-
| --- | --- | --- |
|
|
44
|
-
| `render` | `"build"` | `"build"`、`"client"`、`"both"` のいずれで描画するか |
|
|
45
|
-
| `theme` | `{ light: "default", dark: "dark" }` | Mermaid のテーマ名、または明暗別のテーマ |
|
|
46
|
-
| `caption` | `true` | タイトルまたは `%% caption:` をキャプションとして表示する |
|
|
47
|
-
| `fallback` | `true` | 元の Mermaid 記法を `<details>` に残す |
|
|
48
|
-
|
|
49
|
-
`"client"` はビルド時の描画を行いません。`"both"` は後方互換の値で、現在は `"build"` と同じくビルドを優先し、失敗時だけクライアント側へ切り替えます。
|
|
50
|
-
|
|
51
|
-
## 主なエクスポート
|
|
52
|
-
|
|
53
|
-
- `mermaid(options?)`: プラグインを作成する
|
|
54
|
-
- `initMermaidDiagrams`: クライアント側の描画を初期化する
|
|
55
|
-
- 型: `MermaidOptions`、`MermaidClientOptions`、`MermaidRenderMode`、`MermaidTheme`
|
|
56
|
-
|
|
57
|
-
## 関連資料
|
|
58
|
-
|
|
59
|
-
- [プラグインシステム](../../../docs/ja/plugin-
|
|
1
|
+
# @riebeckite/plugin-mermaid
|
|
2
|
+
|
|
3
|
+
`mermaid` コードブロックを SVG の図として表示するプラグインです。既定ではビルド時に描画し、描画できなかった図だけをブラウザ側で再試行します。
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
## 設定する
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { defineConfig } from "@riebeckite/core";
|
|
11
|
+
import { mermaid } from "@riebeckite/plugin-mermaid";
|
|
12
|
+
|
|
13
|
+
export default defineConfig({
|
|
14
|
+
// ...
|
|
15
|
+
plugins: [
|
|
16
|
+
mermaid({
|
|
17
|
+
render: "build",
|
|
18
|
+
theme: { light: "default", dark: "dark" },
|
|
19
|
+
}),
|
|
20
|
+
],
|
|
21
|
+
});
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
このプラグインは `order: -10` で実行されます。Mermaid のコードブロックを先に処理したい場合に適した順序です。
|
|
25
|
+
|
|
26
|
+
## どのように描画されるか
|
|
27
|
+
|
|
28
|
+
` ```mermaid ` のコードブロックは `figure.rr-mermaid` に置き換わります。図のタイトルはコードブロックの title、またはソース内の `%% caption: ...` 行から取得します。図には代替テキスト相当の `role="img"` を付け、必要に応じて元の記法を折りたたみ表示します。
|
|
29
|
+
|
|
30
|
+
`render: "build"` または `"both"` では、Puppeteer が起動するヘッドレス Chromium 上で Mermaid を実行し、静的な SVG を生成します。簡易な DOM 実装や寸法の推測には頼らないため、ブラウザと同じレイアウトエンジンで図を作れます。Mermaid は `securityLevel: "strict"` で実行されます。
|
|
31
|
+
|
|
32
|
+
構文エラーは `invalid-diagram`、描画環境の問題は `renderer-error` として区別して診断します。ビルドで SVG を作れなかった図には `data-mermaid="pending"` が付き、クライアント側が描画を引き継ぎます。
|
|
33
|
+
|
|
34
|
+
## クライアント側の再試行
|
|
35
|
+
|
|
36
|
+
`initMermaidDiagrams` は保留中の図だけを描画します。Mermaid のインスタンスがなければ jsDelivr から Mermaid 11 を読み込みます。描画に失敗した場合は `data-mermaid="error"` となり、CSS のプレースホルダー表示に切り替わります。
|
|
37
|
+
|
|
38
|
+
明暗別のテーマを指定した場合は、`html[data-theme]` を優先し、なければ OS の配色設定に従います。
|
|
39
|
+
|
|
40
|
+
## オプション
|
|
41
|
+
|
|
42
|
+
| 項目 | 既定値 | 説明 |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| `render` | `"build"` | `"build"`、`"client"`、`"both"` のいずれで描画するか |
|
|
45
|
+
| `theme` | `{ light: "default", dark: "dark" }` | Mermaid のテーマ名、または明暗別のテーマ |
|
|
46
|
+
| `caption` | `true` | タイトルまたは `%% caption:` をキャプションとして表示する |
|
|
47
|
+
| `fallback` | `true` | 元の Mermaid 記法を `<details>` に残す |
|
|
48
|
+
|
|
49
|
+
`"client"` はビルド時の描画を行いません。`"both"` は後方互換の値で、現在は `"build"` と同じくビルドを優先し、失敗時だけクライアント側へ切り替えます。
|
|
50
|
+
|
|
51
|
+
## 主なエクスポート
|
|
52
|
+
|
|
53
|
+
- `mermaid(options?)`: プラグインを作成する
|
|
54
|
+
- `initMermaidDiagrams`: クライアント側の描画を初期化する
|
|
55
|
+
- 型: `MermaidOptions`、`MermaidClientOptions`、`MermaidRenderMode`、`MermaidTheme`
|
|
56
|
+
|
|
57
|
+
## 関連資料
|
|
58
|
+
|
|
59
|
+
- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@riebeckite/plugin-mermaid",
|
|
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",
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"dependencies": {
|
|
24
24
|
"mermaid": "^11.12.2",
|
|
25
25
|
"puppeteer": "^25.11.0",
|
|
26
|
-
"@riebeckite/core": "0.0.
|
|
26
|
+
"@riebeckite/core": "0.0.14"
|
|
27
27
|
},
|
|
28
28
|
"publishConfig": {
|
|
29
29
|
"access": "public"
|