Vault Blog Core の各ディレクトリの役割・使い方を説明をします。
主要なフォルダは下記のとおりです。
.
├─ config
├─ data
├─ lib
├─ posts
├─ public
│ ├─ images
│ └─ post-assets
├─ scripts
├─ src
│ ├─ app
│ │ ├─ about
│ │ ├─ posts
│ │ │ ├─ page
│ │ │ └─ [slug]
│ │ └─ tags
│ │ └─ [tag]
│ ├─ components
│ ├─ config
│ └─ lib
└─ types
./config
./config には、全体または ./scripts のみから参照 する情報をまとめています。
現時点では、パス関連の設定、扱うファイル形式の設定などが置かれています。
./data
./data には、Markdown ファイル収集時に生成するメタデータをまとめた JSON ファイルを置いています。
実行時にプログラムから参照・編集するディレクトリで、手動で変更する必要はありません。
./lib
./lib には、全体、または ./scripts のみから使用する機能 まとめています。
現時点では、パス関連の設定、扱うファイル形式の設定などが置かれています。
./posts
プログラムで収集した Markdown ファイルを置く場所です。
実行時にプログラムから参照・編集するディレクトリで、手動で変更する必要はありません。
このディレクトリは、記事投稿時に初期化され、完全に上書き されます。
./public
公開する画像・音声・動画ファイルなどを置く場所です。
./public/post-assets
プログラムで収集した画像・音声・動画ファイルを置く場所です。
実行時にプログラムから参照・編集するディレクトリで、手動で変更する必要はありません。
./public/**
./public/post-assets 以外の ./public 内のフォルダは任意に使ってください。
サンプルでは、./public/images にロゴ、OGP 画像などを置いています。
./scripts
./scripts には、shell から 直接実行するためのスクリプト をまとめています。
現時点では、Vault Blog Core による記事投稿までの手順で使用した run-update-posts.sh と、RSS 生成用の postbuild.ts などが置かれています。
config、lib の重複について
config、lib はそれぞれ2か所に存在します。
./config、./src/config./lib、./src/lib
これは、主に記事データ収集時に実行する ./scripts から依存する部分を ./config、./lib にまとめているためです。
逆に ./scripts からの依存がない部分を ./src/config、./src/lib に集め、フロントエンドの処理をできるだけ ./src 内で完結するようにしています。
RSS 生成用の関数は URL に依存するため ./src/lib においています。
ここだけ ./scripts/postbuild.ts から ./src への依存が発生しており、のちに修正するかもしれません。
./src
./src 内は、Next.js や React を使ったアプリケーションの 実装コードを集約 する場所です。
主に以下の役割を持ちます。
./src/app
Next.js の App Router 構造に対応したディレクトリです。
ページ単位のコードを格納します。
サンプルでは下記のような構成になっています。
about- 「サイトについて」ページ
posts
記事ページ関連page- 記事一覧ページのページネーション
[slug]- 個別記事ページ
収集した記事の slug に応じてページ生成
- 個別記事ページ
tags- タグ一覧ページ
[tag]- 特定タグの一覧ページ
収集した記事の tag に応じてページを生成
- 特定タグの一覧ページ
./src/components
UI コンポーネントをまとめる場所。
サンプルでは、記事一覧コンポーネント post-list.tsx や記事カードコンポーネント post-card.tsx などを用意しています。
コンポーネントについては、本当はもっとちゃんと作ったほうが良いと思います。
サンプルにも後で追加するかも。
./src/config
./config と似ていますが、こちらは ./src 内で完結する設定 を置きます。
サンプルでは、各ページの metadata のテンプレートと、ページネーションの設定を置いています。
./src/lib
./lib と似ていますが、こちらは ./src 内で完結する機能 を置きます。
サンプルでは
- 記事一覧、隣接記事、関連記事などを取得する関数
- 必要な情報からページの URL を生成する関数
- Markdown を HTML に変換する関数
などを置いています。
フロントエンドの実装では、このディレクトリにある関数を使ってデータを取得してください。
特に下記ファイルは便利だと思います。
blog-utils.ts- 記事、タグの情報を整理して返す関数など
- サンプルでも多くの
page.tsxで使用
markdown-to-html.ts- Markdown 文字列を HTML に変換する関数
- サンプルでは
./src/app/pages/[slug]/page.tsxで使用
先述の通り、./src/lib と ./src/config は、フロントエンド側だけで完結する処理を集約しています。
一方で ./lib や ./config は、記事収集やビルド用のスクリプトからも参照されることを意図しています。
./types
TypeScript 用の型定義ファイルを置くディレクトリです。
現在は、記事データ型、記事メタデータ型などを置いています。
まとめ
ここまでの内容を整理すると、Vault Blog Core のディレクトリ構成と役割は下記のようにまとめられます。
| ディレクトリ | 役割 | 手動編集の可否 | 備考 |
|---|---|---|---|
./config |
記事収集やスクリプト用の設定 | ❌(一部✅) | パス設定やファイル形式、can-publish.ts は編集可 |
./lib |
記事収集やスクリプト用の関数群 | ❌ | ./scripts から参照される関数 |
./data |
Markdown 収集時に生成される JSON メタデータ | ❌ | 自動生成、手動変更不可 |
./posts |
収集した Markdown 記事 | ❌ | 初期化・上書きされる |
./public |
公開用の画像・音声・動画 | ✅ | post-assets は自動生成、その他は任意 |
./public/post-assets |
収集したアセット格納 | ❌ | 自動生成、手動変更不可 |
./scripts |
shell や Node スクリプト | ✅ | 記事収集、RSS 生成など |
./src/app |
Next.js ページコード | ✅ | 任意に編集可、ルーティングや見た目を決める |
./src/components |
UI コンポーネント | ✅ | 共通コンポーネントを配置 |
./src/config |
フロントエンド用設定 | ✅ | ページメタ情報、ページネーション設定 |
./src/lib |
フロントエンド用関数 | ❌ | 編集したい場合、ラッパー関数などでの実装を推奨 |
./types |
TypeScript 型定義 | ✅ | 記事データ型、フロントマター型など |
ディレクトリ間の依存関係イメージ
./scripts→./config/./lib/./data/./posts/./public/post-assets./src/app→./src/components/./src/config/./src/lib/./data./src/lib→./src/config/./config/lib/./data/./posts./src/config→ 無し./data/./posts/./public/post-assetsは自動生成・ビルド依存
この構造により、記事収集・ビルド処理とフロントエンド表示処理が明確に分離され、管理や拡張がしやすくなっています。