@riebeckite/plugin-series 0.0.16 → 0.0.17

package/README.md

@@ -14,6 +14,10 @@ to each note in the series. Links use the permalinks resolved by Core, so
 plugins such as `permalink` are respected. A single-note series renders no
 navigation block.
 
+The plugin also declares page types, so it exposes a list page at `/series`
+and one landing page per series at `/series/<name>`. Both are built from the
+discoverable manifest, so unlisted, draft, and scheduled notes never appear.
+
 The plugin is build-time only: it ships a stylesheet asset and no client
 runtime.
 
@@ -59,6 +63,7 @@ the numbered parts, using `date`/`created`/`published`, then `title`, then
 | `heading` | `boolean` | `true` | Render the series heading above the list. |
 | `className` | `string` | `"rb-series"` | Base CSS class for generated markup. |
 | `positionLabel` | `boolean` | `false` | Add a `Part N of M` label for the current note. |
+| `basePath` | `string` | `"/series"` | Base path for the generated pages. An empty string disables them. |
 
 ## Output
 
@@ -91,6 +96,20 @@ All text and attributes are escaped. The injected HTML is written back to both
 the manifest entry and the processed content object so the page route, feeds,
 and search see the same markup.
 
+## Page types
+
+The plugin registers two page types. Both derive their output from
+`manifest.discoverableEntries`, so non-public notes are excluded.
+
+| Page type | Path | Output |
+| --------- | ---- | ------ |
+| `series-list` | `<basePath>` (`/series`) | `<section class="rb-series rb-series--list">` listing each series with a link to its landing page. Generated only when at least one series exists. |
+| `series-index` | `<basePath>/<name>` (`/series/<name>`) | The `renderSeriesIndex()` section for one series, in the existing order. |
+
+The `<name>` segment is a lowercase, hyphenated slug; non-ASCII names fall back
+to percent-encoding. Set `basePath` to match a custom routing scheme, or pass
+`basePath: ""` to disable the pages and render them yourself.
+
 ## Exports
 
 - `series(options?)` / `seriesPlugin(options?)` — plugin factory
@@ -98,14 +117,23 @@ and search see the same markup.
   (`SeriesIndex | null`); useful for landing pages
 - `renderSeriesIndex(manifest, name, options?)` — standalone `<section>` block
   for a whole series
+- `renderSeriesList(manifest, options?, label?)` — standalone `<section>` block
+  listing every series; returns `""` when there are none
+- `seriesLandingPath(name, options?)` — landing path for a series, or `""` when
+  the pages are disabled
+- `seriesSlug(name)` — URL segment used by a series landing page
 - `renderSeriesNavigation(index, currentSlug, options?)` — a single navigation
   block
 - `collectSeriesIndexes(manifest, options?)` — every series in first-seen order
 - `resolveSeriesOptions(options?)` — options with defaults applied
+- `DEFAULT_SERIES_BASE_PATH` — default `basePath` (`"/series"`)
 - Types: `SeriesOptions`, `ResolvedSeriesOptions`, `SeriesMember`, `SeriesIndex`
 
 ### Series landing page
 
