@riebeckite/plugin-related-posts 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.
Files changed (3) hide show
  1. package/README.md +97 -97
  2. package/README_ja.md +99 -99
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,97 +1,97 @@
1
- # @riebeckite/plugin-related-posts
2
-
3
- Build-time "related notes" navigation. For every published entry, the plugin
4
- ranks the other entries in the content manifest and appends a related-posts
5
- section to the rendered HTML. No client-side JavaScript is required.
6
-
7
- [日本語](./README_ja.md)
8
-
9
- ## Overview
10
-
11
- `relatedPosts()` reads the manifest's content graph and scores every other
12
- published entry against the current one:
13
-
14
- | Signal | Weight | Meaning |
15
- | ------ | ------ | ------- |
16
- | Direct link | 3 | The entry links to the candidate, or the candidate links to the entry |
17
- | Shared tag | 2 per common tag | The entry and the candidate share a tag |
18
- | Co-citation | 1 per common target | Both entries link to the same note |
19
-
20
- Candidates are sorted by score (descending), then by title, then by slug, and
21
- clamped to `limit`. Entries that score below `minScore` are dropped. When no
22
- candidate qualifies, the entry's HTML is left untouched.
23
-
24
- The plugin updates both `entry.html` and the cached `PostContent.html` that the
25
- content route renders, so the section appears on generated pages and in feeds.
26
-
27
- ## Usage
28
-
29
- ```ts
30
- import { defineConfig } from "@riebeckite/core";
31
- import { relatedPosts } from "@riebeckite/plugin-related-posts";
32
-
33
- export default defineConfig({
34
- // ...
35
- plugins: [relatedPosts()],
36
- });
37
- ```
38
-
39
- ## Options
40
-
41
- | Option | Type | Default | Description |
42
- | ------ | ---- | ------- | ----------- |
43
- | `limit` | `number` | `5` | Maximum number of related entries |
44
- | `minScore` | `number` | `1` | Minimum score required to be listed |
45
- | `heading` | `boolean` | `true` | Render the `<h2>` heading |
46
- | `headingText` | `string` | `"Related"` | Heading text |
47
- | `className` | `string` | `"rb-related-posts"` | Root CSS class |
48
- | `useTags` | `boolean` | `true` | Include the shared-tag signal |
49
- | `useBacklinks` | `boolean` | `true` | Include the direct-link signal |
50
-
51
- ```ts
52
- relatedPosts({
53
- limit: 8,
54
- minScore: 2,
55
- headingText: "Related notes",
56
- });
57
- ```
58
-
59
- ## Output
60
-
61
- ```html
62
- <nav class="rb-related-posts" data-related-posts>
63
- <h2 class="rb-related-posts__heading">Related</h2>
64
- <ul>
65
- <li class="rb-related-posts__item">
66
- <a class="rb-related-posts__link" href="/notes/example" data-related-score="5">Example Note</a>
67
- </li>
68
- </ul>
69
- </nav>
70
- ```
71
-
72
- ## Style
73
-
74
- The package ships `style.css`. Register it like any other plugin stylesheet:
75
-
76
- ```ts
77
- import "@riebeckite/plugin-related-posts/style.css";
78
- ```
79
-
80
- ## Exports
81
-
82
- - `relatedPosts(options?)` — plugin factory
83
- - `relatedPostsPlugin` — alias of `relatedPosts`
84
- - `resolveRelatedPostsOptions(options?)` — apply option defaults
85
- - `buildRelatedPosts({ manifest, entry, options, config? })` — rank related entries
86
- - `renderRelatedPosts(entries, options)` — render the navigation HTML
87
- - Types: `RelatedPostsOptions`, `ResolvedRelatedPostsOptions`, `RelatedPostsEntry`
88
-
89
- ## Limitations
90
-
91
- - Ranking is fixed at build time. A full rebuild always recomputes correctly.
92
- - Only tags, direct links, and co-citations are considered. Reading time,
93
- recency, and folders are intentionally ignored to keep ranking deterministic.
94
-
95
- ## See also
96
-
97
- - [Plugin guide](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-related-posts
2
+
3
+ Build-time "related notes" navigation. For every published entry, the plugin
4
+ ranks the other entries in the content manifest and appends a related-posts
5
+ section to the rendered HTML. No client-side JavaScript is required.
6
+
7
+ [日本語](./README_ja.md)
8
+
9
+ ## Overview
10
+
11
+ `relatedPosts()` reads the manifest's content graph and scores every other
12
+ published entry against the current one:
13
+
14
+ | Signal | Weight | Meaning |
15
+ | ------ | ------ | ------- |
16
+ | Direct link | 3 | The entry links to the candidate, or the candidate links to the entry |
17
+ | Shared tag | 2 per common tag | The entry and the candidate share a tag |
18
+ | Co-citation | 1 per common target | Both entries link to the same note |
19
+
20
+ Candidates are sorted by score (descending), then by title, then by slug, and
21
+ clamped to `limit`. Entries that score below `minScore` are dropped. When no
22
+ candidate qualifies, the entry's HTML is left untouched.
23
+
24
+ The plugin updates both `entry.html` and the cached `PostContent.html` that the
25
+ content route renders, so the section appears on generated pages and in feeds.
26
+
27
+ ## Usage
28
+
29
+ ```ts
30
+ import { defineConfig } from "@riebeckite/core";
31
+ import { relatedPosts } from "@riebeckite/plugin-related-posts";
32
+
33
+ export default defineConfig({
34
+ // ...
35
+ plugins: [relatedPosts()],
36
+ });
37
+ ```
38
+
39
+ ## Options
40
+
41
+ | Option | Type | Default | Description |
42
+ | ------ | ---- | ------- | ----------- |
43
+ | `limit` | `number` | `5` | Maximum number of related entries |
44
+ | `minScore` | `number` | `1` | Minimum score required to be listed |
45
+ | `heading` | `boolean` | `true` | Render the `<h2>` heading |
46
+ | `headingText` | `string` | `"Related"` | Heading text |
47
+ | `className` | `string` | `"rb-related-posts"` | Root CSS class |
48
+ | `useTags` | `boolean` | `true` | Include the shared-tag signal |
49
+ | `useBacklinks` | `boolean` | `true` | Include the direct-link signal |
50
+
51
+ ```ts
52
+ relatedPosts({
53
+ limit: 8,
54
+ minScore: 2,
55
+ headingText: "Related notes",
56
+ });
57
+ ```
58
+
59
+ ## Output
60
+
61
+ ```html
62
+ <nav class="rb-related-posts" data-related-posts>
63
+ <h2 class="rb-related-posts__heading">Related</h2>
64
+ <ul>
65
+ <li class="rb-related-posts__item">
66
+ <a class="rb-related-posts__link" href="/notes/example" data-related-score="5">Example Note</a>
67
+ </li>
68
+ </ul>
69
+ </nav>
70
+ ```
71
+
72
+ ## Style
73
+
74
+ The package ships `style.css`. Register it like any other plugin stylesheet:
75
+
76
+ ```ts
77
+ import "@riebeckite/plugin-related-posts/style.css";
78
+ ```
79
+
80
+ ## Exports
81
+
82
+ - `relatedPosts(options?)` — plugin factory
83
+ - `relatedPostsPlugin` — alias of `relatedPosts`
84
+ - `resolveRelatedPostsOptions(options?)` — apply option defaults
85
+ - `buildRelatedPosts({ manifest, entry, options, config? })` — rank related entries
86
+ - `renderRelatedPosts(entries, options)` — render the navigation HTML
87
+ - Types: `RelatedPostsOptions`, `ResolvedRelatedPostsOptions`, `RelatedPostsEntry`
88
+
89
+ ## Limitations
90
+
91
+ - Ranking is fixed at build time. A full rebuild always recomputes correctly.
92
+ - Only tags, direct links, and co-citations are considered. Reading time,
93
+ recency, and folders are intentionally ignored to keep ranking deterministic.
94
+
95
+ ## See also
96
+
97
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,99 +1,99 @@
1
- # @riebeckite/plugin-related-posts
2
-
3
- ビルド時に「関連ノート」ナビゲーションを生成するプラグインです。公開対象の
4
- 各エントリについて、コンテンツマニフェスト上の他のエントリをスコア順に並べ、
5
- 関連ノートのセクションを HTML に追記します。クライアント側 JavaScript は
6
- 不要です。
7
-
8
- [English](./README.md)
9
-
10
- ## 仕組み
11
-
12
- `relatedPosts()` はマニフェストのコンテンツグラフを読み、現在のエントリと
13
- 他の公開エントリを次のシグナルで採点します。
14
-
15
- | シグナル | 重み | 意味 |
16
- | -------- | ---- | ---- |
17
- | 直接リンク | 3 | 現在のエントリが候補へ、または候補が現在のエントリへリンクしている |
18
- | タグの共有 | 共通タグ1件につき2 | 現在のエントリと候補が同じタグを持つ |
19
- | 共引用 | 共通リンク先1件につき1 | 両方のエントリが同じノートへリンクしている |
20
-
21
- 候補はスコアの降順、同点ならタイトル、さらに同点ならスラッグの順に並べ、
22
- `limit` 件に絞ります。`minScore` 未満の候補は除外します。条件を満たす候補が
23
- 1件もない場合、そのエントリの HTML は変更しません。
24
-
25
- `entry.html` と、コンテンツルートが描画するキャッシュ済みの
26
- `PostContent.html` の両方を更新するため、生成ページとフィードの両方に
27
- セクションが反映されます。
28
-
29
- ## 使い方
30
-
31
- ```ts
32
- import { defineConfig } from "@riebeckite/core";
33
- import { relatedPosts } from "@riebeckite/plugin-related-posts";
34
-
35
- export default defineConfig({
36
- // ...
37
- plugins: [relatedPosts()],
38
- });
39
- ```
40
-
41
- ## オプション
42
-
43
- | オプション | 型 | 既定値 | 説明 |
44
- | ---------- | -- | ------ | ---- |
45
- | `limit` | `number` | `5` | 表示する関連エントリの最大件数 |
46
- | `minScore` | `number` | `1` | 表示に必要な最小スコア |
47
- | `heading` | `boolean` | `true` | `<h2>` 見出しを出力する |
48
- | `headingText` | `string` | `"Related"` | 見出しの文言 |
49
- | `className` | `string` | `"rb-related-posts"` | ルート要素の CSS クラス |
50
- | `useTags` | `boolean` | `true` | タグ共有のシグナルを使う |
51
- | `useBacklinks` | `boolean` | `true` | 直接リンクのシグナルを使う |
52
-
53
- ```ts
54
- relatedPosts({
55
- limit: 8,
56
- minScore: 2,
57
- headingText: "関連ノート",
58
- });
59
- ```
60
-
61
- ## 出力
62
-
63
- ```html
64
- <nav class="rb-related-posts" data-related-posts>
65
- <h2 class="rb-related-posts__heading">Related</h2>
66
- <ul>
67
- <li class="rb-related-posts__item">
68
- <a class="rb-related-posts__link" href="/notes/example" data-related-score="5">Example Note</a>
69
- </li>
70
- </ul>
71
- </nav>
72
- ```
73
-
74
- ## スタイル
75
-
76
- パッケージに `style.css` が含まれます。他のプラグインと同じように読み込みます。
77
-
78
- ```ts
79
- import "@riebeckite/plugin-related-posts/style.css";
80
- ```
81
-
82
- ## エクスポート
83
-
84
- - `relatedPosts(options?)` — プラグインファクトリ
85
- - `relatedPostsPlugin` — `relatedPosts` のエイリアス
86
- - `resolveRelatedPostsOptions(options?)` — オプションの既定値を適用する
87
- - `buildRelatedPosts({ manifest, entry, options, config? })` — 関連エントリを採点・整列する
88
- - `renderRelatedPosts(entries, options)` — ナビゲーション HTML を生成する
89
- - 型: `RelatedPostsOptions`, `ResolvedRelatedPostsOptions`, `RelatedPostsEntry`
90
-
91
- ## 制約
92
-
93
- - 並び順はビルド時に確定します。再ビルドすれば常に正しく再計算されます。
94
- - 判定材料はタグ・直接リンク・共引用のみです。読了時間や新しさ、フォルダは
95
- 順位を決定的に保つため意図的に使いません。
96
-
97
- ## ????
98
-
99
- - [?????????](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-related-posts
2
+
3
+ ビルド時に「関連ノート」ナビゲーションを生成するプラグインです。公開対象の
4
+ 各エントリについて、コンテンツマニフェスト上の他のエントリをスコア順に並べ、
5
+ 関連ノートのセクションを HTML に追記します。クライアント側 JavaScript は
6
+ 不要です。
7
+
8
+ [English](./README.md)
9
+
10
+ ## 仕組み
11
+
12
+ `relatedPosts()` はマニフェストのコンテンツグラフを読み、現在のエントリと
13
+ 他の公開エントリを次のシグナルで採点します。
14
+
15
+ | シグナル | 重み | 意味 |
16
+ | -------- | ---- | ---- |
17
+ | 直接リンク | 3 | 現在のエントリが候補へ、または候補が現在のエントリへリンクしている |
18
+ | タグの共有 | 共通タグ1件につき2 | 現在のエントリと候補が同じタグを持つ |
19
+ | 共引用 | 共通リンク先1件につき1 | 両方のエントリが同じノートへリンクしている |
20
+
21
+ 候補はスコアの降順、同点ならタイトル、さらに同点ならスラッグの順に並べ、
22
+ `limit` 件に絞ります。`minScore` 未満の候補は除外します。条件を満たす候補が
23
+ 1件もない場合、そのエントリの HTML は変更しません。
24
+
25
+ `entry.html` と、コンテンツルートが描画するキャッシュ済みの
26
+ `PostContent.html` の両方を更新するため、生成ページとフィードの両方に
27
+ セクションが反映されます。
28
+
29
+ ## 使い方
30
+
31
+ ```ts
32
+ import { defineConfig } from "@riebeckite/core";
33
+ import { relatedPosts } from "@riebeckite/plugin-related-posts";
34
+
35
+ export default defineConfig({
36
+ // ...
37
+ plugins: [relatedPosts()],
38
+ });
39
+ ```
40
+
41
+ ## オプション
42
+
43
+ | オプション | 型 | 既定値 | 説明 |
44
+ | ---------- | -- | ------ | ---- |
45
+ | `limit` | `number` | `5` | 表示する関連エントリの最大件数 |
46
+ | `minScore` | `number` | `1` | 表示に必要な最小スコア |
47
+ | `heading` | `boolean` | `true` | `<h2>` 見出しを出力する |
48
+ | `headingText` | `string` | `"Related"` | 見出しの文言 |
49
+ | `className` | `string` | `"rb-related-posts"` | ルート要素の CSS クラス |
50
+ | `useTags` | `boolean` | `true` | タグ共有のシグナルを使う |
51
+ | `useBacklinks` | `boolean` | `true` | 直接リンクのシグナルを使う |
52
+
53
+ ```ts
54
+ relatedPosts({
55
+ limit: 8,
56
+ minScore: 2,
57
+ headingText: "関連ノート",
58
+ });
59
+ ```
60
+
61
+ ## 出力
62
+
63
+ ```html
64
+ <nav class="rb-related-posts" data-related-posts>
65
+ <h2 class="rb-related-posts__heading">Related</h2>
66
+ <ul>
67
+ <li class="rb-related-posts__item">
68
+ <a class="rb-related-posts__link" href="/notes/example" data-related-score="5">Example Note</a>
69
+ </li>
70
+ </ul>
71
+ </nav>
72
+ ```
73
+
74
+ ## スタイル
75
+
76
+ パッケージに `style.css` が含まれます。他のプラグインと同じように読み込みます。
77
+
78
+ ```ts
79
+ import "@riebeckite/plugin-related-posts/style.css";
80
+ ```
81
+
82
+ ## エクスポート
83
+
84
+ - `relatedPosts(options?)` — プラグインファクトリ
85
+ - `relatedPostsPlugin` — `relatedPosts` のエイリアス
86
+ - `resolveRelatedPostsOptions(options?)` — オプションの既定値を適用する
87
+ - `buildRelatedPosts({ manifest, entry, options, config? })` — 関連エントリを採点・整列する
88
+ - `renderRelatedPosts(entries, options)` — ナビゲーション HTML を生成する
89
+ - 型: `RelatedPostsOptions`, `ResolvedRelatedPostsOptions`, `RelatedPostsEntry`
90
+
91
+ ## 制約
92
+
93
+ - 並び順はビルド時に確定します。再ビルドすれば常に正しく再計算されます。
94
+ - 判定材料はタグ・直接リンク・共引用のみです。読了時間や新しさ、フォルダは
95
+ 順位を決定的に保つため意図的に使いません。
96
+
97
+ ## ????
98
+
99
+ - [?????????](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-related-posts",
3
- "version": "0.0.12",
3
+ "version": "0.0.14",
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.14"
19
19
  },
20
20
  "devDependencies": {
21
21
  "tsx": "^4.22.4",
22
- "@riebeckite/test": "0.0.12"
22
+ "@riebeckite/test": "0.0.14"
23
23
  },
24
24
  "publishConfig": {
25
25
  "access": "public"