pagemeta2md

A powerful Node.js CLI tool that generates Markdown files with frontmatter from CSV data and hierarchical directory structures. Perfect for creating documentation sites, blogs, or any content management system that uses Markdown files with metadata.

Features

• 🚀 CSV to Markdown: Convert CSV data into structured Markdown files with frontmatter
• 📁 Hierarchical Structure: Automatically create directory structures based on parent-child relationships
• 🔄 Smart Updates: Update existing files while preserving content, only modifying frontmatter
• 🎨 Template Support: Use custom templates or built-in defaults for file generation
• ⚡ Interactive Mode: Confirmation prompts for file overwrites with force option
• 📊 Detailed Logging: Comprehensive progress tracking and error reporting
• 🛡️ Error Handling: Robust validation and error recovery

Installation

Global Installation (Recommended)

npm install -g pagemeta2md

Using pnpm

pnpm add -g pagemeta2md

Using yarn

yarn global add pagemeta2md

Quick Start

1. Prepare your CSV file with hierarchical data:

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. Run the command:

pagemeta2md data.csv

3. Generated structure:

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

Usage

Basic Usage

pagemeta2md <csvFile>

Advanced Usage

pagemeta2md [options] <csvFile>

Options:
  -o, --output <dir>      Output directory (default: "./contents")
  -t, --template <file>   Custom template file for markdown generation
  -f, --force            Overwrite existing files without confirmation
  -v, --verbose          Enable verbose logging
  -h, --help             Display help information
  --version              Show version number

Examples

Example 1: Basic Generation

# Generate files in default ./contents directory
pagemeta2md pages.csv

Example 2: Custom Output Directory

# Generate files in custom directory
pagemeta2md pages.csv --output ./docs

Example 3: Using Custom Template

# Use custom template for file generation
pagemeta2md pages.csv --template ./templates/custom.md

Example 4: Force Overwrite with Verbose Logging

# Overwrite existing files and show detailed logs
pagemeta2md pages.csv --force --verbose

Example 5: Complete Workflow

# Complete setup with all options
pagemeta2md data.csv \
  --output ./documentation \
  --template ./templates/doc-template.md \
  --verbose

CSV Format

Your CSV file should contain the following columns:

Required Columns

• slug: URL-friendly identifier for the file/page
• title: Display title for the page

Optional Columns

• parent: Parent slug for hierarchical structure (empty for root items)
• sidebar_position: Numeric position for ordering
• status: Publication status (draft, published, etc.)
• post_type: Type of content (pages, posts, etc.)
• seo_title: SEO-optimized title
• seo_description: Meta description for SEO
• seo_keywords: Keywords for SEO
• handson_overview: Additional metadata field

Example CSV Structure

sidebar_position,slug,parent,title,status,post_type,seo_title,seo_keywords,seo_description,handson_overview
1,introduction,,Introduction,published,pages,Introduction to Our Platform,intro guide,Welcome to our comprehensive guide,Getting started overview
2,basics,introduction,Basic Concepts,published,pages,Basic Concepts Guide,basics fundamentals,Learn the fundamental concepts,Core concepts explanation
3,advanced,introduction,Advanced Topics,draft,pages,Advanced Guide,advanced topics,Deep dive into advanced features,Advanced usage patterns
4,api,,API Reference,published,pages,API Documentation,api reference,Complete API documentation,API usage guide
5,authentication,api,Authentication,published,pages,API Authentication,auth api,Authentication methods,How to authenticate

Templates

Default Template

If no template is specified, pagemeta2md uses a built-in template:

---
title: "{{title}}"
slug: "{{slug}}"
sidebar_position: { { sidebar_position } }
seo_title: "{{seo_title}}"
seo_description: "{{seo_description}}"
seo_keywords: "{{seo_keywords}}"
status: "{{status}}"
post_type: "{{post_type}}"
handson_overview: "{{handson_overview}}"
---

# {{title}}

<!-- Content goes here -->

Custom Templates

Create your own template using {{column_name}} placeholders:

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

# {{title}}

{{#if handson_overview}}

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

<!-- Your content here -->

File Processing Behavior

New Files

• Creates new Markdown files with frontmatter from CSV data
• Uses template content for the body

Existing Files

• Preserves existing content in the file body
• Updates only the frontmatter with new CSV data
• Prompts for confirmation unless --force is used

Directory Structure

• Automatically creates nested directories based on parent relationships
• Generates index.md files for parent items
• Creates individual .md files for leaf items

Error Handling

The tool provides comprehensive error handling:

• File Validation: Checks if CSV and template files exist
• CSV Validation: Validates required columns and data format
• Circular Reference Detection: Prevents infinite loops in parent-child relationships
• Permission Checks: Validates write permissions for output directories
• Detailed Error Messages: Shows line numbers and specific error details

Development

This project uses pnpm for package management.

Setup

# Clone the repository
git clone https://github.com/username/pagemeta2md.git
cd pagemeta2md

# Install dependencies
pnpm install

Available Scripts

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Lint code
pnpm lint

# Format code
pnpm format

# Build for production
pnpm build

# Run in development mode
pnpm dev

Testing

# Run all tests
pnpm test

# Run specific test file
pnpm test csvParser.test.js

# Run tests in watch mode
pnpm test:watch

# Generate coverage report
pnpm test:coverage

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: pnpm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Changelog

See CHANGELOG.md for a detailed history of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Related Projects

• gray-matter - Parse front-matter from a string or file
• csv-parser - Streaming CSV parser
• commander.js - Node.js command-line interfaces

Made with ❤️ by the pagemeta2md team