+The plugin generates these pages automatically. To render them yourself, or to
+reuse the markup elsewhere, combine the exported helpers:
+
 ```ts
 import { buildSeriesIndex, renderSeriesIndex } from "@riebeckite/plugin-series";
 
@@ -134,10 +162,12 @@ matched with `.rb-series__item a[aria-current="page"]`.
 ## Limitations
 
 - A note belongs to exactly one series.
-- A series of one note produces no navigation block.
+- A series of one note produces no navigation block on the note, but it still
+  gets a list entry and a landing page.
 - `series_order` must be a finite number; numeric strings are not coerced.
-- The plugin does not generate routes for series; combine
-  `renderSeriesIndex()` with your own page to build a series landing page.
+- Series names that slugify to the same segment share the first landing page.
+- Generated pages use `/series` by default; change `basePath` to avoid clashes
+  with existing routes.
 
 ## See also
 

package/README_ja.md

@@ -8,6 +8,8 @@
 
 `series()` は frontmatter からシリーズ情報を読み取り、該当するノートをグループ化して並べ替えたうえで、各ノートの HTML に `<nav class="rb-series">` ブロックを追加します。リンクには Core が解決したパーマリンクを使うため、`permalink` プラグインなどとも併用できます。1 件だけのシリーズにはナビゲーションを出力しません。
 
+また page type を登録し、一覧ページを `/series`、シリーズごとのランディングページを `/series/<name>` に生成します。どちらも公開対象（discoverable）の manifest から組み立てるため、非公開・下書き・予約投稿のノートは現れません。
+
 このプラグインはビルド時のみ動作し、クライアント用のランタイムは持ちません（スタイルシートのみを登録します）。
 
 ## 設定する
@@ -50,6 +52,7 @@ series_order: 2
 | `heading` | `boolean` | `true` | リストの上に見出しを表示する。 |
 | `className` | `string` | `"rb-series"` | 生成する HTML の基準クラス名。 |
 | `positionLabel` | `boolean` | `false` | 現在の記事に「Part N of M」を付ける。 |
+| `basePath` | `string` | `"/series"` | 生成するページの基準パス。空文字にすると生成しない。 |
 
 ## 出力
 
@@ -79,18 +82,36 @@ series_order: 2
 
 テキストと属性はすべてエスケープします。生成した HTML は manifest の entry と処理済みコンテンツの両方へ書き戻すため、ページのルート表示・フィード・検索でも同じマークアップになります。
 
+## ページタイプ
+
+プラグインは 2 つの page type を登録します。どちらも `manifest.discoverableEntries` から組み立てるため、非公開のノートは含まれません。
+
+| page type | パス | 出力 |
+| --------- | ---- | ---- |
+| `series-list` | `<basePath>`（`/series`） | 各シリーズをランディングページへのリンク付きで並べた `<section class="rb-series rb-series--list">`。シリーズが 1 つ以上あるときだけ生成。 |
+| `series-index` | `<basePath>/<name>`（`/series/<name>`） | 1 つのシリーズの `renderSeriesIndex()` セクション。既存の並び順をそのまま使う。 |
+
+`<name>` は小文字化・ハイフン化したスラッグです。ASCII 以外の名前はパーセントエンコードにフォールバックします。`basePath` をカスタムルーティングに合わせて変更でき、`basePath: ""` で生成を止めて自前で描画できます。
+
 ## 公開 API
 
 - `series(options?)` / `seriesPlugin(options?)` — プラグインファクトリ
 - `buildSeriesIndex(manifest, name, options?)` — 1 つのシリーズの並び順付きメンバー（`SeriesIndex | null`）。ランディングページ向け
 - `renderSeriesIndex(manifest, name, options?)` — シリーズ全体の `<section>` ブロック
+- `renderSeriesList(manifest, options?, label?)` — 全シリーズを並べた `<section>` ブロック。無ければ `""`
+- `seriesLandingPath(name, options?)` — シリーズのランディングパス。生成無効時は `""`
+- `seriesSlug(name)` — ランディングページの URL セグメント
 - `renderSeriesNavigation(index, currentSlug, options?)` — ナビゲーション 1 つ分
 - `collectSeriesIndexes(manifest, options?)` — 全シリーズを出現順で取得
 - `resolveSeriesOptions(options?)` — 既定値を適用したオプション
+- `DEFAULT_SERIES_BASE_PATH` — 既定の `basePath`（`"/series"`）
 - 型: `SeriesOptions`, `ResolvedSeriesOptions`, `SeriesMember`, `SeriesIndex`
 
 ### シリーズのランディングページ
 
+これらのページはプラグインが自動生成します。自前で描画したい場合や別の場所で
+マークアップを再利用したい場合は、公開ヘルパーを組み合わせます。
+
 ```ts
 import { buildSeriesIndex, renderSeriesIndex } from "@riebeckite/plugin-series";
 
@@ -116,9 +137,10 @@ const html = renderSeriesIndex(manifest, "何かを作る");
 ## 制限
 
 - 1 つのノートが所属できるシリーズは 1 つだけです。
