@tenjuu99/blog 0.2.57 → 0.3.1

package/README.md

@@ -30,6 +30,7 @@ npx server
 - CSSの自動結合・minify・キャッシュバスト
 - ヘルパー関数による拡張性
 - パッケージシステムによる機能拡張
+  - **category パッケージ**: 階層型カテゴリーの自動ページ生成、複数カテゴリーシステムのサポート
 
 ## システム要件
 

package/docs/develop.md

@@ -238,6 +238,95 @@ packages/{パッケージ名}/
 - `packages/editor/` - エディター機能
 - `packages/turbolink/` - Turbolink機能
 
+## パッケージのカスタマイズ方法
+
+### 基本原則
+
+パッケージが提供する任意のファイルを `src/` 配下に同じ構造で配置すると上書きできます。これは `.cache/` ディレクトリへの展開時に、`src/` の内容が `packages/` の内容を上書きするためです（`lib/dir.js:53-57`）。
+
+### テンプレートのカスタマイズ
+
+**例**: category パッケージのテンプレートを変更
+
+1. `src/template/category.html` を作成
+2. 独自のデザインを実装
+3. `.cache/` を削除して再ビルド
+
+```html
+<!-- src/template/category.html -->
+{include('meta.html')}
+<h1>My Custom Category Page</h1>
+{script}
+  const items = allData.filter(data => data.category === page.category)
+  include('item-list.html', { items })
+{/script}
+```
+
+パッケージのデフォルトテンプレート（`packages/category/template/category.html`）が `src/template/category.html` で上書きされます。
+
+### CSS のカスタマイズ
+
+**例**: breadcrumbs.css のスタイルを変更
+
+1. `src/css/breadcrumbs.css` を作成
+2. カスタムスタイルを記述
+3. テンプレートからの読み込み方法は変更不要
+
+```css
+/* src/css/breadcrumbs.css */
+.breadcrumbs {
+  /* カスタムスタイル */
+  background-color: #f0f0f0;
+  padding: 1rem;
+}
+```
+
+CSS は `.cache/css/` に展開され、通常の静的ファイルとして配信されます。テンプレート内で以下のように読み込みます:
+
+```html
+<!-- src/template/css.html -->
+<link rel="stylesheet" href="${/css/lazy.css<<page.css,markdown.css,breadcrumbs.css}">
+```
+
+### Helper のカスタマイズ
+
+**例**: breadcrumbs ヘルパーの動作を変更
+
+1. `src/helper/breadcrumbs.js` を作成
+2. 独自の実装を提供
+
+```javascript
+// src/helper/breadcrumbs.js
+export function breadcrumbs(page) {
+  // カスタムロジック
+  return page.url.split('/').filter(Boolean).map((segment, i, arr) => {
+    const path = '/' + arr.slice(0, i + 1).join('/')
+    return `<a href="${path}">${segment}</a>`
+  }).join(' > ')
+}
+```
+
+パッケージのデフォルト実装（`packages/breadcrumbs/helper/breadcrumbs.js`）が上書きされます。
+
+### 部分的な拡張
+
+パッケージの一部だけを利用し、他をカスタマイズすることも可能です:
+
+- `packages/category/template/category.html` → `src/template/category.html` で上書き
+- `packages/category/helper/category.js` → そのまま使用（上書きしない）
+- CSS は追加ファイルで拡張（`src/css/category-custom.css` など）
+
+### .cache/ の再生成
+
+キャッシュの問題が発生した場合や、パッケージのカスタマイズが反映されない場合:
+
+```bash
+rm -rf .cache/
+npm run dev  # または npm run generate
+```
+
+`.cache/` を削除すると、次回のビルド時に `lib/dir.js` の `cache()` 関数が再度実行され、パッケージとユーザーコードが正しい優先順位で展開されます。
+
 ## デバッグ方法
 
 ### 1. console.log デバッグ

package/docs/spec.md

@@ -421,6 +421,8 @@ helper.readIndex('/post')
 
 | オプション | 説明 | デフォルト |
 |-----------|------|-----------|
