@riebeckite/plugin-breadcrumbs 0.0.11 → 0.0.13

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 +116 -116
  2. package/README_ja.md +117 -117
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,116 +1,116 @@
1
- # @riebeckite/plugin-breadcrumbs
2
-
3
- Build-time breadcrumb navigation derived from the note's slug hierarchy. For
4
- every published entry the plugin inserts a `<nav>` at the top of the rendered
5
- HTML and enriches the page with a hierarchical BreadcrumbList JSON-LD schema.
6
- No client-side JavaScript is required.
7
-
8
- [日本語](./README_ja.md)
9
-
10
- ## Overview
11
-
12
- `breadcrumbs()` reads the entry's slug, splits it into segments, and produces a
13
- trail that always starts at the site home:
14
-
15
- - `Home / folder / sub-folder / Note` for `folder/sub-folder/note`
16
- - `Home / Note` for a note at the site root
17
-
18
- Intermediate segments are resolved against the manifest first: when the folder
19
- has an index note of its own (a note with the folder slug), that note's title
20
- is used for the crumb, otherwise the segment is title-cased. The final crumb is
21
- the note itself and links to its permalink.
22
-
23
- The plugin updates both `entry.html` and the cached `PostContent.html` that the
24
- content route renders, so the nav appears on generated pages and in feeds.
25
-
26
- ## JSON-LD
27
-
28
- `breadcrumbs()` contributes the hierarchical BreadcrumbList as an
29
- `entry.headTags` `<script type="application/ld+json">` so the Site shell can
30
- render it in the document `<head>` (the reference Riebeckite app renders
31
- `entry.headTags` in `_renderer.tsx`). Item URLs are made absolute against the
32
- configured site `baseUrl`.
33
-
34
- When the `seo` plugin is also enabled it emits a two-level BreadcrumbList
35
- (`Home / Note`) inside its own article JSON-LD. The two blocks coexist; to
36
- avoid duplicate BreadcrumbList entities a Site can drop the seo plugin's
37
- placeholder for article pages (shown in the reference app's content route) or
38
- disable `jsonLd` on this plugin (`jsonLd: false`).
39
-
40
- ## Usage
41
-
42
- ```ts
43
- import { defineConfig } from "@riebeckite/core";
44
- import { breadcrumbs } from "@riebeckite/plugin-breadcrumbs";
45
-
46
- export default defineConfig({
47
- // ...
48
- plugins: [breadcrumbs()],
49
- });
50
- ```
51
-
52
- ## Options
53
-
54
- | Option | Type | Default | Description |
55
- | ------ | ---- | ------- | ----------- |
56
- | `homeLabel` | `string` | site title | Home crumb label |
57
- | `className` | `string` | `"rb-breadcrumbs"` | Root CSS class |
58
- | `ariaLabel` | `string` | `"Breadcrumbs"` | Accessible nav name |
59
- | `separator` | `string` | `"/"` | Text between crumbs |
60
- | `jsonLd` | `boolean` | `true` | Emit/replace the BreadcrumbList script |
61
-
62
- ```ts
63
- breadcrumbs({
64
- homeLabel: "Blog",
65
- separator: "›",
66
- });
67
- ```
68
-
69
- ## Output
70
-
71
- ```html
72
- <nav class="rb-breadcrumbs" data-breadcrumbs aria-label="Breadcrumbs">
73
- <ol>
74
- <li class="rb-breadcrumbs__item">
75
- <a class="rb-breadcrumbs__link" href="/">Blog</a>
76
- <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
77
- </li>
78
- <li class="rb-breadcrumbs__item">
79
- <a class="rb-breadcrumbs__link" href="/folder">Folder</a>
80
- <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
81
- </li>
82
- <li class="rb-breadcrumbs__item">
83
- <span class="rb-breadcrumbs__current" aria-current="page">Note</span>
84
- </li>
85
- </ol>
86
- </nav>
87
- ```
88
-
89
- ## Style
90
-
91
- The package ships `style.css`. Register it like any other plugin stylesheet:
92
-
93
- ```ts
94
- import "@riebeckite/plugin-breadcrumbs/style.css";
95
- ```
96
-
97
- ## Exports
98
-
99
- - `breadcrumbs(options?)` — plugin factory
100
- - `breadcrumbsPlugin` — alias of `breadcrumbs`
101
- - `resolveBreadcrumbsOptions(options?)` — apply option defaults
102
- - `buildBreadcrumbItems({ manifest, entry, config, homeLabel })` — build the trail
103
- - `renderBreadcrumbNav(items, options)` — render the navigation HTML
104
- - `buildBreadcrumbJsonLd(config, items)` — build the JSON-LD object
105
- - `injectBreadcrumbNav(html, nav)` / `injectBreadcrumbJsonLd(html, schema)` — HTML injection helpers
106
- - Types: `BreadcrumbsOptions`, `ResolvedBreadcrumbsOptions`, `BreadcrumbItem`
107
-
108
- ## Limitations
109
-
110
- - The trail is fixed at build time. A full rebuild always recomputes correctly.
111
- - Only the slug hierarchy is considered; folder ordering from frontmatter or
112
- series plugins is intentionally ignored.
113
-
114
- ## See also
115
-
116
- - [Plugin guide](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-breadcrumbs
2
+
3
+ Build-time breadcrumb navigation derived from the note's slug hierarchy. For
4
+ every published entry the plugin inserts a `<nav>` at the top of the rendered
5
+ HTML and enriches the page with a hierarchical BreadcrumbList JSON-LD schema.
6
+ No client-side JavaScript is required.
7
+
8
+ [日本語](./README_ja.md)
9
+
10
+ ## Overview
11
+
12
+ `breadcrumbs()` reads the entry's slug, splits it into segments, and produces a
13
+ trail that always starts at the site home:
14
+
15
+ - `Home / folder / sub-folder / Note` for `folder/sub-folder/note`
16
+ - `Home / Note` for a note at the site root
17
+
18
+ Intermediate segments are resolved against the manifest first: when the folder
19
+ has an index note of its own (a note with the folder slug), that note's title
20
+ is used for the crumb, otherwise the segment is title-cased. The final crumb is
21
+ the note itself and links to its permalink.
22
+
23
+ The plugin updates both `entry.html` and the cached `PostContent.html` that the
24
+ content route renders, so the nav appears on generated pages and in feeds.
25
+
26
+ ## JSON-LD
27
+
28
+ `breadcrumbs()` contributes the hierarchical BreadcrumbList as an
29
+ `entry.headTags` `<script type="application/ld+json">` so the Site shell can
30
+ render it in the document `<head>` (the reference Riebeckite app renders
31
+ `entry.headTags` in `_renderer.tsx`). Item URLs are made absolute against the
32
+ configured site `baseUrl`.
33
+
34
+ When the `seo` plugin is also enabled it emits a two-level BreadcrumbList
35
+ (`Home / Note`) inside its own article JSON-LD. The two blocks coexist; to
36
+ avoid duplicate BreadcrumbList entities a Site can drop the seo plugin's
37
+ placeholder for article pages (shown in the reference app's content route) or
38
+ disable `jsonLd` on this plugin (`jsonLd: false`).
39
+
40
+ ## Usage
41
+
42
+ ```ts
43
+ import { defineConfig } from "@riebeckite/core";
44
+ import { breadcrumbs } from "@riebeckite/plugin-breadcrumbs";
45
+
46
+ export default defineConfig({
47
+ // ...
48
+ plugins: [breadcrumbs()],
49
+ });
50
+ ```
51
+
52
+ ## Options
53
+
54
+ | Option | Type | Default | Description |
55
+ | ------ | ---- | ------- | ----------- |
56
+ | `homeLabel` | `string` | site title | Home crumb label |
57
+ | `className` | `string` | `"rb-breadcrumbs"` | Root CSS class |
58
+ | `ariaLabel` | `string` | `"Breadcrumbs"` | Accessible nav name |
59
+ | `separator` | `string` | `"/"` | Text between crumbs |
60
+ | `jsonLd` | `boolean` | `true` | Emit/replace the BreadcrumbList script |
61
+
62
+ ```ts
63
+ breadcrumbs({
64
+ homeLabel: "Blog",
65
+ separator: "›",
66
+ });
67
+ ```
68
+
69
+ ## Output
70
+
71
+ ```html
72
+ <nav class="rb-breadcrumbs" data-breadcrumbs aria-label="Breadcrumbs">
73
+ <ol>
74
+ <li class="rb-breadcrumbs__item">
75
+ <a class="rb-breadcrumbs__link" href="/">Blog</a>
76
+ <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
77
+ </li>
78
+ <li class="rb-breadcrumbs__item">
79
+ <a class="rb-breadcrumbs__link" href="/folder">Folder</a>
80
+ <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
81
+ </li>
82
+ <li class="rb-breadcrumbs__item">
83
+ <span class="rb-breadcrumbs__current" aria-current="page">Note</span>
84
+ </li>
85
+ </ol>
86
+ </nav>
87
+ ```
88
+
89
+ ## Style
90
+
91
+ The package ships `style.css`. Register it like any other plugin stylesheet:
92
+
93
+ ```ts
94
+ import "@riebeckite/plugin-breadcrumbs/style.css";
95
+ ```
96
+
97
+ ## Exports
98
+
99
+ - `breadcrumbs(options?)` — plugin factory
100
+ - `breadcrumbsPlugin` — alias of `breadcrumbs`
101
+ - `resolveBreadcrumbsOptions(options?)` — apply option defaults
102
+ - `buildBreadcrumbItems({ manifest, entry, config, homeLabel })` — build the trail
103
+ - `renderBreadcrumbNav(items, options)` — render the navigation HTML
104
+ - `buildBreadcrumbJsonLd(config, items)` — build the JSON-LD object
105
+ - `injectBreadcrumbNav(html, nav)` / `injectBreadcrumbJsonLd(html, schema)` — HTML injection helpers
106
+ - Types: `BreadcrumbsOptions`, `ResolvedBreadcrumbsOptions`, `BreadcrumbItem`
107
+
108
+ ## Limitations
109
+
110
+ - The trail is fixed at build time. A full rebuild always recomputes correctly.
111
+ - Only the slug hierarchy is considered; folder ordering from frontmatter or
112
+ series plugins is intentionally ignored.
113
+
114
+ ## See also
115
+
116
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,117 +1,117 @@
1
- # @riebeckite/plugin-breadcrumbs
2
-
3
- ノートのスラッグ階層からパンくずナビゲーションをビルド時に生成する
4
- プラグインです。公開対象の各エントリについて、記事上部に `<nav>` を挿入し、
5
- 階層構造を反映した BreadcrumbList の JSON-LD も出力します。クライアント側
6
- JavaScript は不要です。
7
-
8
- [English](./README.md)
9
-
10
- ## 仕組み
11
-
12
- `breadcrumbs()` はエントリのスラッグを「/」で区切り、必ずサイトのホームから
13
- 始まるパンくず列を作ります。
14
-
15
- - `folder/sub-folder/note` の場合: `ホーム / folder / sub-folder / note`
16
- - サイト直下のノートの場合: `ホーム / note`
17
-
18
- 途中のフォルダはマニフェストと突き合わせて解決します。フォルダ自身に
19
- インデックスノート（フォルダと同名のスラッグを持つノート）があればその
20
- タイトルを使い、なければセグメントをタイトルケース（先頭大文字）にして
21
- 代用します。最後のパンくずはそのノート自身で、パーマリンクへリンクします。
22
-
23
- `entry.html` と、コンテンツルートが描画するキャッシュ済みの
24
- `PostContent.html` の両方を更新するため、生成ページとフィードの両方に
25
- ナビゲーションが反映されます。
26
-
27
- ## JSON-LD
28
-
29
- `breadcrumbs()` は階層的な BreadcrumbList を `entry.headTags` の
30
- `<script type="application/ld+json">` として提供します。Site シェルがこれを
31
- 文書の `<head>` に描画します（リファレンスアプリの `_renderer.tsx` は
32
- `entry.headTags` を描画します）。アイテムの URL は設定の `baseUrl` に基づき
33
- 絶対 URL に変換されます。
34
-
35
- `seo` プラグインも有効な場合、seo 側の記事 JSON-LD に 2 階層の
36
- BreadcrumbList（`ホーム / ノート`）が含まれます。この 2 つは共存するため、
37
- BreadcrumbList の重複を避けたい Site は記事ページで seo の暫定版を除去して
38
- ください（リファレンスアプリのコンテンツルートで実施例を確認できます）。
39
- 無効にする場合は本プラグインの `jsonLd: false` も利用できます。
40
-
41
- ## 使い方
42
-
43
- ```ts
44
- import { defineConfig } from "@riebeckite/core";
45
- import { breadcrumbs } from "@riebeckite/plugin-breadcrumbs";
46
-
47
- export default defineConfig({
48
- // ...
49
- plugins: [breadcrumbs()],
50
- });
51
- ```
52
-
53
- ## オプション
54
-
55
- | オプション | 型 | 既定値 | 説明 |
56
- | ---------- | -- | ------ | ---- |
57
- | `homeLabel` | `string` | サイトタイトル | ホームのパンくずラベル |
58
- | `className` | `string` | `"rb-breadcrumbs"` | ルート要素の CSS クラス |
59
- | `ariaLabel` | `string` | `"Breadcrumbs"` | ナビゲーションのアクセシブル名 |
60
- | `separator` | `string` | `"/"` | パンくず間の文字 |
61
- | `jsonLd` | `boolean` | `true` | BreadcrumbList スクリプトを出力・置換する |
62
-
63
- ```ts
64
- breadcrumbs({
65
- homeLabel: "ブログ",
66
- separator: "›",
67
- });
68
- ```
69
-
70
- ## 出力
71
-
72
- ```html
73
- <nav class="rb-breadcrumbs" data-breadcrumbs aria-label="Breadcrumbs">
74
- <ol>
75
- <li class="rb-breadcrumbs__item">
76
- <a class="rb-breadcrumbs__link" href="/">ブログ</a>
77
- <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
78
- </li>
79
- <li class="rb-breadcrumbs__item">
80
- <a class="rb-breadcrumbs__link" href="/folder">フォルダ</a>
81
- <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
82
- </li>
83
- <li class="rb-breadcrumbs__item">
84
- <span class="rb-breadcrumbs__current" aria-current="page">ノート</span>
85
- </li>
86
- </ol>
87
- </nav>
88
- ```
89
-
90
- ## スタイル
91
-
92
- パッケージに `style.css` が含まれます。他のプラグインと同じように読み込みます。
93
-
94
- ```ts
95
- import "@riebeckite/plugin-breadcrumbs/style.css";
96
- ```
97
-
98
- ## エクスポート
99
-
100
- - `breadcrumbs(options?)` — プラグインファクトリ
101
- - `breadcrumbsPlugin` — `breadcrumbs` のエイリアス
102
- - `resolveBreadcrumbsOptions(options?)` — オプションの既定値を適用する
103
- - `buildBreadcrumbItems({ manifest, entry, config, homeLabel })` — パンくず列を組み立てる
104
- - `renderBreadcrumbNav(items, options)` — ナビゲーション HTML を生成する
105
- - `buildBreadcrumbJsonLd(config, items)` — JSON-LD オブジェクトを生成する
106
- - `injectBreadcrumbNav(html, nav)` / `injectBreadcrumbJsonLd(html, schema)` — HTML 注入ヘルパー
107
- - 型: `BreadcrumbsOptions`, `ResolvedBreadcrumbsOptions`, `BreadcrumbItem`
108
-
109
- ## 制約
110
-
111
- - パンくず列はビルド時に確定します。再ビルドすれば常に正しく再計算されます。
112
- - スラッグ階層のみを参照します。frontmatter の並び順や series プラグインの
113
- 順序は意図的に考慮しません。
114
-
115
- ## ????
116
-
117
- - [?????????](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-breadcrumbs
2
+
3
+ ノートのスラッグ階層からパンくずナビゲーションをビルド時に生成する
4
+ プラグインです。公開対象の各エントリについて、記事上部に `<nav>` を挿入し、
5
+ 階層構造を反映した BreadcrumbList の JSON-LD も出力します。クライアント側
6
+ JavaScript は不要です。
7
+
8
+ [English](./README.md)
9
+
10
+ ## 仕組み
11
+
12
+ `breadcrumbs()` はエントリのスラッグを「/」で区切り、必ずサイトのホームから
13
+ 始まるパンくず列を作ります。
14
+
15
+ - `folder/sub-folder/note` の場合: `ホーム / folder / sub-folder / note`
16
+ - サイト直下のノートの場合: `ホーム / note`
17
+
18
+ 途中のフォルダはマニフェストと突き合わせて解決します。フォルダ自身に
19
+ インデックスノート（フォルダと同名のスラッグを持つノート）があればその
20
+ タイトルを使い、なければセグメントをタイトルケース（先頭大文字）にして
21
+ 代用します。最後のパンくずはそのノート自身で、パーマリンクへリンクします。
22
+
23
+ `entry.html` と、コンテンツルートが描画するキャッシュ済みの
24
+ `PostContent.html` の両方を更新するため、生成ページとフィードの両方に
25
+ ナビゲーションが反映されます。
26
+
27
+ ## JSON-LD
28
+
29
+ `breadcrumbs()` は階層的な BreadcrumbList を `entry.headTags` の
30
+ `<script type="application/ld+json">` として提供します。Site シェルがこれを
31
+ 文書の `<head>` に描画します（リファレンスアプリの `_renderer.tsx` は
32
+ `entry.headTags` を描画します）。アイテムの URL は設定の `baseUrl` に基づき
33
+ 絶対 URL に変換されます。
34
+
35
+ `seo` プラグインも有効な場合、seo 側の記事 JSON-LD に 2 階層の
36
+ BreadcrumbList（`ホーム / ノート`）が含まれます。この 2 つは共存するため、
37
+ BreadcrumbList の重複を避けたい Site は記事ページで seo の暫定版を除去して
38
+ ください（リファレンスアプリのコンテンツルートで実施例を確認できます）。
39
+ 無効にする場合は本プラグインの `jsonLd: false` も利用できます。
40
+
41
+ ## 使い方
42
+
43
+ ```ts
44
+ import { defineConfig } from "@riebeckite/core";
45
+ import { breadcrumbs } from "@riebeckite/plugin-breadcrumbs";
46
+
47
+ export default defineConfig({
48
+ // ...
49
+ plugins: [breadcrumbs()],
50
+ });
51
+ ```
52
+
53
+ ## オプション
54
+
55
+ | オプション | 型 | 既定値 | 説明 |
56
+ | ---------- | -- | ------ | ---- |
57
+ | `homeLabel` | `string` | サイトタイトル | ホームのパンくずラベル |
58
+ | `className` | `string` | `"rb-breadcrumbs"` | ルート要素の CSS クラス |
59
+ | `ariaLabel` | `string` | `"Breadcrumbs"` | ナビゲーションのアクセシブル名 |
60
+ | `separator` | `string` | `"/"` | パンくず間の文字 |
61
+ | `jsonLd` | `boolean` | `true` | BreadcrumbList スクリプトを出力・置換する |
62
+
63
+ ```ts
64
+ breadcrumbs({
65
+ homeLabel: "ブログ",
66
+ separator: "›",
67
+ });
68
+ ```
69
+
70
+ ## 出力
71
+
72
+ ```html
73
+ <nav class="rb-breadcrumbs" data-breadcrumbs aria-label="Breadcrumbs">
74
+ <ol>
75
+ <li class="rb-breadcrumbs__item">
76
+ <a class="rb-breadcrumbs__link" href="/">ブログ</a>
77
+ <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
78
+ </li>
79
+ <li class="rb-breadcrumbs__item">
80
+ <a class="rb-breadcrumbs__link" href="/folder">フォルダ</a>
81
+ <span class="rb-breadcrumbs__separator" aria-hidden="true">/</span>
82
+ </li>
83
+ <li class="rb-breadcrumbs__item">
84
+ <span class="rb-breadcrumbs__current" aria-current="page">ノート</span>
85
+ </li>
86
+ </ol>
87
+ </nav>
88
+ ```
89
+
90
+ ## スタイル
91
+
92
+ パッケージに `style.css` が含まれます。他のプラグインと同じように読み込みます。
93
+
94
+ ```ts
95
+ import "@riebeckite/plugin-breadcrumbs/style.css";
96
+ ```
97
+
98
+ ## エクスポート
99
+
100
+ - `breadcrumbs(options?)` — プラグインファクトリ
101
+ - `breadcrumbsPlugin` — `breadcrumbs` のエイリアス
102
+ - `resolveBreadcrumbsOptions(options?)` — オプションの既定値を適用する
103
+ - `buildBreadcrumbItems({ manifest, entry, config, homeLabel })` — パンくず列を組み立てる
104
+ - `renderBreadcrumbNav(items, options)` — ナビゲーション HTML を生成する
105
+ - `buildBreadcrumbJsonLd(config, items)` — JSON-LD オブジェクトを生成する
106
+ - `injectBreadcrumbNav(html, nav)` / `injectBreadcrumbJsonLd(html, schema)` — HTML 注入ヘルパー
107
+ - 型: `BreadcrumbsOptions`, `ResolvedBreadcrumbsOptions`, `BreadcrumbItem`
108
+
109
+ ## 制約
110
+
111
+ - パンくず列はビルド時に確定します。再ビルドすれば常に正しく再計算されます。
112
+ - スラッグ階層のみを参照します。frontmatter の並び順や series プラグインの
113
+ 順序は意図的に考慮しません。
114
+
115
+ ## ????
116
+
117
+ - [?????????](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-breadcrumbs",
3
- "version": "0.0.11",
3
+ "version": "0.0.13",
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.11"
18
+ "@riebeckite/core": "0.0.13"
19
19
  },
20
20
  "devDependencies": {
21
21
  "tsx": "^4.22.4",
22
- "@riebeckite/test": "0.0.11"
22
+ "@riebeckite/test": "0.0.13"
23
23
  },
24
24
  "publishConfig": {
25
25
  "access": "public"