@tenjuu99/blog 0.2.55 → 0.2.57

package/docs/tutorial.md

@@ -0,0 +1,165 @@
+# @tenjuu99/blog チュートリアル
+
+このチュートリアルでは、`@tenjuu99/blog` を使って静的ブログサイトを作成する方法を学びます。
+
+## 目次
+
+- [セットアップ](#セットアップ)
+- [記事を書く](#記事を書く)
+- [タイトルとURL](#タイトルとurl)
+- [テンプレート](#テンプレート)
+- [設定ファイル](#設定ファイル)
+- [次のステップ](#次のステップ)
+
+## セットアップ
+
+### インストール
+
+まず、`@tenjuu99/blog` をインストールします。
+
+```bash
+npm i @tenjuu99/blog
+```
+
+### プロジェクトの初期化
+
+新しいブログプロジェクトを作成し、開発サーバーを起動します。
+
+```bash
+npx create-blog
+npx server
+```
+
+ブラウザで `http://localhost:8000` にアクセスすると、サイトが表示されます。
+
+## 記事を書く
+
+### 最初の記事を作成
+
+記事は `./src/pages/` ディレクトリ以下にMarkdownファイルとして配置します。
+
+まず、空のファイルでも構わないので `src/pages/test.md` を作成してみましょう。
+
+```bash
+touch src/pages/test.md
+```
+
+`src/pages/test.md` を保存したら、`http://localhost:8000/test` にアクセスして表示できることを確認します。
+
+### 内容を記述
+
+次に、記事の内容を記述します。`src/pages/test.md` を以下のような内容で保存します。
+
+```markdown
+# 第一章 人情の碗
+
+茶は薬用として始まり後飲料となる。シナにおいては八世紀に高雅な遊びの一つとして詩歌の域に達した。十五世紀に至り日本はこれを高めて一種の審美的宗教、すなわち茶道にまで進めた。茶道は日常生活の俗事の中に存する美しきものを崇拝することに基づく一種の儀式であって、純粋と調和、相互愛の神秘、社会秩序のローマン主義を諄々と教えるものである。茶道の要義は「不完全なもの」を崇拝するにある。いわゆる人生というこの不可解なもののうちに、何か可能なものを成就しようとするやさしい企てであるから。
+```
+
+保存したら、`http://localhost:8000/test` をリロードして表示を確認しましょう。
+
+## タイトルとURL
+
+### フロントマターで変数を定義
+
+ファイル冒頭を `---` で囲むと、ページのメタデータや変数を定義できます。
+
+`src/pages/test.md` の冒頭に以下のような変数を設定してみましょう。
+
+```markdown
+---
+title: 第一章 人情の碗
+url: /the_book_of_tea/section_one
+---
+```
+
+保存すると、`http://localhost:8000/test` ではアクセスできなくなり、`http://localhost:8000/the_book_of_tea/section_one` でアクセスできるようになります。
+
+### 変数をテンプレート内で利用
+
+ここで定義した変数は、テンプレート内で `{{変数名}}` という形式で利用できます。
+
+`src/pages/test.md` を次のように書き換えてみます。
+
+```markdown
+---
+title: 第一章 人情の碗
+url: /the_book_of_tea/section_one
+---
+
+# {{title}}
+
+茶は薬用として始まり後飲料となる。シナにおいては八世紀に高雅な遊びの一つとして詩歌の域に達した。十五世紀に至り日本はこれを高めて一種の審美的宗教、すなわち茶道にまで進めた。茶道は日常生活の俗事の中に存する美しきものを崇拝することに基づく一種の儀式であって、純粋と調和、相互愛の神秘、社会秩序のローマン主義を諄々と教えるものである。茶道の要義は「不完全なもの」を崇拝するにある。いわゆる人生というこの不可解なもののうちに、何か可能なものを成就しようとするやさしい企てであるから。
+```
+
+ページをリロードすると、`# {{title}}` が `# 第一章 人情の碗` として表示されます。
+
+### ファイル配置によるURL設定
+
+URLの設定は、フロントマター変数ではなく、ファイルの配置場所でも制御できます。
+
+`src/pages/test.md` を `src/pages/the_book_of_tea/section_one.md` に移動すれば、`url` 変数を定義しなくても同じURLでアクセスできるようになります。
+
+```bash
+mkdir -p src/pages/the_book_of_tea
+mv src/pages/test.md src/pages/the_book_of_tea/section_one.md
+```
+
+## テンプレート
+
+### テンプレートの編集
+
+タイトルが重複して表示されて鬱陶しい場合は、テンプレートを編集します。
+
+`src/template/default.html` を開き、`<h1>{{TITLE}}</h1>` の行を削除しましょう。
+
+```diff
+    <article class="container">
+-     <h1>{{TITLE}}</h1>
+      {{CONTENT}}
+    </article>
+```
+
+開発サーバーを再起動すると、変更が反映されます。
+
+## 設定ファイル
+
+### サイト名の変更
+
+サイト全体の名称を変更するには、`blog.json` を編集します。
+
+`blog.json` を開いて、`site_name` を変更します。
+
+```json
+{
+  "site_name": "茶の本",
+  "url_base": "http://localhost:8000",
+  "src_dir": "src",
+  "dist_dir": "dist",
+  "distribute_raw": "image",
+  "helper": "index.js"
+}
+```
+
+設定ファイルを変更したら、一旦 `CTRL+C` で `npx server` を停止して、再度 `npx server` を実行します。
+
+ヘッダーが「茶の本」になっていたら、設定更新が完了です。
+
+## 次のステップ
+
+基本的な使い方を学びました。次は以下のドキュメントを参照して、より高度な機能を活用しましょう。
+
+### さらに学ぶ
+
+- **[技術仕様書 (spec.md)](spec.md)** - フロントマター、テンプレート構文、Hook機構など詳細な仕様
+- **[開発ガイド (develop.md)](develop.md)** - ライブラリ開発、カスタムパッケージ作成、デバッグ方法
+- **[README.md](../README.md)** - プロジェクト概要とドキュメント索引
+
+### よく使う機能
+
+- **条件分岐とスクリプト実行**: テンプレート内で `{%if%}...{%endif%}` や `{%script%}...{%endscript%}` を使用
+- **ヘルパー関数**: カスタム関数を作成して再利用可能な処理を定義
+- **カテゴリー・タグ**: フロントマターで `category` や `tags` を定義して記事を分類
+- **パッケージシステム**: 再利用可能な機能を独立したパッケージとして作成
+
+詳細は各ドキュメントをご覧ください。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenjuu99/blog",
-  "version": "0.2.55",
+  "version": "0.2.57",
   "description": "blog template",
   "main": "index.js",
   "scripts": {
@@ -36,7 +36,9 @@
     "lib",
     "bin",
     "src-sample",
-    "packages"
+    "packages",
+    "docs",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

package/packages/category/helper/category.js

@@ -11,6 +11,11 @@ let categoryTreeCache = null
 export function buildCategoryTree(data = allData, conf = config) {
   const tree = {}
   const urlCase = conf.category?.url_case || 'lower'
+  const urlSeparator = conf.category?.url_separator || '-'
+  const rawUrlPrefix = conf.category?.url_prefix || ''
+  const urlPrefix = rawUrlPrefix
+    ? '/' + rawUrlPrefix.replace(/^\/+|\/+$/g, '')
+    : ''
   const maxDepth = conf.category?.max_depth || 3
 
   for (const [name, page] of Object.entries(data)) {
@@ -19,11 +24,12 @@ export function buildCategoryTree(data = allData, conf = config) {
     }
 
     const categoryPath = page.category.slice(0, maxDepth)
-    let currentPath = ''
+    let currentPath = urlPrefix
 
     for (let i = 0; i < categoryPath.length; i++) {
       const category = categoryPath[i]
-      const categoryUrl = urlCase === 'lower' ? category.toLowerCase() : category
+      let categoryUrl = urlCase === 'lower' ? category.toLowerCase() : category
+      categoryUrl = categoryUrl.replace(/\s+/g, urlSeparator)
       currentPath += `/${categoryUrl}`
 
       if (!tree[currentPath]) {