pagemeta2md

CSVファイルとMarkdownファイル間の双方向変換を行う強力なNode.js CLIツールです。CSVデータからフロントマター付きMarkdownファイルの生成と、既存のMarkdownファイル構造からCSVファイルの生成の両方に対応。ドキュメントサイト、ブログ、またはメタデータを使用するMarkdownファイルベースのコンテンツ管理システムの作成・管理に最適です。

機能

順方向変換（CSV → Markdown）

• 🚀 CSV to Markdown: CSVデータをフロントマター付きの構造化されたMarkdownファイルに変換
• 📁 階層構造: 親子関係に基づいてディレクトリ構造を自動作成
• 🔄 スマートアップデート: コンテンツを保持しながら既存ファイルを更新、フロントマターのみを変更
• 🎨 テンプレートサポート: カスタムテンプレートまたは組み込みデフォルトを使用してファイル生成

逆方向変換（Markdown → CSV）

• 🔄 Markdown to CSV: 既存のMarkdownファイル構造をCSVファイルに変換
• 📊 順序保持: 既存CSVファイルの行順序を維持した差分更新
• 🔍 自動階層解析: ファイルパスとフロントマターから親子関係を自動検出
• 🎯 フィルタリング: include/excludeパターンでファイル選択
• ⚡ 差分検出: frontmatter更新、ファイル追加・削除を効率的に検出

共通機能

• ⚡ インタラクティブモード: ファイル上書き時の確認プロンプトとフォースオプション
• 📊 詳細ログ: 包括的な進捗追跡とエラーレポート
• 🛡️ エラーハンドリング: 堅牢なバリデーションとエラー回復
• 🔗 循環参照検出: 階層構造の整合性チェック

インストール

グローバルインストール（推奨）

npm install -g pagemeta2md

pnpmを使用

pnpm add -g pagemeta2md

yarnを使用

yarn global add pagemeta2md

クイックスタート

1. 階層データを含むCSVファイルを準備:

sidebar_position,slug,parent,title,status,post_type,seo_title,seo_keywords,seo_description,handson_overview
1,getting-started,,Getting Started,published,pages,Getting Started Guide,tutorial guide,Learn how to get started,Introduction to the platform
2,installation,getting-started,Installation,published,pages,Installation Guide,install setup,Step-by-step installation,How to install the software
3,configuration,getting-started,Configuration,draft,pages,Configuration Guide,config setup,Configuration options,Setting up your environment

2. コマンドを実行:

pagemeta2md data.csv

3. 生成される構造:

contents/
├── getting-started/
│   ├── index.md
│   ├── installation.md
│   └── configuration.md

使用方法

コマンド概要

# ヘルプを表示
pagemeta2md --help

# CSV → Markdown変換
pagemeta2md csv2md <csvFile>

# Markdown → CSV変換
pagemeta2md md2csv <inputDir> <outputCsv>

# 後方互換性（従来の使用方法）
pagemeta2md <csvFile>

CSV → Markdown変換

pagemeta2md csv2md [options] <csvFile>

オプション:
  -o, --output <dir>      出力ディレクトリ (デフォルト: "./contents")
  -t, --template <file>   Markdownファイル生成用のカスタムテンプレートファイル
  -f, --force            確認なしで既存ファイルを上書き
  -v, --verbose          詳細ログを有効化

Markdown → CSV変換

pagemeta2md md2csv [options] <inputDir> <outputCsv>

オプション:
  --update-mode          既存CSVファイルの順序を保持した差分更新
  --base-csv <file>      差分更新のベースとなる既存CSVファイル
  --columns <list>       出力するCSV列（カンマ区切り）
  --include <pattern>    含めるファイルパターン（glob）(デフォルト: "**/*.md")
  --exclude <pattern>    除外するファイルパターン（カンマ区切り）
  --sort <field>         ソートフィールド（update-mode時は無効）
  --encoding <type>      出力エンコーディング (デフォルト: "utf8")
  --delimiter <char>     CSV区切り文字 (デフォルト: ",")
  --handle-deleted <action>  削除ファイルの処理（warn/remove/ignore）
  -v, --verbose          詳細ログを有効化

例

CSV → Markdown変換の例

例1: 基本的な生成

# デフォルトの./contentsディレクトリにファイルを生成
pagemeta2md csv2md pages.csv

例2: カスタム出力ディレクトリ

# カスタムディレクトリにファイルを生成
pagemeta2md csv2md pages.csv --output ./docs

例3: カスタムテンプレートの使用

# ファイル生成にカスタムテンプレートを使用
pagemeta2md csv2md pages.csv --template ./templates/custom.md

例4: 詳細ログ付きでの強制上書き

# 既存ファイルを上書きし、詳細ログを表示
pagemeta2md csv2md pages.csv --force --verbose

Markdown → CSV変換の例

例1: 新規CSV生成

# contentsディレクトリのMarkdownファイルから新しいCSVを生成
pagemeta2md md2csv contents output.csv

例2: 既存CSVの差分更新（順序保持）

# 既存CSVファイルの順序を保持しながら更新
pagemeta2md md2csv contents updated.csv --update-mode --base-csv existing.csv

例3: フィルタリングを使用した変換

# 特定のパターンのファイルのみを変換
pagemeta2md md2csv contents docs.csv \
  --include "docs/**/*.md" \
  --exclude "drafts/**,temp/**"

例4: カスタム列選択

# 特定の列のみを含むCSVを生成
pagemeta2md md2csv contents minimal.csv \
  --columns "slug,title,parent,status"

例5: 詳細ログと削除ファイル処理

