@riebeckite/plugin-code-annotations 0.0.11 → 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 +137 -137
  2. package/README_ja.md +136 -136
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,137 +1,137 @@
1
- # @riebeckite/plugin-code-annotations
2
-
3
- VitePress/Docusaurus-style code block annotations: line highlighting, focus,
4
- and diff markers that work on plain `<pre><code>` blocks and on the line
5
- wrappers produced by `@riebeckite/plugin-code-enhance`.
6
-
7
- [日本語](./README_ja.md)
8
-
9
- ## Installation
10
-
11
- ```ts
12
- import { defineConfig } from "@riebeckite/core";
13
- import { codeAnnotations } from "@riebeckite/plugin-code-annotations";
14
-
15
- export default defineConfig({
16
- // ...
17
- plugins: [codeAnnotations()],
18
- });
19
- ```
20
-
21
- The plugin registers its own `style.css`. It adds no client entry and no
22
- runtime JavaScript.
23
-
24
- ## Syntax
25
-
26
- ### Line highlighting (fence meta)
27
-
28
- Add a brace range after the language, exactly like Docusaurus and VitePress.
29
-
30
- ````md
31
- ```js {2,4-5}
32
- const a = 1;
33
- const b = 2;
34
- const c = 3;
35
- const d = 4;
36
- const e = 5;
37
- ```
38
- ````
39
-
40
- Lines `2`, `4`, and `5` receive `rb-code__line--highlighted`.
41
-
42
- ### Focus
43
-
44
- Use the `focus` meta group, or an inline `[!code focus]` marker. An optional
45
- count focuses the current line and the following lines.
46
-
47
- ````md
48
- ```js focus:{2}
49
- const a = 1;
50
- const b = 2;
51
- ```
52
- ````
53
-
54
- ````md
55
- ```js
56
- const a = 1; // [!code focus]
57
- const b = 2;
58
- ```
59
- ````
60
-
61
- `.rb-code__line--focused` is applied. `[!code focus:3]` focuses three lines
62
- starting at the marker.
63
-
64
- ### Diff
65
-
66
- ````md
67
- ```js
68
- const kept = true;
69
- const added = true; // [!code ++]
70
- const removed = false; // [!code --]
71
- ```
72
- ````
73
-
74
- The marker comment is removed from the rendered text, and the line receives
75
- `rb-code__line--added` or `rb-code__line--removed`.
76
-
77
- ### Explicit highlight marker
78
-
79
- ````md
80
- ```js
81
- const value = 1; // [!code highlight]
82
- ```
83
- ````
84
-
85
- Marker comments are recognized with the `//`, `#`, `--`, and `<!-- -->`
86
- comment prefixes, so the same syntax works for JavaScript, shell, SQL, Lua,
87
- HTML, and other languages.
88
-
89
- ## Options
90
-
91
- | Option | Type | Default | Description |
92
- | ------ | ---- | ------- | ----------- |
93
- | `className` | `string` | `"rb-code"` | Class on the block root (`<pre>` or `rehype-pretty-code` `<figure>`) |
94
- | `lineClassName` | `string` | `"rb-code__line"` | Class on generated line wrappers |
95
- | `highlightClassName` | `string` | `"rb-code__line--highlighted"` | Class for highlighted lines |
96
- | `addedClassName` | `string` | `"rb-code__line--added"` | Class for `[!code ++]` lines |
97
- | `removedClassName` | `string` | `"rb-code__line--removed"` | Class for `[!code --]` lines |
98
- | `focusClassName` | `string` | `"rb-code__line--focused"` | Class for focused lines |
99
- | `language` | `string` | unset | Only annotate blocks of this language |
100
-
101
- ```ts
102
- codeAnnotations({ highlightClassName: "is-highlighted" });
103
- ```
104
-
105
- ## Using with code-enhance
106
-
107
- `@riebeckite/plugin-code-annotations` does not import or depend on
108
- `@riebeckite/plugin-code-enhance`. It detects both raw `<pre><code>` text and
109
- the `.line` wrappers emitted by `rehype-pretty-code`:
110
-
111
- - If line wrappers already exist, their classes are extended in place and the
112
- existing `data-line` attribute is kept.
113
- - Otherwise the plugin wraps the raw code text into
114
- `<span class="rb-code__line" data-line="N">` elements.
115
-
116
- Because `rehype-pretty-code` substitutes the `<code>` element, the plan is also
117
- mirrored into the preserved fence meta, so annotations still apply after
118
- code-enhance runs. Place `codeAnnotations()` after `codeEnhance()` in the
119
- plugins array; the plugin uses `order: 10` to run after code-enhance's
120
- highlighting regardless.
121
-
122
- ## Exports
123
-
124
- - `codeAnnotations(options?)` / `codeAnnotationsPlugin(options?)` — plugin factory
125
- - `remarkCodeAnnotations(options?)` — remark transform
126
- - `rehypeCodeAnnotations(options?)` — rehype transform
127
- - `parseCodeAnnotations(meta)` — parse fence meta into a plan
128
- - `parseLineRanges(spec)` — parse `1,3-5` into line numbers
129
- - `collectCodeAnnotations(meta, code)` — parse meta plus inline markers
130
- - `resolveCodeAnnotationsOptions(options?)` — fill in defaults
131
- - Types: `CodeAnnotationsOptions`, `ResolvedCodeAnnotationsOptions`,
132
- `CodeAnnotationPlan`, `CodeAnnotationKind`
133
-
134
- ## See also
135
-
136
- - [Plugin guide](../../../docs/en/plugin-system.md)
137
- - [`@riebeckite/plugin-code-enhance`](../code-enhance/README.md)
1
+ # @riebeckite/plugin-code-annotations
2
+
3
+ VitePress/Docusaurus-style code block annotations: line highlighting, focus,
4
+ and diff markers that work on plain `<pre><code>` blocks and on the line
5
+ wrappers produced by `@riebeckite/plugin-code-enhance`.
6
+
7
+ [日本語](./README_ja.md)
8
+
9
+ ## Installation
10
+
11
+ ```ts
12
+ import { defineConfig } from "@riebeckite/core";
13
+ import { codeAnnotations } from "@riebeckite/plugin-code-annotations";
14
+
15
+ export default defineConfig({
16
+ // ...
17
+ plugins: [codeAnnotations()],
18
+ });
19
+ ```
20
+
21
+ The plugin registers its own `style.css`. It adds no client entry and no
22
+ runtime JavaScript.
23
+
24
+ ## Syntax
25
+
26
+ ### Line highlighting (fence meta)
27
+
28
+ Add a brace range after the language, exactly like Docusaurus and VitePress.
29
+
30
+ ````md
31
+ ```js {2,4-5}
32
+ const a = 1;
33
+ const b = 2;
34
+ const c = 3;
35
+ const d = 4;
36
+ const e = 5;
37
+ ```
38
+ ````
39
+
40
+ Lines `2`, `4`, and `5` receive `rb-code__line--highlighted`.
41
+
42
+ ### Focus
43
+
44
+ Use the `focus` meta group, or an inline `[!code focus]` marker. An optional
45
+ count focuses the current line and the following lines.
46
+
47
+ ````md
48
+ ```js focus:{2}
49
+ const a = 1;
50
+ const b = 2;
51
+ ```
52
+ ````
53
+
54
+ ````md
55
+ ```js
56
+ const a = 1; // [!code focus]
57
+ const b = 2;
58
+ ```
59
+ ````
60
+
61
+ `.rb-code__line--focused` is applied. `[!code focus:3]` focuses three lines
62
+ starting at the marker.
63
+
64
+ ### Diff
65
+
66
+ ````md
67
+ ```js
68
+ const kept = true;
69
+ const added = true; // [!code ++]
70
+ const removed = false; // [!code --]
71
+ ```
72
+ ````
73
+
74
+ The marker comment is removed from the rendered text, and the line receives
75
+ `rb-code__line--added` or `rb-code__line--removed`.
76
+
77
+ ### Explicit highlight marker
78
+
79
+ ````md
80
+ ```js
81
+ const value = 1; // [!code highlight]
82
+ ```
83
+ ````
84
+
85
+ Marker comments are recognized with the `//`, `#`, `--`, and `<!-- -->`
86
+ comment prefixes, so the same syntax works for JavaScript, shell, SQL, Lua,
87
+ HTML, and other languages.
88
+
89
+ ## Options
90
+
91
+ | Option | Type | Default | Description |
92
+ | ------ | ---- | ------- | ----------- |
93
+ | `className` | `string` | `"rb-code"` | Class on the block root (`<pre>` or `rehype-pretty-code` `<figure>`) |
94
+ | `lineClassName` | `string` | `"rb-code__line"` | Class on generated line wrappers |
95
+ | `highlightClassName` | `string` | `"rb-code__line--highlighted"` | Class for highlighted lines |
96
+ | `addedClassName` | `string` | `"rb-code__line--added"` | Class for `[!code ++]` lines |
97
+ | `removedClassName` | `string` | `"rb-code__line--removed"` | Class for `[!code --]` lines |
98
+ | `focusClassName` | `string` | `"rb-code__line--focused"` | Class for focused lines |
99
+ | `language` | `string` | unset | Only annotate blocks of this language |
100
+
101
+ ```ts
102
+ codeAnnotations({ highlightClassName: "is-highlighted" });
103
+ ```
104
+
105
+ ## Using with code-enhance
106
+
107
+ `@riebeckite/plugin-code-annotations` does not import or depend on
108
+ `@riebeckite/plugin-code-enhance`. It detects both raw `<pre><code>` text and
109
+ the `.line` wrappers emitted by `rehype-pretty-code`:
110
+
111
+ - If line wrappers already exist, their classes are extended in place and the
112
+ existing `data-line` attribute is kept.
113
+ - Otherwise the plugin wraps the raw code text into
114
+ `<span class="rb-code__line" data-line="N">` elements.
115
+
116
+ Because `rehype-pretty-code` substitutes the `<code>` element, the plan is also
117
+ mirrored into the preserved fence meta, so annotations still apply after
118
+ code-enhance runs. Place `codeAnnotations()` after `codeEnhance()` in the
119
+ plugins array; the plugin uses `order: 10` to run after code-enhance's
120
+ highlighting regardless.
121
+
122
+ ## Exports
123
+
124
+ - `codeAnnotations(options?)` / `codeAnnotationsPlugin(options?)` — plugin factory
125
+ - `remarkCodeAnnotations(options?)` — remark transform
126
+ - `rehypeCodeAnnotations(options?)` — rehype transform
127
+ - `parseCodeAnnotations(meta)` — parse fence meta into a plan
128
+ - `parseLineRanges(spec)` — parse `1,3-5` into line numbers
129
+ - `collectCodeAnnotations(meta, code)` — parse meta plus inline markers
130
+ - `resolveCodeAnnotationsOptions(options?)` — fill in defaults
131
+ - Types: `CodeAnnotationsOptions`, `ResolvedCodeAnnotationsOptions`,
132
+ `CodeAnnotationPlan`, `CodeAnnotationKind`
133
+
134
+ ## See also
135
+
136
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
137
+ - [`@riebeckite/plugin-code-enhance`](../code-enhance/README.md)
package/README_ja.md CHANGED
@@ -1,136 +1,136 @@
1
- # @riebeckite/plugin-code-annotations
2
-
3
- VitePress / Docusaurus 風のコードブロック装飾を加えるプラグインです。フェンスの
4
- メタ情報による行の強調と、`[!code ...]` のインラインマーカーによるフォーカス・
5
- 差分表示に対応します。素の `<pre><code>` と
6
- `@riebeckite/plugin-code-enhance` の行ラッパーの両方で動作します。
7
-
8
- [English](./README.md)
9
-
10
- ## 設定
11
-
12
- ```ts
13
- import { defineConfig } from "@riebeckite/core";
14
- import { codeAnnotations } from "@riebeckite/plugin-code-annotations";
15
-
16
- export default defineConfig({
17
- // ...
18
- plugins: [codeAnnotations()],
19
- });
20
- ```
21
-
22
- プラグインは `style.css` のみを登録します。クライアントエントリーはなく、
23
- 実行時 JavaScript は追加しません。
24
-
25
- ## 書き方
26
-
27
- ### フェンスメタによる行の強調
28
-
29
- 言語の後ろに波括弧で行範囲を書きます。Docusaurus や VitePress と同じ記法です。
30
-
31
- ````md
32
- ```js {2,4-5}
33
- const a = 1;
34
- const b = 2;
35
- const c = 3;
36
- const d = 4;
37
- const e = 5;
38
- ```
39
- ````
40
-
41
- 2、4、5 行目に `rb-code__line--highlighted` が付きます。
42
-
43
- ### フォーカス
44
-
45
- `focus` メタ、またはインラインの `[!code focus]` を使います。行数を指定すると
46
- その行から続く行までをまとめてフォーカスします。
47
-
48
- ````md
49
- ```js focus:{2}
50
- const a = 1;
51
- const b = 2;
52
- ```
53
- ````
54
-
55
- ````md
56
- ```js
57
- const a = 1; // [!code focus]
58
- const b = 2;
59
- ```
60
- ````
61
-
62
- `rb-code__line--focused` が付きます。`[!code focus:3]` なら 3 行分です。
63
-
64
- ### 差分
65
-
66
- ````md
67
- ```js
68
- const kept = true;
69
- const added = true; // [!code ++]
70
- const removed = false; // [!code --]
71
- ```
72
- ````
73
-
74
- マーカーのコメントは表示テキストから取り除かれ、行には
75
- `rb-code__line--added` または `rb-code__line--removed` が付きます。
76
-
77
- ### 明示的な強調マーカー
78
-
79
- ````md
80
- ```js
81
- const value = 1; // [!code highlight]
82
- ```
83
- ````
84
-
85
- マーカーは `//`、`#`、`--`、`<!-- -->` のコメント記法に対応します。JavaScript、
86
- シェル、SQL、Lua、HTML などで同じ書き方が使えます。
87
-
88
- ## オプション
89
-
90
- | オプション | 既定値 | 内容 |
91
- | --- | --- | --- |
92
- | `className` | `"rb-code"` | ブロック直下（`<pre>` または `rehype-pretty-code` の `<figure>`）に付くクラス |
93
- | `lineClassName` | `"rb-code__line"` | 生成する行ラッパーのクラス |
94
- | `highlightClassName` | `"rb-code__line--highlighted"` | 強調行のクラス |
95
- | `addedClassName` | `"rb-code__line--added"` | `[!code ++]` 行のクラス |
96
- | `removedClassName` | `"rb-code__line--removed"` | `[!code --]` 行のクラス |
97
- | `focusClassName` | `"rb-code__line--focused"` | フォーカス行のクラス |
98
- | `language` | 未設定 | 指定した言語のブロックだけを対象にする |
99
-
100
- ```ts
101
- codeAnnotations({ highlightClassName: "is-highlighted" });
102
- ```
103
-
104
- ## code-enhance との併用
105
-
106
- `@riebeckite/plugin-code-annotations` は
107
- `@riebeckite/plugin-code-enhance` を import せず、依存もしません。素の
108
- `<pre><code>` のテキストと、`rehype-pretty-code` が出力する `.line` ラッパーの
109
- 両方を検出します。
110
-
111
- - 行ラッパーがすでにある場合は、既存のクラスに追記し、既存の `data-line` を
112
- そのまま使います。
113
- - ない場合は、コード本文を
114
- `<span class="rb-code__line" data-line="N">` に分割します。
115
-
116
- `rehype-pretty-code` は `<code>` 要素を差し替えるため、注釈プランは保持される
117
- フェンスメタにも複製します。これにより code-enhance の後でも注釈が適用されます。
118
- プラグイン配列では `codeEnhance()` の後に `codeAnnotations()` を置いてください。
119
- `order: 10` により、順序に関わらず強調処理の後に実行されます。
120
-
121
- ## 公開 API
122
-
123
- - `codeAnnotations(options?)` / `codeAnnotationsPlugin(options?)` — プラグインファクトリ
124
- - `remarkCodeAnnotations(options?)` — remark 変換
125
- - `rehypeCodeAnnotations(options?)` — rehype 変換
126
- - `parseCodeAnnotations(meta)` — フェンスメタをプランに変換
127
- - `parseLineRanges(spec)` — `1,3-5` を行番号に変換
128
- - `collectCodeAnnotations(meta, code)` — メタとインラインマーカーをまとめて解析
129
- - `resolveCodeAnnotationsOptions(options?)` — 既定値を補完
130
- - 型: `CodeAnnotationsOptions`、`ResolvedCodeAnnotationsOptions`、
131
- `CodeAnnotationPlan`、`CodeAnnotationKind`
132
-
133
- ## 関連資料
134
-
135
- - [プラグインシステム](../../../docs/ja/plugin-system.md)
136
- - [`@riebeckite/plugin-code-enhance`](../code-enhance/README_ja.md)
1
+ # @riebeckite/plugin-code-annotations
2
+
3
+ VitePress / Docusaurus 風のコードブロック装飾を加えるプラグインです。フェンスの
4
+ メタ情報による行の強調と、`[!code ...]` のインラインマーカーによるフォーカス・
5
+ 差分表示に対応します。素の `<pre><code>` と
6
+ `@riebeckite/plugin-code-enhance` の行ラッパーの両方で動作します。
7
+
8
+ [English](./README.md)
9
+
10
+ ## 設定
11
+
12
+ ```ts
13
+ import { defineConfig } from "@riebeckite/core";
14
+ import { codeAnnotations } from "@riebeckite/plugin-code-annotations";
15
+
16
+ export default defineConfig({
17
+ // ...
18
+ plugins: [codeAnnotations()],
19
+ });
20
+ ```
21
+
22
+ プラグインは `style.css` のみを登録します。クライアントエントリーはなく、
23
+ 実行時 JavaScript は追加しません。
24
+
25
+ ## 書き方
26
+
27
+ ### フェンスメタによる行の強調
28
+
29
+ 言語の後ろに波括弧で行範囲を書きます。Docusaurus や VitePress と同じ記法です。
30
+
31
+ ````md
32
+ ```js {2,4-5}
33
+ const a = 1;
34
+ const b = 2;
35
+ const c = 3;
36
+ const d = 4;
37
+ const e = 5;
38
+ ```
39
+ ````
40
+
41
+ 2、4、5 行目に `rb-code__line--highlighted` が付きます。
42
+
43
+ ### フォーカス
44
+
45
+ `focus` メタ、またはインラインの `[!code focus]` を使います。行数を指定すると
46
+ その行から続く行までをまとめてフォーカスします。
47
+
48
+ ````md
49
+ ```js focus:{2}
50
+ const a = 1;
51
+ const b = 2;
52
+ ```
53
+ ````
54
+
55
+ ````md
56
+ ```js
57
+ const a = 1; // [!code focus]
58
+ const b = 2;
59
+ ```
60
+ ````
61
+
62
+ `rb-code__line--focused` が付きます。`[!code focus:3]` なら 3 行分です。
63
+
64
+ ### 差分
65
+
66
+ ````md
67
+ ```js
68
+ const kept = true;
69
+ const added = true; // [!code ++]
70
+ const removed = false; // [!code --]
71
+ ```
72
+ ````
73
+
74
+ マーカーのコメントは表示テキストから取り除かれ、行には
75
+ `rb-code__line--added` または `rb-code__line--removed` が付きます。
76
+
77
+ ### 明示的な強調マーカー
78
+
79
+ ````md
80
+ ```js
81
+ const value = 1; // [!code highlight]
82
+ ```
83
+ ````
84
+
85
+ マーカーは `//`、`#`、`--`、`<!-- -->` のコメント記法に対応します。JavaScript、
86
+ シェル、SQL、Lua、HTML などで同じ書き方が使えます。
87
+
88
+ ## オプション
89
+
90
+ | オプション | 既定値 | 内容 |
91
+ | --- | --- | --- |
92
+ | `className` | `"rb-code"` | ブロック直下（`<pre>` または `rehype-pretty-code` の `<figure>`）に付くクラス |
93
+ | `lineClassName` | `"rb-code__line"` | 生成する行ラッパーのクラス |
94
+ | `highlightClassName` | `"rb-code__line--highlighted"` | 強調行のクラス |
95
+ | `addedClassName` | `"rb-code__line--added"` | `[!code ++]` 行のクラス |
96
+ | `removedClassName` | `"rb-code__line--removed"` | `[!code --]` 行のクラス |
97
+ | `focusClassName` | `"rb-code__line--focused"` | フォーカス行のクラス |
98
+ | `language` | 未設定 | 指定した言語のブロックだけを対象にする |
99
+
100
+ ```ts
101
+ codeAnnotations({ highlightClassName: "is-highlighted" });
102
+ ```
103
+
104
+ ## code-enhance との併用
105
+
106
+ `@riebeckite/plugin-code-annotations` は
107
+ `@riebeckite/plugin-code-enhance` を import せず、依存もしません。素の
108
+ `<pre><code>` のテキストと、`rehype-pretty-code` が出力する `.line` ラッパーの
109
+ 両方を検出します。
110
+
111
+ - 行ラッパーがすでにある場合は、既存のクラスに追記し、既存の `data-line` を
112
+ そのまま使います。
113
+ - ない場合は、コード本文を
114
+ `<span class="rb-code__line" data-line="N">` に分割します。
115
+
116
+ `rehype-pretty-code` は `<code>` 要素を差し替えるため、注釈プランは保持される
117
+ フェンスメタにも複製します。これにより code-enhance の後でも注釈が適用されます。
118
+ プラグイン配列では `codeEnhance()` の後に `codeAnnotations()` を置いてください。
119
+ `order: 10` により、順序に関わらず強調処理の後に実行されます。
120
+
121
+ ## 公開 API
122
+
123
+ - `codeAnnotations(options?)` / `codeAnnotationsPlugin(options?)` — プラグインファクトリ
124
+ - `remarkCodeAnnotations(options?)` — remark 変換
125
+ - `rehypeCodeAnnotations(options?)` — rehype 変換
126
+ - `parseCodeAnnotations(meta)` — フェンスメタをプランに変換
127
+ - `parseLineRanges(spec)` — `1,3-5` を行番号に変換
128
+ - `collectCodeAnnotations(meta, code)` — メタとインラインマーカーをまとめて解析
129
+ - `resolveCodeAnnotationsOptions(options?)` — 既定値を補完
130
+ - 型: `CodeAnnotationsOptions`、`ResolvedCodeAnnotationsOptions`、
131
+ `CodeAnnotationPlan`、`CodeAnnotationKind`
132
+
133
+ ## 関連資料
134
+
135
+ - [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
136
+ - [`@riebeckite/plugin-code-enhance`](../code-enhance/README_ja.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-code-annotations",
3
- "version": "0.0.11",
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.11"
18
+ "@riebeckite/core": "0.0.13"
19
19
  },
20
20
  "devDependencies": {
21
21
  "tsx": "^4.22.4",
22
- "@riebeckite/test": "0.0.11"
22
+ "@riebeckite/test": "0.0.13"
23
23
  },
24
24
  "publishConfig": {
25
25
  "access": "public"