@riebeckite/plugin-backlinks 0.0.20 → 0.0.21

package/README.md

@@ -5,17 +5,19 @@ current note.
 
 [日本語](./README_ja.md)
 
-## Overview
+## Recommended placement
 
-`backlinksPlugin()` appends a footer list of incoming links to the
-`article.footer` body slot. `getPublishedBacklinks()` resolves the incoming
-links of a note from the content manifest, keeps only publicly discoverable
-notes, and returns them sorted in manifest order.
+`backlinksPlugin()` automatically appends a footer list of incoming links to
+the `article.footer` semantic body slot. The Site owns physical placement: it
+displays the list only where it renders that slot, normally once after article
+content. `getPublishedBacklinks()` resolves the incoming links of a note from
+the content manifest, keeps only publicly discoverable notes, and returns them
+sorted in manifest order.
 
 Without incoming links (or when none of them are published), the component
 renders nothing.
 
-## Usage
+## Quick Start
 
 ```ts
 import { defineConfig } from "@riebeckite/core";
@@ -28,15 +30,20 @@ export default defineConfig({
 ```
 
 `backlinksPlugin()` adds backlinks for every public entry with published
-incoming links and bundles `style.css` into the app stylesheet. Render the
-`article.footer` body slot in the article layout to display the list.
+incoming links and bundles `style.css` into the app stylesheet. Render
+`<ContentSlot slots={bodySlots} name="article.footer" />` once in the article
+layout to display it. The official Starter already renders this slot.
 
-### Custom placement
+## Advanced customization
+
+To choose a different location, prevent the automatic slot contribution with
+`render: false`; this does not change backlink data or its publication
+filtering. Resolve the data in the Site route and render the public component
+exactly once:
 
 ```tsx
 import Backlinks, { getPublishedBacklinks } from "@riebeckite/plugin-backlinks";
-import { config } from "../config";
-import { content } from "../content";
+import { content } from "virtual:riebeckite/content";
 import { getArticleTitle } from "../lib/article-title";
 
 const manifest = await content.getManifest();
@@ -48,12 +55,24 @@ const backlinks = getPublishedBacklinks({
 });
 
 return (
-  <Article
-    footerContent={<Backlinks backlinks={backlinks} />}
-  />
+  <aside><Backlinks backlinks={backlinks} /></aside>
 );
 ```
 
+```ts
+plugins: [backlinksPlugin({ render: false })];
+```
+
+Remove the component to remove manually placed UI. Do not render both this
+component and `article.footer` with automatic rendering enabled, or it will
+appear twice.
+
+## Configuration
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `render` | `boolean` | `true` | Append the generated list to `article.footer`. Set `false` for manual placement. |
+
 ## Component
 
 `Backlinks({ backlinks })` renders a `<footer class="rr-backlinks">` with

package/README_ja.md

@@ -4,11 +4,11 @@
 
 [English](./README.md)
 
-## できること
+## 推奨配置
 
-`backlinksPlugin()` はコンテンツマニフェストから被リンクを集め、公開対象のノートだけをマニフェスト順で `article.footer` body slot に追加します。`Backlinks` コンポーネントはその結果をフッターのリンク一覧として描画します。表示対象がなければ何も出力しません。
+`backlinksPlugin()` はコンテンツマニフェストから被リンクを集め、公開対象のノートだけをマニフェスト順で `article.footer` body slot に自動追加します。物理的な配置は Site が所有し、通常は記事本文の後でこの slot を一度描画します。`Backlinks` コンポーネントはその結果をリンク一覧として描画します。表示対象がなければ何も出力しません。
 
-## 設定と配置
+## クイックスタート
 
 ```ts
 import { defineConfig } from "@riebeckite/core";
@@ -20,11 +20,11 @@ export default defineConfig({
 });
 ```
 
-プラグインは公開済みの被リンクがある記事へ自動的に出力を追加します。記事レイアウトで `article.footer` body slot を描画してください。
+プラグインは公開済みの被リンクがある記事へ自動的に出力を追加します。記事レイアウトで `<ContentSlot slots={bodySlots} name="article.footer" />` を一度描画してください。公式 Starter はこの slot をすでに描画しています。
 
-### 独自の配置
+## 高度なカスタマイズ
 
-Plugin が追加する footer ではなく、アプリ側で表示位置を決める場合は、記事ルートなどでマニフェストを取得し、現在の `slug` に対する被リンクを渡してください。
+アプリ側で表示位置を決める場合は、`render: false` で自動 slot 追加を止めます。データの生成と公開境界のフィルタリングは維持されます。記事ルートなどでマニフェストを取得し、現在の `slug` に対する被リンクを渡してください。
 
 ```tsx
 import Backlinks, { getPublishedBacklinks } from "@riebeckite/plugin-backlinks";
@@ -35,6 +35,18 @@ const items = getPublishedBacklinks({ manifest, config, slug, resolveTitle });
 return <Article footerContent={<Backlinks backlinks={items} />} />;
 ```
 
+```ts
+plugins: [backlinksPlugin({ render: false })];
+```
+
+手動配置を消すにはコンポーネントを消します。自動描画を有効にしたまま同じコンポーネントを描画すると重複します。
+
+## 設定
+
+| オプション | 型 | 既定値 | 説明 |
+| --- | --- | --- | --- |
+| `render` | `boolean` | `true` | `article.footer` への自動追加。手動配置では `false`。 |
+
 ## 公開 API
 
 - `backlinksPlugin()` — プラグインファクトリ

package/dist/components/backlinks.js

