@riebeckite/plugin-related-posts 0.0.19 → 0.0.21

package/README.md

@@ -6,7 +6,7 @@ section to the `article.footer` Slot. No client-side JavaScript is required.
 
 [日本語](./README_ja.md)
 
-## Overview
+## Recommended placement
 
 `relatedPosts()` reads the manifest's content graph and scores every other
 published entry against the current one:
@@ -25,7 +25,7 @@ The plugin contributes the section to each manifest entry's `article.footer`
 Slot. The Site decides where to render that Slot, so the section appears on
 generated pages and in feeds when the standard article footer is used.
 
-## Usage
+## Quick Start
 
 ```ts
 import { defineConfig } from "@riebeckite/core";
@@ -37,26 +37,34 @@ export default defineConfig({
 });
 ```
 
-## Component
+## Advanced customization
 
-In addition to the automatic `article.footer` Slot contribution, the navigation
-is available as a server-rendered Hono JSX Component for placement in a Site
-layout. Build the entries with the existing helper and pass resolved options:
+The Site can place the public server-rendered component anywhere. Set
+`render: false` first to prevent the automatic `article.footer` contribution;
+ranking and publication filtering remain available through the public helpers.
 
 ```tsx
-import RelatedPosts from "@riebeckite/plugin-related-posts/components";
+import {
+  buildRelatedPosts,
+  RelatedPosts,
+  resolveRelatedPostsOptions,
+} from "@riebeckite/plugin-related-posts";
 
-<RelatedPosts entries={related} options={resolvedOptions} />;
+const options = resolveRelatedPostsOptions({ render: false });
+const entries = buildRelatedPosts({ manifest, entry, options, config });
+
+return <aside><RelatedPosts entries={entries} options={options} /></aside>;
 ```
 
-`related` is the result of `buildRelatedPosts()` and `resolvedOptions` is the
-result of `resolveRelatedPostsOptions()`. Import `style.css` when the Plugin is
-not registered.
+The official Starter already renders `article.footer` once. Remove the manual
+component to remove a manual placement. Do not use it alongside automatic
+rendering for the same article.
 
 ## Options
 
 | Option | Type | Default | Description |
 | ------ | ---- | ------- | ----------- |
+| `render` | `boolean` | `true` | Append generated navigation to `article.footer`; set `false` for manual placement |
 | `limit` | `number` | `5` | Maximum number of related entries |
 | `minScore` | `number` | `1` | Minimum score required to be listed |
 | `heading` | `boolean` | `true` | Render the `<h2>` heading |
@@ -112,4 +120,4 @@ import "@riebeckite/plugin-related-posts/style.css";
 
 ## See also
 
-- [Plugin guide](../../../docs/docs/reference/plugin-api.en.md)
+- [Plugin guide](../../../docs/docs/reference/plugin-api.md)

package/README_ja.md

@@ -7,7 +7,7 @@
 
 [English](./README.md)
 
-## 仕組み
+## 推奨配置
 
 `relatedPosts()` はマニフェストのコンテンツグラフを読み、現在のエントリと
 他の公開エントリを次のシグナルで採点します。
@@ -26,7 +26,7 @@
 記事フッターでこの Slot を描画している場合、生成ページとフィードの両方に
 セクションが反映されます。
 
-## 使い方
+## クイックスタート
 
 ```ts
 import { defineConfig } from "@riebeckite/core";
@@ -38,26 +38,25 @@ export default defineConfig({
 });
 ```
 
-## Component として使う
+## 高度なカスタマイズ
 