+| `name` | カテゴリーシステムの識別子（`categories` 配列使用時のみ） | - |
+| `path_filter` | 対象とするページのパスプレフィックス（`categories` 配列使用時に推奨） | `""` (全ページ) |
 | `template` | カテゴリーページのテンプレート | `category.html` |
 | `auto_generate` | 自動生成の有効/無効 | `true` |
 | `max_depth` | カテゴリーの最大階層数 | `3` |
@@ -430,6 +432,13 @@ helper.readIndex('/post')
 
 **設定オプションの詳細:**
 
+- **`name`**: カテゴリーシステムの識別子。`categories` 配列で複数のカテゴリーシステムを定義する際に使用します。
+
+- **`path_filter`**: 対象とするページのパスプレフィックス。
+  - 例: `path_filter: "book/"` → `book/` 配下のページのみがこのカテゴリーシステムに含まれる
+  - 空文字列の場合は全ページが対象
+  - 複数カテゴリーシステムを使用する場合は、各システムで `path_filter` を設定することを推奨
+
 - **`url_separator`**: カテゴリー名にスペースが含まれる場合の置き換え文字を指定します。
   - 例: `category: ["Contemporary Art"]` + `url_separator: "-"` → `/contemporary-art/`
   - 例: `category: ["Contemporary Art"]` + `url_separator: "_"` → `/contemporary_art/`
@@ -462,6 +471,58 @@ helper.readIndex('/post')
 - `{{category_pages}}` - このカテゴリーに属するページ名の配列
 - `{{category_children}}` - サブカテゴリーのURL配列
 
+**複数カテゴリーシステムの使用:**
+
+`categories` 配列を使用することで、複数の独立したカテゴリーシステムを定義できます。
+
+```json
+{
+  "packages": "category",
+  "hooks": {
+    "afterIndexing": "categoryIndexer.js"
+  },
+  "categories": [
+    {
+      "name": "books",
+      "url_prefix": "/book-list",
+      "path_filter": "book/",
+      "template": "category.html",
+      "auto_generate": true,
+      "max_depth": 3,
+      "url_case": "lower",
+      "url_separator": "-"
+    },
+    {
+      "name": "articles",
+      "url_prefix": "/article-list",
+      "path_filter": "article/",
+      "template": "article-category.html",
+      "auto_generate": true,
+      "max_depth": 2
+    }
+  ]
+}
+```
+
+**動作例:**
+- `book/after-rain.md` (category: ["Art", "Painting"]) → `/book-list/art/painting/index.html`
+- `article/news/200910.md` (category: ["News"]) → `/article-list/news/index.html`
+- `/book-list/news/index.html` は生成**されない**（意図しないページ生成を防止）
+- `/article-list/art/index.html` は生成**されない**（各システムは独立）
+
+**後方互換性:**
+
+既存の `category`（単数形）設定も引き続き動作します。`categories` 配列と `category` の両方が定義されている場合、`categories` が優先されます。
+
+```json
+{
+  "category": {
+    "template": "category.html",
+    "auto_generate": true
+  }
+}
+```
+
 **手動ページによる上書き:**
 
 `src/pages/tech/index.md` が存在する場合、自動生成はスキップされます。