@@ -2,7 +2,7 @@
 import { jsx, jsxs } from "hono/jsx/jsx-runtime";
 function Backlinks(props) {
   if (props.backlinks.length === 0) return null;
-  return /* @__PURE__ */ jsxs("footer", { class: "rr-backlinks max-w-4xl mx-auto px-4", children: [
+  return /* @__PURE__ */ jsxs("footer", { class: "rr-backlinks", children: [
     /* @__PURE__ */ jsx("p", { class: "rr-backlinks__eyebrow", children: "Backlinks" }),
     /* @__PURE__ */ jsx("ul", { class: "rr-backlinks__list", children: props.backlinks.map((backlink) => /* @__PURE__ */ jsx("li", { class: "rr-backlinks__item", children: /* @__PURE__ */ jsx("a", { class: "rr-backlinks__link", href: backlink.permalink, children: backlink.title }) }, backlink.slug)) })
   ] });

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { default as Backlinks } from "./components/backlinks.js";
 export type { ArticleBacklink } from "./src/backlinks.js";
 export { getPublishedBacklinks } from "./src/backlinks.server.js";
-export declare function backlinksPlugin(): import("@riebeckite/core").RiebeckitePlugin<unknown>;
+export type BacklinksOptions = {
+    render?: boolean;
+};
+export declare function backlinksPlugin(options?: BacklinksOptions): import("@riebeckite/core").RiebeckitePlugin<BacklinksOptions>;

package/dist/index.js

@@ -1,12 +1,15 @@
 // index.ts
-import { appendContentBodySlot, definePlugin } from "@riebeckite/core";
+import {
+  appendContentBodySlot,
+  definePlugin
+} from "@riebeckite/core";
 import { renderToString } from "hono/jsx/dom/server";
 
 // components/backlinks.tsx
 import { jsx, jsxs } from "hono/jsx/jsx-runtime";
 function Backlinks(props) {
   if (props.backlinks.length === 0) return null;
-  return /* @__PURE__ */ jsxs("footer", { class: "rr-backlinks max-w-4xl mx-auto px-4", children: [
+  return /* @__PURE__ */ jsxs("footer", { class: "rr-backlinks", children: [
     /* @__PURE__ */ jsx("p", { class: "rr-backlinks__eyebrow", children: "Backlinks" }),
     /* @__PURE__ */ jsx("ul", { class: "rr-backlinks__list", children: props.backlinks.map((backlink) => /* @__PURE__ */ jsx("li", { class: "rr-backlinks__item", children: /* @__PURE__ */ jsx("a", { class: "rr-backlinks__link", href: backlink.permalink, children: backlink.title }) }, backlink.slug)) })
   ] });
@@ -31,11 +34,14 @@ function getPublishedBacklinks(args) {
 }
 
 // index.ts
-function backlinksPlugin() {
+function backlinksPlugin(options = {}) {
   return definePlugin({
     name: "backlinks",
     order: 500,
+    options,
+    validateOptions: validateBacklinksOptions,
     onManifestCreated: ({ config, manifest }) => {
+      if (options.render === false) return;
       if (!config) return;
       for (const entry of manifest.discoverableEntries) {
         const backlinks = getPublishedBacklinks({
@@ -61,6 +67,12 @@ function backlinksPlugin() {
     ]
   });
 }
+function validateBacklinksOptions(options) {
+  if (!options || options.render === void 0 || typeof options.render === "boolean") {
+    return [];
+  }
+  return [{ path: "render", message: "Expected a boolean." }];
+}
 function resolveTitle(slug, title) {
   if (typeof title === "string" && title.trim()) return title;
   return slug.split("/").at(-1) ?? slug;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-backlinks",
-  "version": "0.0.20",
+  "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.20"
+    "@riebeckite/core": "0.0.21"
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.20"
+    "@riebeckite/test": "0.0.21"
   },
   "publishConfig": {
     "access": "public"

package/style.css

@@ -1,16 +1,16 @@
 .rr-backlinks {
   margin-block-start: var(--rb-space-6, 3rem);
   padding-top: 1.5rem;
-  border-top: 1px solid color-mix(in srgb, currentColor 16%, transparent);
+  border-top: 1px solid
+    var(--rb-color-border, color-mix(in srgb, currentColor 16%, transparent));
 }
 
 .rr-backlinks__eyebrow {
-  margin: 0 0 0.25rem;
-  font-size: 0.75rem;
+  margin: 0 0 1rem;
+  font-size: 1.125rem;
   font-weight: 700;
-  letter-spacing: 0.12em;
-  text-transform: uppercase;
-  opacity: 0.62;
+  letter-spacing: 0.02em;
+  text-transform: none;
 }
 
 .rr-backlinks__title {
@@ -22,7 +22,7 @@
 .rr-backlinks__list {
   display: grid;
   gap: 0.5rem;
-  margin: 1rem 0 0;
+  margin: 0;
   padding: 0;
   list-style: none;
 }
@@ -33,13 +33,17 @@
 
 .rr-backlinks__link {
   display: block;
-  padding: 0.75rem 0.875rem;
-  border: 1px solid color-mix(in srgb, currentColor 12%, transparent);
-  border-radius: 0.75rem;
-  text-decoration: none;
+  padding: 0.75rem 0;
+  border-bottom: 1px solid
+    var(--rb-color-border, color-mix(in srgb, currentColor 14%, transparent));
+  color: inherit;
+  text-decoration: underline;
+  text-decoration-color: color-mix(in srgb, currentColor 28%, transparent);
+  text-underline-offset: 0.2em;
 }
 
-.rr-backlinks__link:hover {
-  border-color: color-mix(in srgb, currentColor 28%, transparent);
-  background: color-mix(in srgb, currentColor 4%, transparent);
+.rr-backlinks__link:hover,
+.rr-backlinks__link:focus-visible {
+  color: var(--rb-color-accent, currentColor);
+  text-decoration-color: currentColor;
 }