Package Exports

pagemeta2md
pagemeta2md/src/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (pagemeta2md) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

クイックスタート

階層データを含む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

コマンドを実行:

pagemeta2md data.csv

生成される構造:

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

貢献

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

開発ワークフロー

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

変更履歴

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

ライセンス

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

pagemeta2md

Package Exports

Readme

pagemeta2md

機能

順方向変換（CSV → Markdown）

逆方向変換（Markdown → CSV）

共通機能

インストール

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

pnpmを使用

yarnを使用

クイックスタート

使用方法

コマンド概要

CSV → Markdown変換

Markdown → CSV変換

例

CSV → Markdown変換の例

例1: 基本的な生成

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

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

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

Markdown → CSV変換の例

例1: 新規CSV生成

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

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

例4: カスタム列選択

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

CSVフォーマット

必須列

オプション列

CSVサンプル構造

テンプレート

デフォルトテンプレート

カスタムテンプレート

ファイル処理動作

新規ファイル

既存ファイル

ディレクトリ構造

エラーハンドリング

開発

セットアップ

利用可能なスクリプト

テスト

貢献

開発ワークフロー

変更履歴

ライセンス

サポート

関連プロジェクト