@@ -643,7 +704,46 @@ export async function afterIndexing(allData, config) {
 
 ## ファイル操作とキャッシュ
 
-### `.cache/` ディレクトリ
+### `.cache/` ディレクトリの役割
+
+#### 概要
+
+`.cache/` はパッケージとユーザーコードを統合した「実効的なソースディレクトリ」として機能します。ビルドシステムはこのディレクトリを実際のソースとして扱います。
+
+#### ファイル展開の仕組み
+
+`lib/dir.js` の `cache()` 関数が以下の順序で実行します:
+
+1. **コアパッケージの展開**: `packages/*/` → `.cache/`（名前空間フラット化）
+2. **ユーザーパッケージの展開**: `src/packages/*/` → `.cache/`
+3. **ユーザーコードのコピー**: `src/` → `.cache/`（上書き）
+
+**展開例**:
+```
+packages/breadcrumbs/helper/breadcrumbs.js → .cache/helper/breadcrumbs.js
+packages/breadcrumbs/css/breadcrumbs.css   → .cache/css/breadcrumbs.css
+packages/category/template/category.html   → .cache/template/category.html
+src/helper/custom.js                       → .cache/helper/custom.js（追加）
+src/template/category.html                 → .cache/template/category.html（上書き）
+```
+
+#### ファイル優先順位
+
+同名ファイルが存在する場合の優先順位:
+
+1. **`src/`** （最優先 - ユーザーカスタム）
+2. **`src/packages/`** （ユーザー定義パッケージ）
+3. **`packages/`** （コアパッケージ）
+
+この仕組みにより、ユーザーはパッケージが提供する任意のファイルを上書きしてカスタマイズできます。
+
+#### Helper の自動登録
+
+`blog.json` の `packages` で指定されたパッケージは:
+- `.cache/helper/<package>.js` が自動的に `config.helper` に追加される（`lib/dir.js:38-40, 45-47`）
+- ユーザーが明示的に設定する必要はない
+
+#### ディレクトリ構造
 
 ビルド時に以下がコピーされます:
 

package/lib/cssGenerator.js

@@ -11,6 +11,9 @@ import config from './config.js'
 let cacheBuster = {}
 const cacheBusterQuery = 't'
 
+// 正規表現をモジュールレベルでキャッシュ
+const CSS_LINK_REGEXP = /\${([\w-_/]+\.css)<<([\w-_/,.]+\.css)}/g
+
 /**
  * @param {string} src
  * @param {string} dist
@@ -51,7 +54,7 @@ const cssGenerator = async (src, dist) => {
  * @return {string}
  */
 const applyCss = async (text) => {
-  const target = [...text.matchAll(/\${([\w-_/]+\.css)<<([\w-_/,.]+\.css)}/g)].map(val => {
+  const target = [...text.matchAll(CSS_LINK_REGEXP)].map(val => {
     return { matched: val[0], dist: val[1], src: val[2] }
   })
   for (const cssDist of target) {

package/lib/filter.js

@@ -1,5 +1,12 @@
 import helper from '../lib/helper.js'
 
+// 正規表現をモジュールレベルでキャッシュ
+const IF_REGEXP = /(\{|\<)if\s(?<condition>[\s\S]+?)(}|>)(?<content>[\s\S]*?)((\{|\<)else(\}|\>)(?<elsecontent>[\s\S]*?))?(\{|\<)\/if(\>|})/g
+const SCRIPT_REGEXP = /({script}|\<script\s.*type="ssg".*>)(?<script>[\s\S]*?)(\{\/script}|\<\/script>)/g
+const CONDITION_SEGMENTS_REGEXP = /(?<left>[\S]+)\s(?<operator>!=|==)\s(?<right>[\S]+)/
+const FUNCTION_CALL_REGEXP = /([\w]+)\((.*)\)/
+const FUNCTION_ARG_REGEXP = /^(['"])?\s*([\w]+)(["'])?$/
+
 /**
  * @param {string} condition
  * @params {object} variables
@@ -7,7 +14,7 @@ import helper from '../lib/helper.js'
  */
 const ifConditionEvaluator = (condition, variables) => {
   if (condition.includes('=')) {
-    const segmented = condition.match(/(?<left>[\S]+)\s(?<operator>!=|==)\s(?<right>[\S]+)/)
+    const segmented = condition.match(CONDITION_SEGMENTS_REGEXP)
     let {left, operator, right} = segmented.groups
     if (variables.hasOwnProperty(left)) {
       left = variables[left]
@@ -34,14 +41,14 @@ const ifConditionEvaluator = (condition, variables) => {
         return left != right
     }
   } else {
-    const match = condition.match(/([\w]+)\((.*)\)/)
+    const match = condition.match(FUNCTION_CALL_REGEXP)
     if (match) {
       const func = match[1]
       if (helper[func] instanceof Function) {
         let args = match[2].trim()
         if (args) {
           args = args.split(',').map(arg => {
-            const match = arg.match(/^(['"])?\s*([\w]+)(["'])?$/)
+            const match = arg.match(FUNCTION_ARG_REGEXP)
             if (match) {
               return match[1] ? `${match[2]}` : variables[match[2]]
             }
@@ -64,8 +71,7 @@ const ifConditionEvaluator = (condition, variables) => {
  * @returns {string}
  */
 const replaceIfFilter = (text, variables) => {
-  const ifRegexp = new RegExp(/(\{|\<)if\s(?<condition>[\s\S]+?)(}|>)(?<content>[\s\S]*?)((\{|\<)else(\}|\>)(?<elsecontent>[\s\S]*?))?(\{|\<)\/if(\>|})/g)
-  const matched = [...text.matchAll(ifRegexp)]
+  const matched = [...text.matchAll(IF_REGEXP)]
   for (const item of matched) {
     const target = item[0]
     const content = item.groups.content
@@ -83,8 +89,7 @@ const replaceIfFilter = (text, variables) => {
 
 const replaceScriptFilter = async (text, variables) => {
   let replaced = text
-  const scriptRegexp = new RegExp(/({script}|\<script\s.*type="ssg".*>)(?<script>[\s\S]*?)(\{\/script}|\<\/script>)/g)
-  const scripts = [...text.matchAll(scriptRegexp)].map((matched) => {
+  const scripts = [...text.matchAll(SCRIPT_REGEXP)].map((matched) => {
     return {
       replace: matched[0],
       script: matched.groups.script.trim("\n"),

package/lib/includeFilter.js

@@ -4,11 +4,12 @@ import { staticFile } from './files.js'
 
 const alreadyLoaded = {}
 
-const includeRegexp = new RegExp(/\{\s*include\('(template|css)\/([\w\./-]+)'\)\s*\}/g)
+// 正規表現をモジュールレベルでキャッシュ
+const INCLUDE_REGEXP = /\{\s*include\('(template|css)\/([\w\./-]+)'\)\s*\}/g
 
 const includeFilter = (text) => {
   let replaced = text
-  const include = [...text.matchAll(includeRegexp)].map(matched => {
+  const include = [...text.matchAll(INCLUDE_REGEXP)].map(matched => {
     return { toBeReplace: matched[0], type: matched[1], filename: matched[2] }
   })
   if (include.length === 0) {
@@ -27,7 +28,7 @@ const includeFilter = (text) => {
         throw new Error(cacheKey + ' is invalid')
       }
       // include を再帰的に解決する
-      if (content.match(includeRegexp)) {
+      if (content.match(INCLUDE_REGEXP)) {
         content = includeFilter(content)
       }
       alreadyLoaded[cacheKey] = content

package/lib/pageData.js

@@ -1,15 +1,18 @@
 "use strict"
 import config from './config.js'
 
+// 正規表現をモジュールレベルでキャッシュ
+const FRONTMATTER_REGEXP = /^(<!|-)--(?<variables>[\s\S]*?)--(-|>)/
+const METADATA_KEY_REGEXP = /^([a-zA-Z\d_-]+):/
+
 const makePageData = (filename, content) => {
   const [name, ext] = filename.split('.')
   return parse(content, name, ext)
 }
 
 const parse = (content, name, ext) => {
-  const regexp = new RegExp(/^(<!|-)--(?<variables>[\s\S]*?)--(-|>)/)
-  const matched = content.match(regexp)
-  const markdownReplaced = content.replace(regexp, '')
+  const matched = content.match(FRONTMATTER_REGEXP)
+  const markdownReplaced = content.replace(FRONTMATTER_REGEXP, '')
   const fullUrl = (data) => {
     const base = data.url_base + (data.relative_path ?? '')
     let url = data.url
@@ -64,7 +67,7 @@ const parseMetaData = (data) => {
   let key, value
   for (const line of data.split('\n')) {
     if (!isStringContinue) {
-      const match = line.match(/^([a-zA-Z\d_-]+):/)
+      const match = line.match(METADATA_KEY_REGEXP)
       if (match) {
         key = match[1]
         value = line.slice(line.indexOf(':') + 1).trim()

package/lib/replaceVariablesFilter.js

@@ -1,5 +1,8 @@
 import helper from './helper.js'
 
+// 正規表現をモジュールレベルでキャッシュ
+const VARIABLE_REGEXP = /(\\)?{{[\s]*([^{}]+)[\s]*}}/g
+
 /**
  * テキストに含まれる変数を一括変換する
  * ヘルパー処理もここで行われる
@@ -9,7 +12,7 @@ import helper from './helper.js'
  * @return {text}
  */
 const replaceVariablesFilter = (text, variables) => {
-  const matched = [...text.matchAll(/(\\)?{{[\s]*([^{}]+)[\s]*}}/g)]
+  const matched = [...text.matchAll(VARIABLE_REGEXP)]
   const replace = Object.fromEntries(matched.map(match => [match[0], {variableName: match[2].trim().toLowerCase(), backslash: !!match[1]}]))
   let replaced = text
   for (const elm in replace) {

package/package.json

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

package/packages/category/helper/categoryIndexer.js

@@ -1,19 +1,28 @@
 import { buildCategoryTree } from './category.js'
 
 /**
- * afterIndexing フック関数
- * カテゴリーツリーを構築し、仮想カテゴリーインデックスページを生成する
- * @param {Object} allData - 全ページデータ
- * @param {Object} config - 設定オブジェクト
+ * 単一カテゴリー設定に対してカテゴリーページを生成する
+ * @param {Object} allData - 全ページデータ（仮想ページの追加先）
+ * @param {Object} categoryConfig - 単一カテゴリー設定オブジェクト
+ * @param {Object} config - グローバル設定オブジェクト
  */
-export async function afterIndexing(allData, config) {
-  // auto_generate が false の場合は何もしない
-  if (config.category?.auto_generate === false) {
-    return
+function generateCategoryPages(allData, categoryConfig, config) {
+  // path_filter でページをフィルタ
+  const pathFilter = categoryConfig.path_filter || ''
+  let filteredData = allData
+
+  if (pathFilter) {
+    filteredData = {}
+    for (const [name, page] of Object.entries(allData)) {
+      if (name.startsWith(pathFilter)) {
+        filteredData[name] = page
+      }
+    }
   }
 
-  // カテゴリーツリーを構築
-  const tree = buildCategoryTree(allData, config)
+  // カテゴリーツリーを構築（category キーにラップして buildCategoryTree に渡す）
+  const treeConfig = { category: categoryConfig }
+  const tree = buildCategoryTree(filteredData, treeConfig)
 
   // 各カテゴリーに対して仮想ページを生成
   for (const [url, categoryData] of Object.entries(tree)) {
@@ -30,7 +39,7 @@ export async function afterIndexing(allData, config) {
       url: url,
       __output: `${url}/index.html`,
       title: categoryData.title,
-      template: config.category?.template || 'category.html',
+      template: categoryConfig.template || 'category.html',
       markdown: '',
       category_path: categoryData.path,
       category_pages: categoryData.pages,
@@ -53,3 +62,25 @@ export async function afterIndexing(allData, config) {
     }
   }
 }
+
+/**
+ * afterIndexing フック関数
+ * カテゴリーツリーを構築し、仮想カテゴリーインデックスページを生成する
+ * `config.categories`（配列）と `config.category`（単一、後方互換）の両方をサポート。
+ * @param {Object} allData - 全ページデータ
+ * @param {Object} config - 設定オブジェクト
+ */
+export async function afterIndexing(allData, config) {
+  // categories 配列または category 単一設定からカテゴリーシステム一覧を取得
+  const categorySystems = config.categories
+    ? config.categories
+    : (config.category ? [config.category] : [])
+
+  for (const categoryConfig of categorySystems) {
+    if (categoryConfig.auto_generate === false) {
+      continue
+    }
+
+    generateCategoryPages(allData, categoryConfig, config)
+  }
+}

package/src-sample/pages/article/news-200910.md

@@ -0,0 +1,13 @@
+---
+title: News Article 200910
+category: ["News"]
+published: 2020-09-10
+---
+
+# News Article 200910
+
+これはニュース記事のページです。
+
+カテゴリー: [News]({{RELATIVE_PATH}}/article-list/news/)
+
+このページは `/article-list/news/` カテゴリーに含まれるべきです。

package/src-sample/pages/article/tech-update.md

@@ -0,0 +1,14 @@
+---
+title: Tech Update Article
+category: ["Tech", "News"]
+published: 2024-01-20
+---
+
+# Tech Update Article
+
+これは技術ニュース記事のページです。
+
+カテゴリー: Tech > News
+カテゴリー: [Tech]({{RELATIVE_PATH}}/article-list/tech/) > [News]({{RELATIVE_PATH}}/article-list/tech/news)
+
+このページは `/article-list/tech/news/` カテゴリーに含まれるべきです。

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

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

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

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

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

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