-自動の `article.footer` Slot への追加に加え、Site のレイアウト内で任意の位置に
-配置できる、サーバー描画の Hono JSX Component も公開しています。既存の helper
-で entries を計算し、解決済みの options を渡してください。
+Site のレイアウト内で任意の位置に配置できるサーバー描画の Hono JSX Component を公開しています。`render: false` で自動の `article.footer` Slot 追加を止め、既存の helper で entries を計算して解決済み options を渡してください。採点と公開境界のフィルタリングは維持されます。
 
 ```tsx
-import RelatedPosts from "@riebeckite/plugin-related-posts/components";
+import { buildRelatedPosts, RelatedPosts, resolveRelatedPostsOptions } from "@riebeckite/plugin-related-posts";
 
-<RelatedPosts entries={related} options={resolvedOptions} />;
+const options = resolveRelatedPostsOptions({ render: false });
+const entries = buildRelatedPosts({ manifest, entry, options, config });
+return <aside><RelatedPosts entries={entries} options={options} /></aside>;
 ```
 
-`related` には `buildRelatedPosts()` の戻り値を、`resolvedOptions` には
-`resolveRelatedPostsOptions()` の戻り値を渡します。Plugin を登録しない場合は
-`style.css` も読み込んでください。
+公式 Starter は `article.footer` を一度描画します。手動配置を消すにはコンポーネントを消します。自動描画を有効にしたまま同じ記事へ手動描画しないでください。
 
 ## オプション
 
 | オプション | 型 | 既定値 | 説明 |
 | ---------- | -- | ------ | ---- |
+| `render` | `boolean` | `true` | `article.footer` への自動追加。手動配置では `false` |
 | `limit` | `number` | `5` | 表示する関連エントリの最大件数 |
 | `minScore` | `number` | `1` | 表示に必要な最小スコア |
 | `heading` | `boolean` | `true` | `<h2>` 見出しを出力する |
@@ -113,4 +112,4 @@ import "@riebeckite/plugin-related-posts/style.css";
 
 ## 関連リンク
 
-- [プラグイン API](../../../docs/docs/reference/plugin-api.md)
+- [プラグイン API](../../../docs/docs/reference/plugin-api.ja.md)

package/dist/index.js

@@ -142,6 +142,7 @@ function relatedPosts(options = {}) {
     options,
     validateOptions: validateRelatedPostsOptions,
     onManifestCreated: (context) => {
+      if (options.render === false) return;
       const { manifest } = context;
       for (const entry of manifest.discoverableEntries) {
         if (!isEligibleRelatedEntry(entry, manifest, context.config)) continue;
@@ -166,6 +167,9 @@ var relatedPostsPlugin = relatedPosts;
 function validateRelatedPostsOptions(options) {
   if (!options) return [];
   const issues = [];
+  if (options.render !== void 0 && typeof options.render !== "boolean") {
+    issues.push({ path: "render", message: "Expected a boolean." });
+  }
   if (options.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 0)) {
     issues.push({ path: "limit", message: "Expected a non-negative integer." });
   }

package/dist/src/types.d.ts

@@ -1,5 +1,6 @@
 /** Options accepted by `relatedPosts()`. */
 export type RelatedPostsOptions = {
+    render?: boolean;
     /** Maximum number of related entries to render. Defaults to `5`. */
     limit?: number;
     /** Minimum score a candidate must reach to be listed. Defaults to `1`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-related-posts",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,11 +22,11 @@
   },
   "dependencies": {
     "hono": "^4.12.25",
-    "@riebeckite/core": "0.0.19"
+    "@riebeckite/core": "0.0.21"
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.19"
+    "@riebeckite/test": "0.0.21"
   },
   "publishConfig": {
     "access": "public"

package/style.css

@@ -22,7 +22,7 @@
 
 .rb-related-posts ul {
   display: grid;
-  gap: 0.5rem;
+  gap: 0;
   margin: 0;
   padding: 0;
   list-style: none;
@@ -30,7 +30,8 @@
 
 .rb-related-posts__item {
   margin: 0;
-  padding: 0;
+  padding: 0.75rem 0;
+  border-bottom: 1px solid var(--rb-related-posts-rule);
 }
 
 .rb-related-posts__link {