# 詳細ログを表示し、削除されたファイルをCSVからも削除
pagemeta2md md2csv contents output.csv \
  --update-mode \
  --base-csv existing.csv \
  --handle-deleted remove \
  --verbose

CSVフォーマット

CSVファイルには以下の列を含める必要があります：

必須列

• slug: ファイル/ページのURL対応識別子
• title: ページの表示タイトル

オプション列

• parent: 階層構造の親スラッグ（ルートアイテムの場合は空）
• status: 公開ステータス（draft、publishedなど）
• filepath: 生成されるMarkdownファイルのカスタムファイルパス
• post_type: コンテンツの種類（pages、postsなど）
• target: コンテンツの対象読者またはコンテキスト
• goal: コンテンツの目的または目標
• seo_title: SEO最適化されたタイトル
• seo_description: SEO用のメタディスクリプション
• seo_keywords: SEO用のキーワード
• handson_overview: 追加のメタデータフィールド

CSVサンプル構造

sidebar_position,slug,parent,title,status,filepath,post_type,target,goal,seo_title,seo_keywords,seo_description,handson_overview
1,introduction,,Introduction,published,,pages,developers,getting-started,Introduction to Our Platform,intro guide,Welcome to our comprehensive guide,Getting started overview
2,basics,introduction,Basic Concepts,published,,pages,beginners,learn-fundamentals,Basic Concepts Guide,basics fundamentals,Learn the fundamental concepts,Core concepts explanation
3,advanced,introduction,Advanced Topics,draft,,pages,experienced-users,master-features,Advanced Guide,advanced topics,Deep dive into advanced features,Advanced usage patterns
4,api,,API Reference,published,docs/api/index.md,pages,developers,api-integration,API Documentation,api reference,Complete API documentation,API usage guide
5,authentication,api,Authentication,published,,pages,developers,secure-access,API Authentication,auth api,Authentication methods,How to authenticate

テンプレート

デフォルトテンプレート

テンプレートが指定されていない場合、pagemeta2mdは組み込みテンプレートを使用します：

---
title: "{{title}}"
slug: "{{slug}}"
parent: "{{parent}}"
status: "{{status}}"
filepath: "{{filepath}}"
post_type: "{{post_type}}"
target: "{{target}}"
goal: "{{goal}}"
seo_title: "{{seo_title}}"
seo_description: "{{seo_description}}"
seo_keywords: "{{seo_keywords}}"
handson_overview: "{{handson_overview}}"
---

<!-- コンテンツをここに記述 -->

カスタムテンプレート

{{column_name}}プレースホルダーを使用して独自のテンプレートを作成できます：

---
title: "{{title}}"
description: "{{seo_description}}"
keywords: [{{seo_keywords}}]
draft: {{#if status === 'draft'}}true{{else}}false{{/if}}
---

# {{title}}

{{#if handson_overview}}

> {{handson_overview}}
> {{/if}}

<!-- ここにコンテンツを記述 -->

ファイル処理動作

新規ファイル

• CSVデータからフロントマターを含む新しいMarkdownファイルを作成
• テンプレートコンテンツをファイル本文に使用

既存ファイル

• ファイル本文の既存コンテンツを保持
• フロントマターのみを新しいCSVデータで更新
• --forceが使用されない限り確認プロンプトを表示

ディレクトリ構造

• parent関係に基づいてネストされたディレクトリを自動作成
• 親アイテムにはindex.mdファイルを生成
• リーフアイテムには個別の.mdファイルを作成

エラーハンドリング

このツールは包括的なエラーハンドリングを提供します：

• ファイル検証: CSVファイルとテンプレートファイルの存在確認
• CSV検証: 必須列とデータフォーマットの検証
• 循環参照検出: 親子関係での無限ループを防止
• 権限チェック: 出力ディレクトリの書き込み権限を検証
• 詳細なエラーメッセージ: 行番号と具体的なエラー詳細を表示

開発

このプロジェクトはパッケージ管理にpnpmを使用しています。

セットアップ

# リポジトリをクローン
git clone https://github.com/username/pagemeta2md.git
cd pagemeta2md

# 依存関係をインストール
pnpm install

利用可能なスクリプト

# テストを実行
pnpm test

# カバレッジ付きでテストを実行
pnpm test:coverage

# コードをリント
pnpm lint

# コードをフォーマット
pnpm format

# プロダクション用にビルド
pnpm build

# 開発モードで実行
pnpm dev

テスト

# すべてのテストを実行
pnpm test

# 特定のテストファイルを実行
pnpm test csvParser.test.js

# ウォッチモードでテストを実行
pnpm test:watch

# カバレッジレポートを生成
pnpm test:coverage

貢献

貢献を歓迎します！詳細については貢献ガイドをご覧ください。

開発ワークフロー

1. リポジトリをフォーク
2. 機能ブランチを作成: git checkout -b feature/amazing-feature
3. 変更を加えてテストを追加
4. テストを実行: pnpm test
5. 変更をコミット: git commit -m 'Add amazing feature'
6. ブランチにプッシュ: git push origin feature/amazing-feature
7. プルリクエストを開く

変更履歴

変更の詳細履歴についてはCHANGELOG.mdをご覧ください。

ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSEファイルをご覧ください。

サポート

• 📖 ドキュメント
• 🐛 Issue Tracker
• 💬 ディスカッション

関連プロジェクト

• gray-matter - 文字列またはファイルからフロントマターを解析
• csv-parser - ストリーミングCSVパーサー
• commander.js - Node.jsコマンドラインインターフェース

pagemeta2mdチームが❤️を込めて作成