@riebeckite/plugin-related-posts 0.0.22 → 0.0.23

package/README.md

@@ -4,7 +4,9 @@
 
 Build-time "related notes" navigation. For every published entry, the plugin
 ranks the other entries in the content manifest and contributes a related-posts
-section to the `article.footer` Slot. No client-side JavaScript is required.
+section. The Site places the `<RelatedPosts />` component itself, normally once
+after article content, to display the navigation. No client-side JavaScript is
+required.
 
 [日本語](./README_ja.md)
 
@@ -23,9 +25,9 @@ Candidates are sorted by score (descending), then by title, then by slug, and
 clamped to `limit`. Entries that score below `minScore` are dropped. When no
 candidate qualifies, the entry's HTML is left untouched.
 
-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.
+The Site places the `<RelatedPosts entries={...} options={...} />` component
+itself, normally once after article content. The component renders nothing when
+no related entries qualify.
 
 ## Quick Start
 
@@ -41,9 +43,10 @@ export default defineConfig({
 
 ## Advanced customization
 
-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.
+The Site can place the public server-rendered `<RelatedPosts />` 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 {
@@ -52,10 +55,10 @@ import {
   resolveRelatedPostsOptions,
 } from "@riebeckite/plugin-related-posts";
 
-const options = resolveRelatedPostsOptions({ render: false });
+const options = resolveRelatedPostsOptions({});
 const entries = buildRelatedPosts({ manifest, entry, options, config });
 
-return <aside><RelatedPosts entries={entries} options={options} /></aside>;
+return <nav rb-related-posts><RelatedPosts entries={entries} options={options} /></nav>;
 ```
 
 The official Starter already renders `article.footer` once. Remove the manual
@@ -66,7 +69,6 @@ rendering for the same article.
 
 | 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 |
@@ -85,7 +87,9 @@ relatedPosts({
 
 ## Display
 
-Related entries are rendered in the `article.footer` slot on eligible pages. This site renders the live navigation below the article when matching public entries exist.
+Related entries are rendered in the `article.footer` area on eligible pages.
+This site renders the live navigation below the article when matching public
+entries exist.
 
 ## Style
 

package/README_ja.md

@@ -4,8 +4,7 @@
 
 ビルド時に「関連ノート」ナビゲーションを生成するプラグインです。公開対象の
 各エントリについて、コンテンツマニフェスト上の他のエントリをスコア順に並べ、
-関連ノートのセクションを `article.footer` Slot に追加します。クライアント側 JavaScript は
-不要です。
+関連セクションを表示します。クライアント側 JavaScript は不要です。
 
 [English](./README.md)
 
@@ -24,9 +23,9 @@
 `limit` 件に絞ります。`minScore` 未満の候補は除外します。条件を満たす候補が
 1 件もない場合、そのエントリの HTML は変更しません。
 
-各マニフェストエントリの `article.footer` Slot にセクションを追加します。標準の
-記事フッターでこの Slot を描画している場合、生成ページとフィードの両方に
-セクションが反映されます。
+Site は `<RelatedPosts entries={...} options={...} />` コンポーネントを
+記事の後などに配置します。条件を満たす関連エントリがない場合、コンポーネントは
+何も描画しません。
 
 ## クイックスタート
 
@@ -42,14 +41,17 @@ export default defineConfig({
 
 ## 高度なカスタマイズ
 
-Site のレイアウト内で任意の位置に配置できるサーバー描画の Hono JSX Component を公開しています。`render: false` で自動の `article.footer` Slot 追加を止め、既存の helper で entries を計算して解決済み options を渡してください。採点と公開境界のフィルタリングは維持されます。
+Site のレイアウト内で任意の位置に配置できるサーバー描画の Hono JSX Component
+を公開しています。`render: false` で自動の `article.footer` Slot 追加を止め、
+既存の helper で entries を計算して解決済み options を渡してください。採点と公開境界のフィルタリングは維持されます。
 
 ```tsx
 import { buildRelatedPosts, RelatedPosts, resolveRelatedPostsOptions } from "@riebeckite/plugin-related-posts";
 
-const options = resolveRelatedPostsOptions({ render: false });
+const options = resolveRelatedPostsOptions({});
 const entries = buildRelatedPosts({ manifest, entry, options, config });
-return <aside><RelatedPosts entries={entries} options={options} /></aside>;
+
+<nav rb-related-posts><RelatedPosts entries={entries} options={options} /></nav>;
 ```
 
 公式 Starter は `article.footer` を一度描画します。手動配置を消すにはコンポーネントを消します。自動描画を有効にしたまま同じ記事へ手動描画しないでください。
@@ -58,7 +60,6 @@ return <aside><RelatedPosts entries={entries} options={options} /></aside>;
 
 | オプション | 型 | 既定値 | 説明 |
 | ---------- | -- | ------ | ---- |
-| `render` | `boolean` | `true` | `article.footer` への自動追加。手動配置では `false` |
 | `limit` | `number` | `5` | 表示する関連エントリの最大件数 |
 | `minScore` | `number` | `1` | 表示に必要な最小スコア |
 | `heading` | `boolean` | `true` | `<h2>` 見出しを出力する |
@@ -77,7 +78,9 @@ relatedPosts({
 
 ## 表示
 
-関連エントリは対象ページの `article.footer` スロットに描画されます。このサイトでは、条件に合う公開エントリがあれば記事下に実際のナビゲーションを表示します。
+関連エントリは対象ページの `article.footer`  area に描画されます。この
+サイトでは、条件に合う公開エントリがあれば記事下に実際のナビゲーションを
+表示します。
 
 ## スタイル
 

package/dist/components/related-posts.d.ts

@@ -1,7 +1,7 @@
 import type { RelatedPostsEntry, ResolvedRelatedPostsOptions } from "../src/types.js";
-type Props = {
+export type RelatedPostsProps = {
     entries: readonly RelatedPostsEntry[];
     options: ResolvedRelatedPostsOptions;
 };
-export default function RelatedPosts(props: Props): import("hono/jsx/jsx-dev-runtime").JSX.Element;
-export {};
+declare const RelatedPosts: (props: Readonly<RelatedPostsProps>) => import("hono/jsx/jsx-dev-runtime").JSX.Element;
+export default RelatedPosts;

package/dist/components/related-posts.js

@@ -1,6 +1,6 @@
 // components/related-posts.tsx
 import { jsx, jsxs } from "hono/jsx/jsx-runtime";
-function RelatedPosts(props) {
+var RelatedPosts = ((props) => {
   if (props.entries.length === 0) return null;
   const { className, heading, headingText } = props.options;
   return /* @__PURE__ */ jsxs("nav", { class: className, "data-related-posts": "", children: [
@@ -15,7 +15,8 @@ function RelatedPosts(props) {
       }
     ) }, entry.slug)) })
   ] });
-}
+});
+var related_posts_default = RelatedPosts;
 export {
-  RelatedPosts as default
+  related_posts_default as default
 };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import type { RelatedPostsOptions } from "./src/types.js";
+export type { RelatedPostsProps } from "./components/related-posts.js";
 export { default as RelatedPosts } from "./components/related-posts.js";
 export { resolveRelatedPostsOptions } from "./src/options.js";
-export { buildRelatedPosts, CO_CITATION_WEIGHT, DIRECT_LINK_WEIGHT, isEligibleRelatedEntry, SHARED_TAG_WEIGHT, } from "./src/related.js";
+export { buildRelatedPosts, CO_CITATION_WEIGHT, DIRECT_LINK_WEIGHT, getRelatedPosts, isEligibleRelatedEntry, SHARED_TAG_WEIGHT, } from "./src/related.js";
 export { RELATED_POSTS_ATTRIBUTE, renderRelatedPosts, } from "./src/render.js";
 export type { RelatedPostsEntry, RelatedPostsOptions, ResolvedRelatedPostsOptions, } from "./src/types.js";
 export declare const RELATED_POSTS_PLUGIN_NAME = "related-posts";

package/dist/index.js

@@ -1,14 +1,12 @@
 // index.ts
 import {
-  appendContentBodySlot,
   createStyleAsset,
   definePlugin
 } from "@riebeckite/core";
-import { renderToString as renderToString2 } from "hono/jsx/dom/server";
 
 // components/related-posts.tsx
 import { jsx, jsxs } from "hono/jsx/jsx-runtime";
-function RelatedPosts(props) {
+var RelatedPosts = ((props) => {
   if (props.entries.length === 0) return null;
   const { className, heading, headingText } = props.options;
   return /* @__PURE__ */ jsxs("nav", { class: className, "data-related-posts": "", children: [
@@ -23,7 +21,8 @@ function RelatedPosts(props) {
       }
     ) }, entry.slug)) })
   ] });
-}
+});
+var related_posts_default = RelatedPosts;
 
 // src/options.ts
 var DEFAULT_RELATED_POSTS_LIMIT = 5;
@@ -95,6 +94,60 @@ function buildRelatedPosts(args) {
   candidates.sort(compareRelatedEntries);
   return candidates.slice(0, options.limit);
 }
+var getRelatedPosts = ({ view, entry, options }) => {
+  const resolved = options ?? {
+    limit: 5,
+    minScore: 1,
+    useTags: true,
+    useBacklinks: true,
+    heading: true,
+    headingText: "Related posts",
+    className: "rr-related-posts"
+  };
+  const scores = /* @__PURE__ */ new Map();
+  const outgoing = new Set(
+    entry.links.flatMap(
+      (link) => link.kind === "note" && link.slug ? [link.slug] : []
+    )
+  );
+  if (resolved.useTags) {
+    for (const tag of entry.tags) {
+      for (const candidate of view.getDiscoverableEntriesByTag(tag)) {
+        if (candidate.slug !== entry.slug) {
+          addScore(scores, candidate.slug, SHARED_TAG_WEIGHT);
+        }
+      }
+    }
+  }
+  if (resolved.useBacklinks) {
+    for (const candidate of [
+      ...view.getDiscoverableOutgoing(entry.slug),
+      ...view.getDiscoverableIncoming(entry.slug)
+    ]) {
+      if (candidate.slug !== entry.slug) {
+        addScore(scores, candidate.slug, DIRECT_LINK_WEIGHT);
+      }
+    }
+  }
+  for (const target of outgoing) {
+    for (const candidate of view.getDiscoverableIncoming(target)) {
+      if (candidate.slug !== entry.slug) {
+        addScore(scores, candidate.slug, CO_CITATION_WEIGHT);
+      }
+    }
+  }
+  return [...scores].flatMap(([slug, score]) => {
+    const candidate = view.findDiscoverableBySlug(slug);
+    return candidate && score >= resolved.minScore ? [
+      {
+        slug,
+        permalink: candidate.permalink,
+        title: candidate.title,
+        score
+      }
+    ] : [];
+  }).sort(compareRelatedEntries).slice(0, resolved.limit);
+};
 function isEligibleRelatedEntry(entry, manifest, _config) {
   if (manifest.redirects.has(entry.permalink)) return false;
   return manifest.discoverableEntries.some(
@@ -124,13 +177,12 @@ function addScore(scores, slug, weight) {
 import { renderToString } from "hono/jsx/dom/server";
 var RELATED_POSTS_ATTRIBUTE = "data-related-posts";
 function renderRelatedPosts(entries, options) {
-  return renderToString(RelatedPosts({ entries, options }));
+  return renderToString(related_posts_default({ entries, options }));
 }
 
 // index.ts
 var RELATED_POSTS_PLUGIN_NAME = "related-posts";
 function relatedPosts(options = {}) {
-  const resolved = resolveRelatedPostsOptions(options);
   return definePlugin({
     name: RELATED_POSTS_PLUGIN_NAME,
     order: 100,
@@ -138,38 +190,21 @@ function relatedPosts(options = {}) {
       version: "related-posts-v1",
       dependencyMode: "none"
     },
-    outputDependencies: [{ type: "global" }],
+    contentOutputDependencies: [{ type: "global" }],
     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;
-        const related = buildRelatedPosts({
-          manifest,
-          entry,
-          options: resolved,
-          config: context.config
-        });
-        if (related.length === 0) continue;
-        appendContentBodySlot(
-          entry,
-          "article.footer",
-          renderToString2(RelatedPosts({ entries: related, options: resolved }))
-        );
-      }
-    },
-    assets: [createStyleAsset(RELATED_POSTS_PLUGIN_NAME)]
+    assets: [
+      createStyleAsset(
+        RELATED_POSTS_PLUGIN_NAME,
+        "@riebeckite/plugin-related-posts/style.css"
+      )
+    ]
   });
 }
 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." });
   }
@@ -204,9 +239,10 @@ export {
   DIRECT_LINK_WEIGHT,
   RELATED_POSTS_ATTRIBUTE,
   RELATED_POSTS_PLUGIN_NAME,
-  RelatedPosts,
+  related_posts_default as RelatedPosts,
   SHARED_TAG_WEIGHT,
   buildRelatedPosts,
+  getRelatedPosts,
   isEligibleRelatedEntry,
   relatedPosts,
   relatedPostsPlugin,

package/dist/src/related.d.ts

@@ -1,4 +1,4 @@
-import type { ContentManifest, ContentManifestEntry, ResolvedRiebeckiteConfig } from "@riebeckite/core";
+import type { ContentManifest, ContentManifestEntry, PluginDataHelper, PublicContentEntry, PublicContentView, ResolvedRiebeckiteConfig } from "@riebeckite/core";
 import type { RelatedPostsEntry, ResolvedRelatedPostsOptions } from "./types.js";
 /**
  * Weights are deterministic constants: the same manifest always produces the
@@ -23,6 +23,11 @@ export type BuildRelatedPostsArgs = {
  * and the Core-resolved publishing view.
  */
 export declare function buildRelatedPosts(args: BuildRelatedPostsArgs): RelatedPostsEntry[];
+export declare const getRelatedPosts: PluginDataHelper<{
+    view: PublicContentView;
+    entry: PublicContentEntry;
+    options?: ResolvedRelatedPostsOptions;
+}, readonly RelatedPostsEntry[]>;
 /**
  * An entry may receive a related-posts section (and be offered as a related
  * candidate) only when it is discoverable and its canonical permalink is not

package/dist/src/types.d.ts

@@ -1,6 +1,5 @@
 /** 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.22",
+  "version": "0.0.23",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,11 +22,11 @@
   },
   "dependencies": {
     "hono": "^4.12.25",
-    "@riebeckite/core": "0.0.22"
+    "@riebeckite/core": "0.0.23"
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.22"
+    "@riebeckite/test": "0.0.23"
   },
   "publishConfig": {
     "access": "public"