@riebeckite/plugin-markmap 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 +140 -140
- package/README_ja.md +113 -113
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,140 +1,140 @@
|
|
|
1
|
-
# @riebeckite/plugin-markmap
|
|
2
|
-
|
|
3
|
-
Renders ` ```markmap ` code blocks as Markdown-heading mindmaps. The mindmap is
|
|
4
|
-
drawn in the browser by `markmap-lib` + `markmap-view`, which are imported from
|
|
5
|
-
the CDN only when a figure is present.
|
|
6
|
-
|
|
7
|
-
[Japanese](./README_ja.md)
|
|
8
|
-
|
|
9
|
-
## Configure
|
|
10
|
-
|
|
11
|
-
```ts
|
|
12
|
-
import { defineConfig } from "@riebeckite/core";
|
|
13
|
-
import { markmap } from "@riebeckite/plugin-markmap";
|
|
14
|
-
|
|
15
|
-
export default defineConfig({
|
|
16
|
-
// ...
|
|
17
|
-
plugins: [
|
|
18
|
-
markmap({
|
|
19
|
-
caption: true,
|
|
20
|
-
height: 320,
|
|
21
|
-
fallback: true,
|
|
22
|
-
}),
|
|
23
|
-
],
|
|
24
|
-
});
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
The plugin runs with `order: -10`.
|
|
28
|
-
|
|
29
|
-
## Syntax
|
|
30
|
-
|
|
31
|
-
The block body is ordinary Markdown: headings become nodes and their nesting
|
|
32
|
-
becomes the tree. Content other than headings is ignored.
|
|
33
|
-
|
|
34
|
-
````markdown
|
|
35
|
-
```markmap
|
|
36
|
-
# Project
|
|
37
|
-
|
|
38
|
-
## Design
|
|
39
|
-
|
|
40
|
-
### Notation
|
|
41
|
-
### Rendering
|
|
42
|
-
|
|
43
|
-
## Delivery
|
|
44
|
-
```
|
|
45
|
-
````
|
|
46
|
-
|
|
47
|
-
The caption comes from the code-block `title`.
|
|
48
|
-
|
|
49
|
-
## How it renders
|
|
50
|
-
|
|
51
|
-
A ` ```markmap ` block becomes a `figure.rb-markmap`:
|
|
52
|
-
|
|
53
|
-
- `figure.rb-markmap`: carries `data-markmap="pending"`,
|
|
54
|
-
`data-markmap-source` (the raw Markdown) and `data-markmap-height`
|
|
55
|
-
- `div.rb-markmap__canvas`: the element the SVG is rendered into
|
|
56
|
-
(`role="img"`)
|
|
57
|
-
- `figcaption.rb-markmap__caption`: the caption (enabled by default)
|
|
58
|
-
- `details.rb-markmap__fallback`: the raw Markdown, folded away
|
|
59
|
-
|
|
60
|
-
`initMarkmap` finds every `[data-markmap="pending"]`, loads the runtime, runs
|
|
61
|
-
`markmap-lib`'s `Transformer` over `data-markmap-source`, and renders the
|
|
62
|
-
resulting tree with `markmap-view`'s `Markmap.create`. On success the figure
|
|
63
|
-
becomes `data-markmap="rendered"`.
|
|
64
|
-
|
|
65
|
-
If loading the runtime, transforming the source, or rendering fails, the
|
|
66
|
-
initializer does not throw: it opens that figure's `details` and marks it
|
|
67
|
-
`data-markmap="error"`.
|
|
68
|
-
|
|
69
|
-
A block whose body has no Markdown heading is left as a normal code block, and a
|
|
70
|
-
diagnostic with `source: "@riebeckite/plugin-markmap"` is emitted.
|
|
71
|
-
|
|
72
|
-
## Options
|
|
73
|
-
|
|
74
|
-
| Option | Default | Description |
|
|
75
|
-
| --- | --- | --- |
|
|
76
|
-
| `caption` | `true` | Show the code-block `title` as a caption |
|
|
77
|
-
| `height` | `320` | Canvas height in pixels |
|
|
78
|
-
| `className` | `"rb-markmap"` | Base class applied to the figure |
|
|
79
|
-
| `language` | `"markmap"` | Fenced-code language to recognize |
|
|
80
|
-
| `fallback` | `true` | Render the `<details>` block with the raw Markdown |
|
|
81
|
-
| `colorFreezeLevel` | — | Depth at which node colours are frozen |
|
|
82
|
-
|
|
83
|
-
## Client rendering
|
|
84
|
-
|
|
85
|
-
The client initializer is static and receives no plugin options. `height` and
|
|
86
|
-
`colorFreezeLevel` are embedded into the figure's `data-markmap-*` attributes,
|
|
87
|
-
and `initMarkmap` reads them from there.
|
|
88
|
-
|
|
89
|
-
`markmap-lib` and `markmap-view` are fetched from jsDelivr with a computed
|
|
90
|
-
import specifier, so they are never bundled into the host's client bundle.
|
|
91
|
-
`markmap-view` pulls `d3` in as its own dependency. Because the libraries are
|
|
92
|
-
loaded lazily, the page still renders (with the fallback `details`) when
|
|
93
|
-
JavaScript is disabled.
|
|
94
|
-
|
|
95
|
-
## The input-notation seam
|
|
96
|
-
|
|
97
|
-
The code-block body is turned into a mindmap tree by a single, pure function in
|
|
98
|
-
`src/parse.ts`:
|
|
99
|
-
|
|
100
|
-
```ts
|
|
101
|
-
parseMarkmapSource(source: string): MarkmapNode | null
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
`MarkmapNode` is the notation-neutral tree (`{ content, children, payload? }`).
|
|
105
|
-
Only the standard Markdown-heading notation is implemented today. A future
|
|
106
|
-
alternative notation (for example an "ExcaliMindMap"-style outline) is added by
|
|
107
|
-
implementing another parser that produces the same `MarkmapNode` shape; the
|
|
108
|
-
figure emission and the render path do not parse the notation themselves, so
|
|
109
|
-
they stay unchanged. `parseMarkmapSource` is exported from the package entry
|
|
110
|
-
point for that purpose.
|
|
111
|
-
|
|
112
|
-
## Output hooks
|
|
113
|
-
|
|
114
|
-
- `figure[data-markmap]`: state (`pending` / `rendered` / `error`)
|
|
115
|
-
- `figure[data-markmap-source]`: the raw Markdown
|
|
116
|
-
- `figure[data-markmap-height]`, `figure[data-markmap-color-freeze-level]`
|
|
117
|
-
- `[data-markmap-canvas]`: the render target
|
|
118
|
-
- `details.rb-markmap__fallback`: the raw Markdown
|
|
119
|
-
|
|
120
|
-
## Main exports
|
|
121
|
-
|
|
122
|
-
- `markmap(options?)`: create the plugin (`markmapPlugin` is an alias)
|
|
123
|
-
- `initMarkmap`: initialize client-side rendering
|
|
124
|
-
- `parseMarkmapSource`: parse the standard notation into a tree
|
|
125
|
-
- `describeMarkmapTree`: derive an accessible label from a tree
|
|
126
|
-
- Types: `MarkmapOptions`, `MarkmapNode`, `MarkmapClientOptions`
|
|
127
|
-
|
|
128
|
-
## Limitations
|
|
129
|
-
|
|
130
|
-
- Rendering is client-only. Nothing is rendered at build time, so mindmaps are
|
|
131
|
-
not visible without JavaScript (the source remains in the fallback `details`)
|
|
132
|
-
- The client fetches `markmap-lib`, `markmap-view`, and their CDN sub-modules on
|
|
133
|
-
first use, so the first render waits on the network
|
|
134
|
-
- Not every Markdown extension is supported by the standard notation; the
|
|
135
|
-
parser recognises ATX (`#`) headings and ignores fenced code blocks
|
|
136
|
-
- `markmap-lib` and `markmap-view` are MIT licensed
|
|
137
|
-
|
|
138
|
-
## See also
|
|
139
|
-
|
|
140
|
-
- [Plugin system](../../../docs/en/plugin-
|
|
1
|
+
# @riebeckite/plugin-markmap
|
|
2
|
+
|
|
3
|
+
Renders ` ```markmap ` code blocks as Markdown-heading mindmaps. The mindmap is
|
|
4
|
+
drawn in the browser by `markmap-lib` + `markmap-view`, which are imported from
|
|
5
|
+
the CDN only when a figure is present.
|
|
6
|
+
|
|
7
|
+
[Japanese](./README_ja.md)
|
|
8
|
+
|
|
9
|
+
## Configure
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { defineConfig } from "@riebeckite/core";
|
|
13
|
+
import { markmap } from "@riebeckite/plugin-markmap";
|
|
14
|
+
|
|
15
|
+
export default defineConfig({
|
|
16
|
+
// ...
|
|
17
|
+
plugins: [
|
|
18
|
+
markmap({
|
|
19
|
+
caption: true,
|
|
20
|
+
height: 320,
|
|
21
|
+
fallback: true,
|
|
22
|
+
}),
|
|
23
|
+
],
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The plugin runs with `order: -10`.
|
|
28
|
+
|
|
29
|
+
## Syntax
|
|
30
|
+
|
|
31
|
+
The block body is ordinary Markdown: headings become nodes and their nesting
|
|
32
|
+
becomes the tree. Content other than headings is ignored.
|
|
33
|
+
|
|
34
|
+
````markdown
|
|
35
|
+
```markmap
|
|
36
|
+
# Project
|
|
37
|
+
|
|
38
|
+
## Design
|
|
39
|
+
|
|
40
|
+
### Notation
|
|
41
|
+
### Rendering
|
|
42
|
+
|
|
43
|
+
## Delivery
|
|
44
|
+
```
|
|
45
|
+
````
|
|
46
|
+
|
|
47
|
+
The caption comes from the code-block `title`.
|
|
48
|
+
|
|
49
|
+
## How it renders
|
|
50
|
+
|
|
51
|
+
A ` ```markmap ` block becomes a `figure.rb-markmap`:
|
|
52
|
+
|
|
53
|
+
- `figure.rb-markmap`: carries `data-markmap="pending"`,
|
|
54
|
+
`data-markmap-source` (the raw Markdown) and `data-markmap-height`
|
|
55
|
+
- `div.rb-markmap__canvas`: the element the SVG is rendered into
|
|
56
|
+
(`role="img"`)
|
|
57
|
+
- `figcaption.rb-markmap__caption`: the caption (enabled by default)
|
|
58
|
+
- `details.rb-markmap__fallback`: the raw Markdown, folded away
|
|
59
|
+
|
|
60
|
+
`initMarkmap` finds every `[data-markmap="pending"]`, loads the runtime, runs
|
|
61
|
+
`markmap-lib`'s `Transformer` over `data-markmap-source`, and renders the
|
|
62
|
+
resulting tree with `markmap-view`'s `Markmap.create`. On success the figure
|
|
63
|
+
becomes `data-markmap="rendered"`.
|
|
64
|
+
|
|
65
|
+
If loading the runtime, transforming the source, or rendering fails, the
|
|
66
|
+
initializer does not throw: it opens that figure's `details` and marks it
|
|
67
|
+
`data-markmap="error"`.
|
|
68
|
+
|
|
69
|
+
A block whose body has no Markdown heading is left as a normal code block, and a
|
|
70
|
+
diagnostic with `source: "@riebeckite/plugin-markmap"` is emitted.
|
|
71
|
+
|
|
72
|
+
## Options
|
|
73
|
+
|
|
74
|
+
| Option | Default | Description |
|
|
75
|
+
| --- | --- | --- |
|
|
76
|
+
| `caption` | `true` | Show the code-block `title` as a caption |
|
|
77
|
+
| `height` | `320` | Canvas height in pixels |
|
|
78
|
+
| `className` | `"rb-markmap"` | Base class applied to the figure |
|
|
79
|
+
| `language` | `"markmap"` | Fenced-code language to recognize |
|
|
80
|
+
| `fallback` | `true` | Render the `<details>` block with the raw Markdown |
|
|
81
|
+
| `colorFreezeLevel` | — | Depth at which node colours are frozen |
|
|
82
|
+
|
|
83
|
+
## Client rendering
|
|
84
|
+
|
|
85
|
+
The client initializer is static and receives no plugin options. `height` and
|
|
86
|
+
`colorFreezeLevel` are embedded into the figure's `data-markmap-*` attributes,
|
|
87
|
+
and `initMarkmap` reads them from there.
|
|
88
|
+
|
|
89
|
+
`markmap-lib` and `markmap-view` are fetched from jsDelivr with a computed
|
|
90
|
+
import specifier, so they are never bundled into the host's client bundle.
|
|
91
|
+
`markmap-view` pulls `d3` in as its own dependency. Because the libraries are
|
|
92
|
+
loaded lazily, the page still renders (with the fallback `details`) when
|
|
93
|
+
JavaScript is disabled.
|
|
94
|
+
|
|
95
|
+
## The input-notation seam
|
|
96
|
+
|
|
97
|
+
The code-block body is turned into a mindmap tree by a single, pure function in
|
|
98
|
+
`src/parse.ts`:
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
parseMarkmapSource(source: string): MarkmapNode | null
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`MarkmapNode` is the notation-neutral tree (`{ content, children, payload? }`).
|
|
105
|
+
Only the standard Markdown-heading notation is implemented today. A future
|
|
106
|
+
alternative notation (for example an "ExcaliMindMap"-style outline) is added by
|
|
107
|
+
implementing another parser that produces the same `MarkmapNode` shape; the
|
|
108
|
+
figure emission and the render path do not parse the notation themselves, so
|
|
109
|
+
they stay unchanged. `parseMarkmapSource` is exported from the package entry
|
|
110
|
+
point for that purpose.
|
|
111
|
+
|
|
112
|
+
## Output hooks
|
|
113
|
+
|
|
114
|
+
- `figure[data-markmap]`: state (`pending` / `rendered` / `error`)
|
|
115
|
+
- `figure[data-markmap-source]`: the raw Markdown
|
|
116
|
+
- `figure[data-markmap-height]`, `figure[data-markmap-color-freeze-level]`
|
|
117
|
+
- `[data-markmap-canvas]`: the render target
|
|
118
|
+
- `details.rb-markmap__fallback`: the raw Markdown
|
|
119
|
+
|
|
120
|
+
## Main exports
|
|
121
|
+
|
|
122
|
+
- `markmap(options?)`: create the plugin (`markmapPlugin` is an alias)
|
|
123
|
+
- `initMarkmap`: initialize client-side rendering
|
|
124
|
+
- `parseMarkmapSource`: parse the standard notation into a tree
|
|
125
|
+
- `describeMarkmapTree`: derive an accessible label from a tree
|
|
126
|
+
- Types: `MarkmapOptions`, `MarkmapNode`, `MarkmapClientOptions`
|
|
127
|
+
|
|
128
|
+
## Limitations
|
|
129
|
+
|
|
130
|
+
- Rendering is client-only. Nothing is rendered at build time, so mindmaps are
|
|
131
|
+
not visible without JavaScript (the source remains in the fallback `details`)
|
|
132
|
+
- The client fetches `markmap-lib`, `markmap-view`, and their CDN sub-modules on
|
|
133
|
+
first use, so the first render waits on the network
|
|
134
|
+
- Not every Markdown extension is supported by the standard notation; the
|
|
135
|
+
parser recognises ATX (`#`) headings and ignores fenced code blocks
|
|
136
|
+
- `markmap-lib` and `markmap-view` are MIT licensed
|
|
137
|
+
|
|
138
|
+
## See also
|
|
139
|
+
|
|
140
|
+
- [Plugin system](../../../docs/en/reference/plugin-api.md)
|
package/README_ja.md
CHANGED
|
@@ -1,113 +1,113 @@
|
|
|
1
|
-
# @riebeckite/plugin-markmap
|
|
2
|
-
|
|
3
|
-
` ```markmap ` コードブロックを、Markdown の見出しから組み立てるマインドマップとして表示するプラグインです。マインドマップはブラウザ側で `markmap-lib` と `markmap-view` により描画し、これらのライブラリは図があるときだけ CDN から読み込みます。
|
|
4
|
-
|
|
5
|
-
[English](./README.md)
|
|
6
|
-
|
|
7
|
-
## 設定する
|
|
8
|
-
|
|
9
|
-
```ts
|
|
10
|
-
import { defineConfig } from "@riebeckite/core";
|
|
11
|
-
import { markmap } from "@riebeckite/plugin-markmap";
|
|
12
|
-
|
|
13
|
-
export default defineConfig({
|
|
14
|
-
// ...
|
|
15
|
-
plugins: [
|
|
16
|
-
markmap({
|
|
17
|
-
caption: true,
|
|
18
|
-
height: 320,
|
|
19
|
-
fallback: true,
|
|
20
|
-
}),
|
|
21
|
-
],
|
|
22
|
-
});
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
このプラグインは `order: -10` で実行されます。
|
|
26
|
-
|
|
27
|
-
## 記法
|
|
28
|
-
|
|
29
|
-
コードブロックの本文は通常の Markdown です。見出しがノードになり、見出しの階層が木構造になります。見出し以外の内容は無視します。
|
|
30
|
-
|
|
31
|
-
````markdown
|
|
32
|
-
```markmap
|
|
33
|
-
# プロジェクト
|
|
34
|
-
|
|
35
|
-
## 設計
|
|
36
|
-
|
|
37
|
-
### 記法
|
|
38
|
-
### 描画
|
|
39
|
-
|
|
40
|
-
## リリース
|
|
41
|
-
```
|
|
42
|
-
````
|
|
43
|
-
|
|
44
|
-
キャプションにはコードブロックの `title` を使います。
|
|
45
|
-
|
|
46
|
-
## どのように描画されるか
|
|
47
|
-
|
|
48
|
-
` ```markmap ` のコードブロックは `figure.rb-markmap` に置き換わります。
|
|
49
|
-
|
|
50
|
-
- `figure.rb-markmap`: `data-markmap="pending"`、`data-markmap-source`（元の Markdown）、`data-markmap-height` を持ちます
|
|
51
|
-
- `div.rb-markmap__canvas`: SVG を描画する領域（`role="img"`）
|
|
52
|
-
- `figcaption.rb-markmap__caption`: キャプション（既定で有効）
|
|
53
|
-
- `details.rb-markmap__fallback`: 元の Markdown を折りたたんで表示
|
|
54
|
-
|
|
55
|
-
`initMarkmap` は `[data-markmap="pending"]` を探し、ランタイムを読み込んでから `markmap-lib` の `Transformer` を `data-markmap-source` に適用し、得られた木を `markmap-view` の `Markmap.create` で描画します。描画に成功すると `data-markmap="rendered"` になります。
|
|
56
|
-
|
|
57
|
-
ランタイムの読み込み、ソースの変換、描画のいずれかが失敗した場合は例外を投げず、その figure の `details` を開いて元の Markdown を見せます（`data-markmap="error"`）。
|
|
58
|
-
|
|
59
|
-
Markdown の見出しを 1 つも含まないコードブロックは置き換えず、通常のコードブロックのまま残し、`source: "@riebeckite/plugin-markmap"` を持つ診断を出します。
|
|
60
|
-
|
|
61
|
-
## オプション
|
|
62
|
-
|
|
63
|
-
| 項目 | 既定値 | 説明 |
|
|
64
|
-
| --- | --- | --- |
|
|
65
|
-
| `caption` | `true` | コードブロックの `title` をキャプションとして表示する |
|
|
66
|
-
| `height` | `320` | キャンバスの高さ（ピクセル） |
|
|
67
|
-
| `className` | `"rb-markmap"` | figure に付ける基準クラス |
|
|
68
|
-
| `language` | `"markmap"` | 対象にするコードブロックの言語 |
|
|
69
|
-
| `fallback` | `true` | 元の Markdown を表示する `details` を描画する |
|
|
70
|
-
| `colorFreezeLevel` | — | ノードの色を固定する深さ |
|
|
71
|
-
|
|
72
|
-
## クライアント側の描画
|
|
73
|
-
|
|
74
|
-
クライアントの初期化コードは静的なので、プラグインのオプションは受け取りません。`height` と `colorFreezeLevel` は figure の `data-markmap-*` 属性に埋め込まれ、`initMarkmap` がそこから読み取ります。
|
|
75
|
-
|
|
76
|
-
`markmap-lib` と `markmap-view` は計算された import 指定子で jsDelivr から取得するため、ホストのクライアントバンドルには含まれません。`markmap-view` は依存として `d3` を読み込みます。ライブラリを遅延して読み込むので、JavaScript を無効にしていてもページは表示され、元の Markdown はフォールバックの `details` から読めます。
|
|
77
|
-
|
|
78
|
-
## 入力記法の継ぎ目（notation seam）
|
|
79
|
-
|
|
80
|
-
コードブロックの本文は、`src/parse.ts` にある単一の純粋関数でマインドマップの木に変換します。
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
parseMarkmapSource(source: string): MarkmapNode | null
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
`MarkmapNode` は記法に依存しない木（`{ content, children, payload? }`）です。現在は標準の Markdown 見出し記法だけを実装しています。将来別の入力記法（たとえば "ExcaliMindMap" 風のアウトライン）を追加するときは、同じ `MarkmapNode` を返すパーサーを実装するだけです。figure の生成と描画の経路は記法を解析しないため、変更する必要はありません。`parseMarkmapSource` はそのためにパッケージのエントリーポイントから公開しています。
|
|
87
|
-
|
|
88
|
-
## 出力のフック
|
|
89
|
-
|
|
90
|
-
- `figure[data-markmap]`: 状態（`pending` / `rendered` / `error`）
|
|
91
|
-
- `figure[data-markmap-source]`: 元の Markdown
|
|
92
|
-
- `figure[data-markmap-height]`、`figure[data-markmap-color-freeze-level]`
|
|
93
|
-
- `[data-markmap-canvas]`: 描画先の要素
|
|
94
|
-
- `details.rb-markmap__fallback`: 元の Markdown
|
|
95
|
-
|
|
96
|
-
## 主なエクスポート
|
|
97
|
-
|
|
98
|
-
- `markmap(options?)`: プラグインを作成する（`markmapPlugin` は別名）
|
|
99
|
-
- `initMarkmap`: クライアント側の描画を初期化する
|
|
100
|
-
- `parseMarkmapSource`: 標準記法を木に変換する
|
|
101
|
-
- `describeMarkmapTree`: 木からアクセシブルなラベルを作る
|
|
102
|
-
- 型: `MarkmapOptions`、`MarkmapNode`、`MarkmapClientOptions`
|
|
103
|
-
|
|
104
|
-
## 制限
|
|
105
|
-
|
|
106
|
-
- 描画はクライアント側のみです。ビルド時に何も生成しないため、JavaScript が無効な環境ではマインドマップは表示されません（元の Markdown はフォールバックの `details` に残ります）
|
|
107
|
-
- クライアントは初回描画時に `markmap-lib`、`markmap-view` とその CDN サブモジュールを取得するため、最初の描画はネットワーク待ちになります
|
|
108
|
-
- 標準記法が対応する Markdown 拡張は限られます。パーサーは ATX（`#`）見出しを認識し、コードフェンス内は無視します
|
|
109
|
-
- `markmap-lib` と `markmap-view` は MIT ライセンスです
|
|
110
|
-
|
|
111
|
-
## 関連資料
|
|
112
|
-
|
|
113
|
-
- [プラグインシステム](../../../docs/ja/plugin-
|
|
1
|
+
# @riebeckite/plugin-markmap
|
|
2
|
+
|
|
3
|
+
` ```markmap ` コードブロックを、Markdown の見出しから組み立てるマインドマップとして表示するプラグインです。マインドマップはブラウザ側で `markmap-lib` と `markmap-view` により描画し、これらのライブラリは図があるときだけ CDN から読み込みます。
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
## 設定する
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { defineConfig } from "@riebeckite/core";
|
|
11
|
+
import { markmap } from "@riebeckite/plugin-markmap";
|
|
12
|
+
|
|
13
|
+
export default defineConfig({
|
|
14
|
+
// ...
|
|
15
|
+
plugins: [
|
|
16
|
+
markmap({
|
|
17
|
+
caption: true,
|
|
18
|
+
height: 320,
|
|
19
|
+
fallback: true,
|
|
20
|
+
}),
|
|
21
|
+
],
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
このプラグインは `order: -10` で実行されます。
|
|
26
|
+
|
|
27
|
+
## 記法
|
|
28
|
+
|
|
29
|
+
コードブロックの本文は通常の Markdown です。見出しがノードになり、見出しの階層が木構造になります。見出し以外の内容は無視します。
|
|
30
|
+
|
|
31
|
+
````markdown
|
|
32
|
+
```markmap
|
|
33
|
+
# プロジェクト
|
|
34
|
+
|
|
35
|
+
## 設計
|
|
36
|
+
|
|
37
|
+
### 記法
|
|
38
|
+
### 描画
|
|
39
|
+
|
|
40
|
+
## リリース
|
|
41
|
+
```
|
|
42
|
+
````
|
|
43
|
+
|
|
44
|
+
キャプションにはコードブロックの `title` を使います。
|
|
45
|
+
|
|
46
|
+
## どのように描画されるか
|
|
47
|
+
|
|
48
|
+
` ```markmap ` のコードブロックは `figure.rb-markmap` に置き換わります。
|
|
49
|
+
|
|
50
|
+
- `figure.rb-markmap`: `data-markmap="pending"`、`data-markmap-source`（元の Markdown）、`data-markmap-height` を持ちます
|
|
51
|
+
- `div.rb-markmap__canvas`: SVG を描画する領域（`role="img"`）
|
|
52
|
+
- `figcaption.rb-markmap__caption`: キャプション（既定で有効）
|
|
53
|
+
- `details.rb-markmap__fallback`: 元の Markdown を折りたたんで表示
|
|
54
|
+
|
|
55
|
+
`initMarkmap` は `[data-markmap="pending"]` を探し、ランタイムを読み込んでから `markmap-lib` の `Transformer` を `data-markmap-source` に適用し、得られた木を `markmap-view` の `Markmap.create` で描画します。描画に成功すると `data-markmap="rendered"` になります。
|
|
56
|
+
|
|
57
|
+
ランタイムの読み込み、ソースの変換、描画のいずれかが失敗した場合は例外を投げず、その figure の `details` を開いて元の Markdown を見せます（`data-markmap="error"`）。
|
|
58
|
+
|
|
59
|
+
Markdown の見出しを 1 つも含まないコードブロックは置き換えず、通常のコードブロックのまま残し、`source: "@riebeckite/plugin-markmap"` を持つ診断を出します。
|
|
60
|
+
|
|
61
|
+
## オプション
|
|
62
|
+
|
|
63
|
+
| 項目 | 既定値 | 説明 |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| `caption` | `true` | コードブロックの `title` をキャプションとして表示する |
|
|
66
|
+
| `height` | `320` | キャンバスの高さ（ピクセル） |
|
|
67
|
+
| `className` | `"rb-markmap"` | figure に付ける基準クラス |
|
|
68
|
+
| `language` | `"markmap"` | 対象にするコードブロックの言語 |
|
|
69
|
+
| `fallback` | `true` | 元の Markdown を表示する `details` を描画する |
|
|
70
|
+
| `colorFreezeLevel` | — | ノードの色を固定する深さ |
|
|
71
|
+
|
|
72
|
+
## クライアント側の描画
|
|
73
|
+
|
|
74
|
+
クライアントの初期化コードは静的なので、プラグインのオプションは受け取りません。`height` と `colorFreezeLevel` は figure の `data-markmap-*` 属性に埋め込まれ、`initMarkmap` がそこから読み取ります。
|
|
75
|
+
|
|
76
|
+
`markmap-lib` と `markmap-view` は計算された import 指定子で jsDelivr から取得するため、ホストのクライアントバンドルには含まれません。`markmap-view` は依存として `d3` を読み込みます。ライブラリを遅延して読み込むので、JavaScript を無効にしていてもページは表示され、元の Markdown はフォールバックの `details` から読めます。
|
|
77
|
+
|
|
78
|
+
## 入力記法の継ぎ目（notation seam）
|
|
79
|
+
|
|
80
|
+
コードブロックの本文は、`src/parse.ts` にある単一の純粋関数でマインドマップの木に変換します。
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
parseMarkmapSource(source: string): MarkmapNode | null
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`MarkmapNode` は記法に依存しない木（`{ content, children, payload? }`）です。現在は標準の Markdown 見出し記法だけを実装しています。将来別の入力記法（たとえば "ExcaliMindMap" 風のアウトライン）を追加するときは、同じ `MarkmapNode` を返すパーサーを実装するだけです。figure の生成と描画の経路は記法を解析しないため、変更する必要はありません。`parseMarkmapSource` はそのためにパッケージのエントリーポイントから公開しています。
|
|
87
|
+
|
|
88
|
+
## 出力のフック
|
|
89
|
+
|
|
90
|
+
- `figure[data-markmap]`: 状態（`pending` / `rendered` / `error`）
|
|
91
|
+
- `figure[data-markmap-source]`: 元の Markdown
|
|
92
|
+
- `figure[data-markmap-height]`、`figure[data-markmap-color-freeze-level]`
|
|
93
|
+
- `[data-markmap-canvas]`: 描画先の要素
|
|
94
|
+
- `details.rb-markmap__fallback`: 元の Markdown
|
|
95
|
+
|
|
96
|
+
## 主なエクスポート
|
|
97
|
+
|
|
98
|
+
- `markmap(options?)`: プラグインを作成する（`markmapPlugin` は別名）
|
|
99
|
+
- `initMarkmap`: クライアント側の描画を初期化する
|
|
100
|
+
- `parseMarkmapSource`: 標準記法を木に変換する
|
|
101
|
+
- `describeMarkmapTree`: 木からアクセシブルなラベルを作る
|
|
102
|
+
- 型: `MarkmapOptions`、`MarkmapNode`、`MarkmapClientOptions`
|
|
103
|
+
|
|
104
|
+
## 制限
|
|
105
|
+
|
|
106
|
+
- 描画はクライアント側のみです。ビルド時に何も生成しないため、JavaScript が無効な環境ではマインドマップは表示されません（元の Markdown はフォールバックの `details` に残ります）
|
|
107
|
+
- クライアントは初回描画時に `markmap-lib`、`markmap-view` とその CDN サブモジュールを取得するため、最初の描画はネットワーク待ちになります
|
|
108
|
+
- 標準記法が対応する Markdown 拡張は限られます。パーサーは ATX（`#`）見出しを認識し、コードフェンス内は無視します
|
|
109
|
+
- `markmap-lib` と `markmap-view` は MIT ライセンスです
|
|
110
|
+
|
|
111
|
+
## 関連資料
|
|
112
|
+
|
|
113
|
+
- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@riebeckite/plugin-markmap",
|
|
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",
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"dependencies": {
|
|
24
24
|
"markmap-lib": "^0.18.12",
|
|
25
25
|
"markmap-view": "^0.18.12",
|
|
26
|
-
"@riebeckite/core": "0.0.
|
|
26
|
+
"@riebeckite/core": "0.0.13"
|
|
27
27
|
},
|
|
28
28
|
"publishConfig": {
|
|
29
29
|
"access": "public"
|