@tenjuu99/blog 0.3.3 → 0.3.5

package/docs/develop.md

@@ -452,8 +452,17 @@ npm run dev
 
 ### 4. フロントマターパーサー
 
-- YAML完全互換ではなく独自実装（lib/pageData.js:61-93）
-- 配列・オブジェクトはJSON形式必須
+- YAML完全互換ではなく独自実装（`parseMetaData()` in lib/pageData.js）
+- 配列はJSON形式（`["item1"]`）またはYAMLリスト形式（`- item`）で記述可能
+- オブジェクトはJSON形式必須
+
+### 5. helper.js の top-level await 禁止
+
+`lib/helper.js` では top-level await を使用してはならない。
+
+**理由:** `.cache/helper/` 以下のヘルパーファイルが `replaceVariablesFilter.js` を静的 import し、そこから `helper.js` が再度 import される循環依存がある。top-level await があると ESM のモジュール評価が完了前に循環参照が解決されずデッドロックが発生する。
+
+**対処:** IIFE `(async () => { ... })()` の中で await し、その Promise を `helperReady` としてエクスポートする（lib/helper.js 参照）。
 
 ## テストについて
 
@@ -490,7 +499,7 @@ test('テストの説明', () => {
 
 - ES Modules使用（`import/export`）
 - `"use strict"` は一部モジュールで使用
-- JSDocコメントは部分的に記載
+- JSDocコメントは基本的に記載する
 
 ### 変更を加える際の確認事項
 

package/docs/spec.md

@@ -129,7 +129,7 @@ url: /custom-url
 |--------|-------------|------|
 | `name` | ファイル名（拡張子なし） | ページの内部名 |
 | `title` | `name` の値 | ページタイトル |
-| `url` | `/${name}` | URLパス |
+| `url` | `/${name}` | URLパス（出力先も決定する。後述） |
 | `description` | 本文先頭150文字 | ページ説明 |
 | `og_description` | `description` と同じ | OGP説明文 |
 | `published` | `"1970-01-01"` | 公開日 |
@@ -146,9 +146,41 @@ url: /custom-url
 | `markdown` | 解析後のHTML | Markdown変換後のHTML |
 | `markdown_not_parsed` | フロントマター除去後 | 変換前のMarkdown |
 | `full_url` | 自動生成 | 完全なURL |
-| `__output` | 自動生成 | 出力ファイルパス |
+| `__output` | 自動生成 | 出力ファイルパス（`url` から導出） |
 | `__filetype` | 拡張子 | 元ファイルの拡張子 |
 
+### `url` と出力先の関係
+
+`url` フィールドはリンクの `href` に使われるだけでなく、**出力ファイルパス（`__output`）の導出元**にもなっています。
+
+| `url` の形式 | `__output` |
+|-------------|-----------|
+| `/foo/bar`（末尾スラッシュなし） | `/foo/bar.html` |
+| `/foo/bar/`（末尾スラッシュあり） | `/foo/bar/index.html` |
+
+フロントマターで `url` を上書きすると `__output` も再計算されるため、ファイルの物理的な配置とは無関係に出力先を変更できます。
+
+```markdown
+---
+url: /book/new/book
+---
+```
+
+この場合、ファイルが `src/pages/book/new_book.md` であっても、出力先は `dist/book/new/book.html` になります。
+
+**例外**: ファイル名が `index` の場合は `__output = /index.html` 固定（`url` に関係なし）。また、カテゴリーパッケージの仮想ページのように `__output` を明示的に設定するケースでは、この導出は行われません。
+
+### URLの末尾スラッシュ規約
+
+S3+CDN 等のファイルシステムベースのホスティングでは、`/book` というURLが `book.html` を指すのか `book/index.html` を指すのかをURLだけから判断できません。これを避けるため、以下の規約を推奨します。
+
+| ページ種別 | URL形式 | 出力先 |
+|-----------|---------|-------|
+| アイテム系（記事・個別ページ） | 末尾スラッシュなし `/book/foo` | `dist/book/foo.html` |
+| リスト系（一覧・カテゴリー・ページネーション） | 末尾スラッシュあり `/book/` | `dist/book/index.html` |
+
+リスト系ページを作る場合は、フロントマターで `url` を末尾スラッシュつきで指定するか、ファイル名を `index.md` にします。カテゴリーパッケージの仮想ページはこの規約に従い、`url` に末尾スラッシュを付与しています。
+
 ### データ型の記述
 
 フロントマター内のデータ型:
@@ -166,6 +198,12 @@ published: true
 # 配列（JSON形式）
 tags: ["tag1", "tag2", "tag3"]
 
+# 配列（YAMLリスト形式）
+tags:
+  - tag1
+  - tag2
+  - tag3
+
 # オブジェクト（JSON形式）
 metadata: {"author": "名前", "year": 2024}
 
@@ -178,7 +216,7 @@ description: "これは
 url_base: config.url_base
 ```
 
-**重要**: 配列・オブジェクトは `JSON.parse()` で解析されるため、有効なJSON形式である必要があります。
+**配列の記述形式**: JSON形式（`["item1", "item2"]`）とYAMLリスト形式（`- item`）の両方をサポートします。オブジェクトはJSON形式のみ対応です。
 
 ## テンプレート記法
 
@@ -429,6 +467,7 @@ helper.readIndex('/post')
 | `url_case` | URLの大文字小文字変換 (`lower`/`original`) | `lower` |
 | `url_separator` | スペースの置き換え文字 | `"-"` |
 | `url_prefix` | カテゴリーURLのプレフィックス | `""` |
+| `per_page` | 1ページあたりの記事数。正の整数のときページネーション有効。`false`・`0`・未設定はページネーションなし | `undefined` |
 
 **設定オプションの詳細:**
 
@@ -457,10 +496,18 @@ helper.readIndex('/post')
   title: 'Frontend',                    // カテゴリー名
   template: 'category.html',
   category_path: ['Tech', 'Frontend'],  // カテゴリーパス
-  category_pages: ['tech/frontend/react/tutorial', ...],  // このカテゴリーのページ
-  category_children: ['/tech/frontend/react', ...],       // サブカテゴリー
+  category_pages: ['tech/frontend/react/tutorial', ...],  // このカテゴリーのページ（per_page設定時は当該ページのスライス）
+  category_children: [                  // サブカテゴリー（{url, title}[] 型）
+    { url: '/tech/frontend/react', title: 'React' },
+    ...
+  ],
   __is_auto_category: true,
-  distribute: true
+  distribute: true,
+  // 常に設定されるページネーションフィールド（per_page 無効時は current_page=1, total_pages=1, per_page=undefined）:
+  category_current_page: 1,           // 現在のページ番号（1始まり）
+  category_total_pages: 3,            // 総ページ数
+  category_per_page: 10,              // 1ページあたりの件数（per_page 無効時は undefined）
+  category_pagination_base: '/tech/frontend/',  // カテゴリー1ページ目URL（末尾スラッシュあり）
 }
 ```
 
@@ -468,8 +515,12 @@ helper.readIndex('/post')
 
 - `{{title}}` - カテゴリー名
 - `{{category_path}}` - カテゴリーパス配列
-- `{{category_pages}}` - このカテゴリーに属するページ名の配列
-- `{{category_children}}` - サブカテゴリーのURL配列
+- `{{category_pages}}` - このカテゴリーに属するページ名の配列（ページネーション有効時は当該ページ分のスライス）
+- `{{category_children}}` - サブカテゴリーの配列。各要素は `{url: string, title: string}` オブジェクト
+- `{{category_current_page}}` - 現在のページ番号（常に設定、ページネーション無効時は `1`）
+- `{{category_total_pages}}` - 総ページ数（常に設定、ページネーション無効時は `1`）
+- `{{category_per_page}}` - 1ページあたりの件数（ページネーション無効時は `undefined`）
+- `{{category_pagination_base}}` - カテゴリーの1ページ目URL、末尾スラッシュあり（常に設定）
 
 **複数カテゴリーシステムの使用:**
 
@@ -527,6 +578,115 @@ helper.readIndex('/post')
 
 `src/pages/tech/index.md` が存在する場合、自動生成はスキップされます。
 
+---
+
+#### category パッケージ: ページネーション
+
+`per_page` を設定すると、カテゴリーごとに複数の静的HTMLページが自動生成されます。
+
+**設定例:**
+
+```json
+{
+  "categories": [
+    {
+      "name": "books",
+      "url_prefix": "/book-list",
+      "path_filter": "book/",
+      "template": "category.html",
+      "auto_generate": true,
+      "per_page": 10
+    }
+  ]
+}
+```
+
+**生成されるURL:**
+
+10件の記事と `per_page: 3` の設定では:
+
+| ページ | ページ名（allData キー） | 出力ファイル |
+|--------|--------------------------|-------------|
+| 1 | `book-list/art/index` | `dist/book-list/art/index.html` |
+| 2 | `book-list/art/2/index` | `dist/book-list/art/2/index.html` |
+| 3 | `book-list/art/3/index` | `dist/book-list/art/3/index.html` |
+
+1ページ目のURL・ファイル名は `per_page` 未設定時と同じで後方互換を維持します。
+
+**`per_page` 未設定時との違い:**
+
+| 項目 | per_page 未設定 | per_page 設定あり |
+|------|----------------|-----------------|
+| 生成ページ数 | 1 | ceil(記事数 / per_page) |
+| `category_pages` | 全記事 | 当該ページの記事スライス |
+| `category_current_page` 等 | あり（current_page=1, total_pages=1） | あり |
+
+**ページネーション UI パーシャル（`_pagination.html`）:**
+
+`packages/category/template/_pagination.html` がパッケージに同梱されており、`category.html` から自動的に include されます。`total_pages <= 1` のときは何も出力しません。
+
+独自スタイルに合わせてカスタマイズする場合は、`src/template/_pagination.html` に同名ファイルを配置するとパッケージのデフォルトを上書きできます（[ファイル優先順位](#ファイル優先順位) 参照）。
+
+**ページネーションヘルパー（`pagination.js`）:**
+
+`packages/category/helper/pagination.js` に以下の関数が提供されています。独自テンプレートを作成する際に `{script}` ブロックから直接利用できます（`import` 不要、インライン実装）。
+
+```javascript
+// ページ番号から URL を生成する
+// page === 1 → basePath、それ以外 → basePath + page + '/'
+getPaginationUrl(basePath, page)
+
+// ウィンドウ付きページ番号リストを生成する
+// 各要素: {num: number, isCurrent: boolean} または {num: null, isEllipsis: true}
+buildWindowedPages(totalPages, currentPage, windowSize = 2)
+```
+
+**使用例（カスタムテンプレート内）:**
+
+```html
+<script type="ssg">
+  if ((variables.category_total_pages || 0) <= 1) return ''
+
+  const totalPages = variables.category_total_pages
+  const currentPage = variables.category_current_page
+  const base = variables.category_pagination_base
+
+  // ページURLを生成（page=1 → base, page=2 → base + '2/'）
+  const prevUrl = currentPage > 1 ? base + (currentPage - 1 === 1 ? '' : (currentPage - 1) + '/') : null
+  const nextUrl = currentPage < totalPages ? base + (currentPage + 1) + '/' : null
+
+  let html = '<nav class="pagination">'
+  if (prevUrl) html += `<a href="${prevUrl}">前へ</a>`
+  if (nextUrl) html += `<a href="${nextUrl}">次へ</a>`
+  html += '</nav>'
+  return html
+</script>
+```
+
+**`category_children` の型（破壊的変更）:**
+
+この変更により、`category_children` の型が `string[]`（URL文字列の配列）から `{url: string, title: string}[]`（オブジェクトの配列）に変わりました。
+
+既存のカスタムテンプレートで `category_children` を文字列として扱っている場合は更新が必要です。
+
+```html
+<!-- 旧 (変更前) -->
+<script type="ssg">
+  for (const childUrl of variables.category_children) {
+    html += `<a href="${childUrl}">${childUrl}</a>`
+  }
+</script>
+
+<!-- 新 (変更後) -->
+<script type="ssg">
+  for (const child of variables.category_children) {
+    html += `<a href="${child.url}">${child.title}</a>`
+  }
+</script>
+```
+
+---
+
 **ヘルパー関数:**
 
 ```javascript
@@ -843,7 +1003,8 @@ import { allData, config, dir } from '@tenjuu99/blog'
 ## 制約事項
 
 - フロントマターは YAML 完全互換ではなく、独自パーサーを使用
-- 配列・オブジェクトは JSON 形式で記述必須
+- 配列は JSON 形式（`["item1"]`）または YAML リスト形式（`- item`）で記述可能
+- オブジェクトは JSON 形式で記述必須
 - 変数名は強制的に小文字化される
 - `include()` は同期処理のため、非同期ファイル読み込みは不可
 - SSGスクリプト内で `import()` は使用不可（ヘルパー関数を使用）

package/lib/dir.js

@@ -34,16 +34,34 @@ const cache = () => {
   if (config.packages) {
     const packages = config.packages.split(',')
     packages.forEach(dir => {
+      // TODO: 将来的には hookDir を導入し、hooks/ からフックを読み込む仕組みにする。
+      // 現状はフックの解決が helperDir に依存しているため、config.hooks に登録済みのファイルを
+      // helper 自動登録から除外することで helper として公開されないようにしている（workaround）。
+      const hookFiles = new Set(
+        config.hooks ? Object.values(config.hooks).flat() : []
+      )
       if (fs.existsSync(`${packageDirCore}/${dir}`)) {
-        const helper = config.helper.split(',')
+        const helper = config.helper.split(',').filter(Boolean)
         helper.push(`${dir}.js`)
+        const pkgHelperDir = `${packageDirCore}/${dir}/helper`
+        if (fs.existsSync(pkgHelperDir)) {
+          fs.readdirSync(pkgHelperDir)
+            .filter(f => f.endsWith('.js') && !helper.includes(f) && !hookFiles.has(f))
+            .forEach(f => helper.push(f))
+        }
         config.helper = helper.join(',')
         console.log(styleText('blue', `[cache] enable core package: ${dir}`))
         fs.cpSync(`${packageDirCore}/${dir}`, cacheDir, { recursive: true })
       }
       if (fs.existsSync(`${packageDir}/${dir}`)) {
-        const helper = config.helper.split(',')
+        const helper = config.helper.split(',').filter(Boolean)
         helper.push(`${dir}.js`)
+        const pkgHelperDir = `${packageDir}/${dir}/helper`
+        if (fs.existsSync(pkgHelperDir)) {
+          fs.readdirSync(pkgHelperDir)
+            .filter(f => f.endsWith('.js') && !helper.includes(f) && !hookFiles.has(f))
+            .forEach(f => helper.push(f))
+        }
         config.helper = helper.join(',')
         console.log(styleText('blue', `[cache] enable package: ${dir}`))
         fs.cpSync(`${packageDir}/${dir}`, cacheDir, { recursive: true })

package/lib/helper.js

@@ -2,16 +2,21 @@ import config from './config.js'
 import { existsSync } from 'node:fs'
 import { helperDir } from './dir.js'
 
-let helper = {}
+const helper = {}
 
-if (config.helper) {
-  const files = config.helper.split(',')
-  for (const file of files) {
-    if (existsSync(`${helperDir}/${file}`)) {
-      const helperAdditional = await import(`${helperDir}/${file}`)
-      helper = Object.assign(helper, helperAdditional)
+// top-level await を使うと循環依存がある場合に ESM のデッドロックが発生するため IIFE を使用する。
+// helperReady をエクスポートすることで、ヘルパーのロード完了を外部から await できる。
+// （Promise は一度 resolve すれば以降の await は即座に返るため、複数箇所で await しても問題ない）
+export const helperReady = (async () => {
+  if (config.helper) {
+    const files = config.helper.split(',')
+    for (const file of files) {
+      if (existsSync(`${helperDir}/${file}`)) {
+        const helperAdditional = await import(`${helperDir}/${file}`)
+        Object.assign(helper, helperAdditional)
+      }
     }
   }
-}
+})()
 
 export default helper

package/lib/pageData.js

@@ -56,7 +56,11 @@ const parse = (content, name, ext) => {
     metaDataMerged.url = '/preview' + metaDataMerged.url
   }
   metaDataMerged.full_url = fullUrl(metaDataMerged)
-  metaDataMerged['__output'] = name === 'index' ? '/index.html' : `${metaDataMerged.url}.${metaDataMerged.ext}`
+  metaDataMerged['__output'] = name === 'index'
+    ? '/index.html'
+    : metaDataMerged.url.endsWith('/')
+      ? `${metaDataMerged.url}index.html`
+      : `${metaDataMerged.url}.${metaDataMerged.ext}`
 
   return metaDataMerged
 }
@@ -64,13 +68,38 @@ const parse = (content, name, ext) => {
 const parseMetaData = (data) => {
   const metaData = {}
   let isStringContinue = false
+  let isYamlArray = false
   let key, value
-  for (const line of data.split('\n')) {
+  const lines = data.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (isYamlArray) {
+      const itemMatch = line.match(/^\s+-\s+(.+)/)
+      if (itemMatch) {
+        const rawItem = itemMatch[1].trim()
+        let item
+        try {
+          item = JSON.parse(rawItem)
+        } catch (e) {
+          item = rawItem.replace(/^'|'$/g, '')
+        }
+        metaData[key].push(item)
+        continue
+      } else {
+        isYamlArray = false
+      }
+    }
     if (!isStringContinue) {
       const match = line.match(METADATA_KEY_REGEXP)
       if (match) {
         key = match[1]
         value = line.slice(line.indexOf(':') + 1).trim()
+        const nextLine = lines[i + 1] || ''
+        if (value === '' && nextLine.match(/^\s+-\s+/)) {
+          metaData[key] = []
+          isYamlArray = true
+          continue
+        }
         try {
           value = JSON.parse(value)
         } catch (e) {

package/lib/render.js

@@ -6,6 +6,7 @@ import replaceVariablesFilter from './replaceVariablesFilter.js'
 import includeFilter from './includeFilter.js'
 import { marked } from "marked";
 import { applyTemplate } from './applyTemplate.js'
+import { helperReady } from './helper.js'
 
 marked.use({
   gfm: true,
@@ -13,6 +14,7 @@ marked.use({
 })
 
 const render = async (templateName, data) => {
+  await helperReady
   let template
   if (!templateName) {
     template = '{{MARKDOWN}}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenjuu99/blog",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "blog template",
   "main": "index.js",
   "scripts": {

package/packages/category/css/pagination.css

@@ -0,0 +1,51 @@
+.pagination {
+  margin: 2rem 0 1rem;
+}
+
+.pagination-list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.25rem;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.pagination-list li a,
+.pagination-list li span {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2rem;
+  height: 2rem;
+  padding: 0 0.5rem;
+  border-radius: 4px;
+  font-size: 0.9rem;
+  text-decoration: none;
+  line-height: 1;
+}
+
+.pagination-list li a {
+  border: 1px solid #ccc;
+  color: inherit;
+}
+
+.pagination-list li a:hover {
+  background-color: #f0f0f0;
+}
+
+.pagination-current span {
+  border: 1px solid currentColor;
+  font-weight: bold;
+}
+
+.pagination-ellipsis span {
+  border: none;
+  color: #999;
+}
+
+.pagination-prev,
+.pagination-next {
+  font-size: 0.85rem;
+}

package/packages/category/helper/categoryIndexer.js

@@ -1,5 +1,81 @@
 import { buildCategoryTree } from './category.js'
 
+/**
+ * 記事名配列を perPage 件ずつのページ配列に分割する
+ * 空の場合は [[]] を返す（ページ数ゼロを避けるため）
+ */
+function sliceIntoPages(items, perPage) {
+  if (items.length === 0) return [[]]
+  const pages = []
+  for (let i = 0; i < items.length; i += perPage) {
+    pages.push(items.slice(i, i + perPage))
+  }
+  return pages
+}
+
+/**
+ * 仮想カテゴリーページオブジェクトを生成する
+ *
+ * 通常のページオブジェクトに対して以下のカテゴリー固有プロパティを追加する:
+ *   category_path     - カテゴリーパス配列
+ *   category_children - サブカテゴリー一覧 {url, title}[]
+ *   category_pages    - このカテゴリーのページ名配列（呼び出し側でセット）
+ *   __is_auto_category - 自動生成フラグ
+ *
+ * 以下のページネーションフィールドは常に設定される:
+ *   category_current_page    - 現在のページ番号（1始まり）
+ *   category_total_pages     - 総ページ数
+ *   category_per_page        - 1ページあたりの件数（per_page <= 0 または未設定時は undefined）
+ *   category_pagination_base - カテゴリー1ページ目URL（末尾スラッシュあり）
+ * ページネーション無効時（per_page が正の整数でない場合）は current_page=1, total_pages=1 となる。
+ *
+ * @param {string} url - ページURL
+ * @param {Object} categoryData - カテゴリーデータ（baseUrl を含む）
+ * @param {Array} children - 子カテゴリー一覧
+ * @param {number} currentPage - 現在のページ番号
+ * @param {number} totalPages - 総ページ数
+ * @param {Object} categoryConfig - 単一カテゴリー設定オブジェクト
+ * @param {Object} config - グローバル設定オブジェクト
+ */
+function buildVirtualPage(url, categoryData, children, currentPage, totalPages, categoryConfig, config) {
+  const pageName = url.replace(/^\//, '') + '/index'
+  const paginationBase = categoryData.baseUrl + '/'
+  const perPage = categoryConfig.per_page
+
+  const page = {
+    name: pageName,
+    url: url + '/',
+    __output: `${url}/index.html`,
+    title: categoryData.title,
+    template: categoryConfig.template || 'category.html',
+    markdown: '',
+    category_path: categoryData.path,
+    category_children: children,
+    __is_auto_category: true,
+    distribute: true,
+    index: false,
+    noindex: false,
+    lang: 'ja',
+    published: '1970-01-01',
+    ext: 'html',
+    site_name: config.site_name || 'default',
+    url_base: config.url_base || 'http://localhost:8000',
+    relative_path: config.relative_path || '',
+    description: `${categoryData.title} カテゴリーのページ一覧`,
+    og_description: `${categoryData.title} カテゴリーのページ一覧`,
+    __filetype: 'md',
+    markdown_not_parsed: '',
+    full_url: `${config.url_base || 'http://localhost:8000'}${url}/`,
+    category_pages: [],
+    category_current_page: currentPage,
+    category_total_pages: totalPages,
+    category_per_page: perPage > 0 ? perPage : undefined,
+    category_pagination_base: paginationBase,
+  }
+
+  return page
+}
+
 /**
  * 単一カテゴリー設定に対してカテゴリーページを生成する
  * @param {Object} allData - 全ページデータ（仮想ページの追加先）
@@ -7,7 +83,6 @@ import { buildCategoryTree } from './category.js'
  * @param {Object} config - グローバル設定オブジェクト
  */
 function generateCategoryPages(allData, categoryConfig, config) {
-  // path_filter でページをフィルタ
   const pathFilter = categoryConfig.path_filter || ''
   let filteredData = allData
 
@@ -20,45 +95,40 @@ function generateCategoryPages(allData, categoryConfig, config) {
     }
   }
 
-  // カテゴリーツリーを構築（category キーにラップして buildCategoryTree に渡す）
   const treeConfig = { category: categoryConfig }
   const tree = buildCategoryTree(filteredData, treeConfig)
 
-  // 各カテゴリーに対して仮想ページを生成
   for (const [url, categoryData] of Object.entries(tree)) {
-    const pageName = url.replace(/^\//, '') + '/index'
+    const children = Object.entries(categoryData.children).map(([childUrl, childNode]) => ({
+      url: childUrl + '/',
+      title: childNode.title,
+    }))
 
-    // 既存ページ（手動作成）が存在する場合はスキップ
-    if (allData[pageName]) {
-      continue
-    }
+    const categoryInfo = { ...categoryData, baseUrl: url }
+    const perPage = categoryConfig.per_page
+
+    if (perPage > 0) {
+      const slices = sliceIntoPages(categoryData.pages, perPage)
+      const totalPages = slices.length
+
+      for (let i = 0; i < slices.length; i++) {
+        const currentPage = i + 1
+        const pageUrl = currentPage === 1 ? url : `${url}/${currentPage}`
+        const pageName = pageUrl.replace(/^\//, '') + '/index'
+
+        if (allData[pageName]) continue
+
+        const virtualPage = buildVirtualPage(pageUrl, categoryInfo, children, currentPage, totalPages, categoryConfig, config)
+        virtualPage.category_pages = slices[i]
+        allData[pageName] = virtualPage
+      }
+    } else {
+      const pageName = url.replace(/^\//, '') + '/index'
+      if (allData[pageName]) continue
 
-    // 仮想カテゴリーページを生成
-    allData[pageName] = {
-      name: pageName,
-      url: url,
-      __output: `${url}/index.html`,
-      title: categoryData.title,
-      template: categoryConfig.template || 'category.html',
-      markdown: '',
-      category_path: categoryData.path,
-      category_pages: categoryData.pages,
-      category_children: Object.keys(categoryData.children),
-      __is_auto_category: true,
-      distribute: true,
-      index: false,
-      noindex: false,
-      lang: 'ja',
-      published: '1970-01-01',
-      ext: 'html',
-      site_name: config.site_name || 'default',
-      url_base: config.url_base || 'http://localhost:8000',
-      relative_path: config.relative_path || '',
-      description: `${categoryData.title} カテゴリーのページ一覧`,
-      og_description: `${categoryData.title} カテゴリーのページ一覧`,
-      __filetype: 'md',
-      markdown_not_parsed: '',
-      full_url: `${config.url_base || 'http://localhost:8000'}${url}`
+      const virtualPage = buildVirtualPage(url, categoryInfo, children, 1, 1, categoryConfig, config)
+      virtualPage.category_pages = categoryData.pages
+      allData[pageName] = virtualPage
     }
   }
 }
@@ -71,7 +141,6 @@ function generateCategoryPages(allData, categoryConfig, config) {
  * @param {Object} config - 設定オブジェクト
  */
 export async function afterIndexing(allData, config) {
-  // categories 配列または category 単一設定からカテゴリーシステム一覧を取得
   const categorySystems = config.categories
     ? config.categories
     : (config.category ? [config.category] : [])

package/packages/category/helper/pagination.js

@@ -0,0 +1,36 @@
+/**
+ * getPaginationUrl: ページ番号から URL を生成する
+ * page === 1 なら basePath、それ以外なら basePath + page + '/'
+ */
+export function getPaginationUrl(basePath, page) {
+  const base = basePath.endsWith('/') ? basePath : `${basePath}/`
+  if (page === 1) return base
+  return `${base}${page}/`
+}
+
+/**
+ * buildWindowedPages: ウィンドウ付きページ番号リストを生成する
+ * 各要素は {num, isCurrent} または {num: null, isEllipsis: true}
+ */
+export function buildWindowedPages(totalPages, currentPage, windowSize = 2) {
+  if (totalPages <= 0) return []
+  if (totalPages === 1) return [{ num: 1, isCurrent: currentPage === 1 }]
+
+  const rangeStart = Math.max(2, currentPage - windowSize)
+  const rangeEnd = Math.min(totalPages - 1, currentPage + windowSize)
+  const result = []
+
+  result.push({ num: 1, isCurrent: currentPage === 1 })
+
+  if (rangeStart > 2) result.push({ num: null, isEllipsis: true })
+
+  for (let i = rangeStart; i <= rangeEnd; i++) {
+    result.push({ num: i, isCurrent: i === currentPage })
+  }
+
+  if (rangeEnd < totalPages - 1) result.push({ num: null, isEllipsis: true })
+
+  result.push({ num: totalPages, isCurrent: currentPage === totalPages })
+
+  return result
+}

package/packages/category/template/_pagination.html

@@ -0,0 +1,37 @@
+<script type="ssg">
+  const totalPages = variables.category_total_pages || 0
+  if (totalPages <= 1) return ''
+
+  const currentPage = variables.category_current_page || 1
+  const paginationBase = variables.category_pagination_base || ''
+  const relativePath = variables.relative_path || ''
+
+  const pages = helper.buildWindowedPages(totalPages, currentPage)
+
+  let html = '<nav class="pagination" aria-label="ページネーション">'
+  html += '<ul class="pagination-list">'
+
+  if (currentPage > 1) {
+    const prevUrl = helper.getPaginationUrl(paginationBase, currentPage - 1)
+    html += `<li class="pagination-prev"><a href="${relativePath}${prevUrl}">&laquo; 前へ</a></li>`
+  }
+
+  for (const p of pages) {
+    if (p.isEllipsis) {
+      html += '<li class="pagination-ellipsis"><span aria-hidden="true">…</span></li>'
+    } else if (p.isCurrent) {
+      html += `<li class="pagination-current"><span aria-current="page">${p.num}</span></li>`
+    } else {
+      const pageUrl = helper.getPaginationUrl(paginationBase, p.num)
+      html += `<li><a href="${relativePath}${pageUrl}">${p.num}</a></li>`
+    }
+  }
+
+  if (currentPage < totalPages) {
+    const nextUrl = helper.getPaginationUrl(paginationBase, currentPage + 1)
+    html += `<li class="pagination-next"><a href="${relativePath}${nextUrl}">次へ &raquo;</a></li>`
+  }
+
+  html += '</ul></nav>'
+  return html
+</script>

package/packages/category/template/category.html

@@ -16,6 +16,9 @@
   <meta name="description" content="{{DESCRIPTION}}">
 
   {include('template/css.html')}
+  <style>
+    {include('css/pagination.css')}
+  </style>
 </head>
 <body>
   <header>
@@ -45,15 +48,16 @@
           html += '<h2>サブカテゴリー</h2>'
           html += '<div class="category-children">'
 
-          for (const childUrl of children) {
+          for (const child of children) {
+            const childUrl = typeof child === 'string' ? child : child.url
+            const childTitle = typeof child === 'string' ? null : child.title
             const childPageName = childUrl.replace(/^\//, '') + '/index'
             const childData = helper.getPageData(childPageName)
+            const title = childTitle || (childData && childData.title) || childUrl
 
-            if (childData) {
-              html += '<div class="category-child-card">'
-              html += `<a href="${relativePath}${childUrl}/">${childData.title}</a>`
-              html += '</div>'
-            }
+            html += '<div class="category-child-card">'
+            html += `<a href="${relativePath}${childUrl}/">${title}</a>`
+            html += '</div>'
           }
 
           html += '</div></div>'
@@ -104,6 +108,7 @@
           html += '</ul>'
           return html
         </script>
+        {include('template/_pagination.html')}
       </div>
     </article>
   </main>

package/src-sample/pages/book/after-rain.md

@@ -1,6 +1,6 @@
 ---
 title: After Rain
-category: ["Art", "Painting"]
+category: ["Book", "Art", "Painting"]
 published: 2024-01-15
 ---
 
@@ -10,4 +10,4 @@ published: 2024-01-15
 
 カテゴリー: Art > Painting
 
-このページは `/book-list/art/painting/` カテゴリーに含まれるべきです。
+このページは `/book/art/painting/` カテゴリーに含まれるべきです。

package/src-sample/pages/book/japanese-history.md

@@ -1,6 +1,6 @@
 ---
 title: Japanese History
-category: ["History", "Japan"]
+category: ["Book", "History", "Japan"]
 published: 2024-03-10
 ---
 
@@ -8,6 +8,6 @@ published: 2024-03-10
 
 これは書籍「Japanese History」のページです。
 
-カテゴリー: [History]({{RELATIVE_PATH}}/book-list/history/) > [Japan]({{RELATIVE_PATH}}/book-list/history/japan/)
+カテゴリー: [History]({{RELATIVE_PATH}}/book/history/) > [Japan]({{RELATIVE_PATH}}/book/history/japan/)
 
-このページは `/book-list/history/japan/` カテゴリーに含まれるべきです。
+このページは `/book/history/japan/` カテゴリーに含まれるべきです。

package/src-sample/pages/book/modern-sculpture.md

@@ -1,6 +1,6 @@
 ---
 title: Modern Sculpture
-category: ["Art", "Sculpture"]
+category: ["Book", "Art", "Sculpture"]
 published: 2024-02-20
 ---
 
@@ -8,6 +8,6 @@ published: 2024-02-20
 
 これは書籍「Modern Sculpture」のページです。
 
-カテゴリー: [Art]({{RELATIVE_PATH}}/book-list/art/) > [Sculpture]({{RELATIVE_PATH}}/book-list/art/sculpture/)
+カテゴリー: [Art]({{RELATIVE_PATH}}/book/art/) > [Sculpture]({{RELATIVE_PATH}}/book/art/sculpture/)
 
-このページは `/book-list/art/sculpture/` カテゴリーに含まれるべきです。
+このページは `/book/art/sculpture/` カテゴリーに含まれるべきです。

package/src-sample/pages/book/oil-painting-masters.md

@@ -0,0 +1,9 @@
+---
+title: Oil Painting Masters
+category: ["Book", "Art", "Painting"]
+published: 2024-05-01
+---
+
+# Oil Painting Masters
+
+油彩画の巨匠たちの作品集です。

package/src-sample/pages/book/watercolor-landscapes.md

@@ -0,0 +1,9 @@
+---
+title: Watercolor Landscapes
+category: ["Book", "Art", "Painting"]
+published: 2024-04-01
+---
+
+# Watercolor Landscapes
+
+水彩風景画の画集です。