-- 1 件だけのシリーズにはナビゲーションを出力しません。
+- 1 件だけのシリーズにはナビゲーションを出力しませんが、一覧の項目とランディングページは生成します。
 - `series_order` は有限の数値である必要があります。数値文字列は変換しません。
-- シリーズ用のルートは生成しません。ランディングページを作る場合は `renderSeriesIndex()` を自前のページと組み合わせてください。
+- スラッグが同じになるシリーズ名は、最初のランディングページを共有します。
+- 生成ページは既定で `/series` を使います。既存ルートと衝突する場合は `basePath` を変更してください。
 
 ## 関連
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { resolveSeriesOptions } from "./src/series.js";
 import type { SeriesOptions } from "./src/types.js";
-export { buildSeriesIndex, collectSeriesIndexes, renderSeriesIndex, renderSeriesNavigation, } from "./src/series.js";
+export { buildSeriesIndex, collectSeriesIndexes, DEFAULT_SERIES_BASE_PATH, renderSeriesIndex, renderSeriesList, renderSeriesNavigation, seriesLandingPath, seriesSlug, } from "./src/series.js";
 export type { ResolvedSeriesOptions, SeriesIndex, SeriesMember, SeriesOptions, } from "./src/types.js";
 /**
  * Series (ordered multi-part posts) for Riebeckite.

package/dist/index.js

@@ -1,5 +1,6 @@
 // index.ts
 import {
+  appendContentBodySlot,
   createStyleAsset,
   definePlugin
 } from "@riebeckite/core";
@@ -10,6 +11,7 @@ import {
   escapeHtmlAttribute
 } from "@riebeckite/core";
 var DEFAULT_SERIES_CLASS_NAME = "rb-series";
+var DEFAULT_SERIES_BASE_PATH = "/series";
 function resolveSeriesOptions(options = {}) {
   return {
     key: options.key ?? "series",
@@ -17,7 +19,8 @@ function resolveSeriesOptions(options = {}) {
     titleKey: options.titleKey ?? "series_title",
     heading: options.heading ?? true,
     className: options.className ?? DEFAULT_SERIES_CLASS_NAME,
-    positionLabel: options.positionLabel ?? false
+    positionLabel: options.positionLabel ?? false,
+    basePath: normalizeBasePath(options.basePath ?? DEFAULT_SERIES_BASE_PATH)
   };
 }
 function collectSeriesIndexes(manifest, options = {}) {
@@ -47,6 +50,18 @@ function buildSeriesIndex(manifest, name, options = {}) {
     (index) => index.name === name
   ) ?? null;
 }
+function seriesSlug(name) {
+  return name.split("/").map((segment) => {
+    const normalized = segment.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return normalized === "" ? encodeURIComponent(segment.trim()) : normalized;
+  }).join("/");
+}
+function seriesLandingPath(name, options = {}) {
+  const resolved = resolveSeriesOptions(options);
+  if (resolved.basePath === "") return "";
+  const slug = seriesSlug(name);
+  return slug === "" ? "" : `${resolved.basePath}/${slug}`;
+}
 function renderSeriesNavigation(index, currentSlug, options = {}) {
   const resolved = resolveSeriesOptions(options);
   const cls = resolved.className;
@@ -143,6 +158,21 @@ function renderSeriesIndex(manifest, name, options = {}) {
   parts.push("</ol></section>");
   return parts.join("");
 }
+function renderSeriesList(manifest, options = {}, label = "Series") {
+  const indexes = collectSeriesIndexes(manifest, options);
+  if (indexes.length === 0) return "";
+  const resolved = resolveSeriesOptions(options);
+  const cls = escapeHtmlAttribute(resolved.className);
+  const items = indexes.map((index) => {
+    const path = seriesLandingPath(index.name, options);
+    const title = escapeHtml(index.title);
+    const link = path === "" ? `<span class="${cls}__link">${title}</span>` : `<a class="${cls}__link" href="${escapeHtmlAttribute(path)}">${title}</a>`;
+    return `<li class="${cls}__item" data-series-count="${index.members.length}">${link}</li>`;
+  }).join("");
+  return `<section class="${cls} ${cls}--list" data-series-list><h1 class="${cls}__title">${escapeHtml(
+    label
+  )}</h1><ol class="${cls}__list">${items}</ol></section>`;
+}
 function collectSeriesDiagnostics(manifest, options = {}) {
   const resolved = resolveSeriesOptions(options);
   const diagnostics = [];
@@ -247,9 +277,44 @@ function hasFrontmatterKey(entry, key) {
 function formatPosition(position, total) {
   return `Part ${position} of ${total}`;
 }
+function normalizeBasePath(value) {
+  const trimmed = value.trim();
+  if (trimmed === "") return "";
+  const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : prefixed;
+}
 
 // index.ts
 function series(options = {}) {
+  const models = /* @__PURE__ */ new WeakMap();
+  const modelFor = (manifest) => {
+    const cached = models.get(manifest);
+    if (cached) return cached;
+    const resolved = resolveSeriesOptions(options);
+    const view = {
+      ...manifest,
+      entries: manifest.discoverableEntries
+    };
+    const byPath = /* @__PURE__ */ new Map();
+    const landingPaths = [];
+    if (resolved.basePath !== "") {
+      for (const index of collectSeriesIndexes(view, options)) {
+        const path = seriesLandingPath(index.name, options);
+        if (path === "" || byPath.has(path)) continue;
+        byPath.set(path, index);
+        landingPaths.push(path);
+      }
+    }
+    const model = {
+      resolved,
+      view,
+      listPath: resolved.basePath !== "" && landingPaths.length > 0 ? resolved.basePath : "",
+      landingPaths,
+      byPath
+    };
+    models.set(manifest, model);
+    return model;
+  };
   return definePlugin({
     name: "series",
     processedContentCache: {
@@ -261,12 +326,13 @@ function series(options = {}) {
     validateOptions: validateSeriesOptions,
     onManifestCreated: ({ manifest, diagnostics }) => {
       diagnostics.push(...collectSeriesDiagnostics(manifest, options));
+      const view = modelFor(manifest).view;
       const injected = /* @__PURE__ */ new Set();
-      for (const index of collectSeriesIndexes(manifest, options)) {
+      for (const index of collectSeriesIndexes(view, options)) {
         if (index.members.length < 2) continue;
         for (const member of index.members) {
           if (injected.has(member.slug)) continue;
-          const entry = manifest.bySlug.get(member.slug);
+          const entry = view.bySlug.get(member.slug);
           if (!entry) continue;
           injected.add(member.slug);
           const navigation = renderSeriesNavigation(
@@ -274,21 +340,73 @@ function series(options = {}) {
             member.slug,
             options
           );
-          if (!entry.html.includes(navigation)) {
-            entry.html = `${entry.html}
-${navigation}`;
+          if (!hasSlotFragment(entry.bodySlots?.["article.footer"], navigation)) {
+            appendContentBodySlot(entry, "article.footer", navigation);
           }
         }
       }
     },
+    pageTypes: [
+      {
+        id: "series-list",
+        paths: ({ manifest }) => {
+          const listPath = modelFor(manifest).listPath;
+          return listPath === "" ? [] : [listPath];
+        },
+        outputDependencies: [{ type: "global" }],
+        resolve: ({ manifest, pathname }) => {
+          const model = modelFor(manifest);
+          if (model.listPath === "" || pathname !== model.listPath) return null;
+          const body = renderSeriesList(model.view, options);
+          if (body === "") return null;
+          return {
+            type: "series-list",
+            pathname,
+            title: "Series",
+            body
+          };
+        }
+      },
+      {
+        id: "series-index",
+        paths: ({ manifest }) => modelFor(manifest).landingPaths,
+        outputDependencies: [{ type: "global" }],
+        resolve: ({ manifest, pathname }) => {
+          const model = modelFor(manifest);
+          const index = model.byPath.get(pathname);
+          if (!index) return null;
+          const body = renderSeriesIndex(model.view, index.name, options);
+          if (body === "") return null;
+          return {
+            type: "series-index",
+            pathname,
+            title: index.title,
+            body
+          };
+        }
+      }
+    ],
     assets: [createStyleAsset("series")]
   });
 }
 var seriesPlugin = series;
+function hasSlotFragment(slot, fragment) {
+  return slot === fragment || slot?.startsWith(`${fragment}
+`) || slot?.endsWith(`
+${fragment}`) || slot?.includes(`
+${fragment}
+`) || false;
+}
 function validateSeriesOptions(options) {
   if (!options) return [];
   const issues = [];
-  for (const key of ["key", "orderKey", "titleKey", "className"]) {
+  for (const key of [
+    "key",
+    "orderKey",
+    "titleKey",
+    "className",
+    "basePath"
+  ]) {
     const value = options[key];
     if (value !== void 0 && (typeof value !== "string" || value.trim() === "")) {
       issues.push({ path: key, message: "Expected a non-empty string." });
@@ -304,11 +422,15 @@ function validateSeriesOptions(options) {
 var DEFAULT_CLASS_NAME = resolveSeriesOptions({}).className;
 export {
   DEFAULT_CLASS_NAME,
+  DEFAULT_SERIES_BASE_PATH,
   buildSeriesIndex,
   collectSeriesIndexes,
   renderSeriesIndex,
+  renderSeriesList,
   renderSeriesNavigation,
   resolveSeriesOptions,
   series,
-  seriesPlugin
+  seriesLandingPath,
+  seriesPlugin,
+  seriesSlug
 };

package/dist/src/series.d.ts

@@ -2,6 +2,7 @@ import { type ContentManifest, type Diagnostic } from "@riebeckite/core";
 import type { ResolvedSeriesOptions, SeriesIndex, SeriesOptions } from "./types.js";
 /** Base class applied when `options.className` is not set. */
 export declare const DEFAULT_SERIES_CLASS_NAME = "rb-series";
+export declare const DEFAULT_SERIES_BASE_PATH = "/series";
 /** Applies defaults to the user-supplied options. */
 export declare function resolveSeriesOptions(options?: SeriesOptions): ResolvedSeriesOptions;
 /**
@@ -13,6 +14,8 @@ export declare function resolveSeriesOptions(options?: SeriesOptions): ResolvedS
 export declare function collectSeriesIndexes(manifest: ContentManifest, options?: SeriesOptions): SeriesIndex[];
 /** Returns a single series index, or `null` when no note declares `name`. */
 export declare function buildSeriesIndex(manifest: ContentManifest, name: string, options?: SeriesOptions): SeriesIndex | null;
+export declare function seriesSlug(name: string): string;
+export declare function seriesLandingPath(name: string, options?: SeriesOptions): string;
 /**
  * Renders the navigation block that is appended to each note in a series.
  * `currentSlug` marks the active part with `aria-current="page"` and drives the
@@ -24,6 +27,7 @@ export declare function renderSeriesNavigation(index: SeriesIndex, currentSlug:
  * Returns an empty string when the manifest has no member for `name`.
  */
 export declare function renderSeriesIndex(manifest: ContentManifest, name: string, options?: SeriesOptions): string;
+export declare function renderSeriesList(manifest: ContentManifest, options?: SeriesOptions, label?: string): string;
 /**
  * Reports notes whose series metadata cannot be ordered reliably. Emitted
  * diagnostics use `pluginName: "series"` and `severity: "warning"`.

package/dist/src/types.d.ts

@@ -12,6 +12,7 @@ export type SeriesOptions = {
     className?: string;
     /** Render a `Part N of M` label for the current note. Defaults to `false`. */
     positionLabel?: boolean;
+    basePath?: string;
 };
 /** Options after defaults have been applied. */
 export type ResolvedSeriesOptions = {
@@ -21,6 +22,7 @@ export type ResolvedSeriesOptions = {
     heading: boolean;
     className: string;
     positionLabel: boolean;
+    basePath: string;
 };
 /** A single note that belongs to a series. */
 export type SeriesMember = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-series",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,11 +15,11 @@
     "./style.css": "./style.css"
   },
   "dependencies": {
-    "@riebeckite/core": "0.0.16"
+    "@riebeckite/core": "0.0.17"
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.16"
+    "@riebeckite/test": "0.0.17"
   },
   "publishConfig": {
     "access": "public"