Product Markdown Sync

Product Markdown Sync

Overview

Product Markdown Sync is a Node.js sub-package that will provide bidirectional synchronization between Mercari Shops CSV exports and markdown files for managing existing product descriptions. This tool will replace the existing generate-product-markdown.mjs script with a more comprehensive solution.

The system works exclusively with Mercari’s 162-column export format, which contains all information about already-registered products. It extracts product descriptions to markdown files for easy editing, then applies the changes back to the original CSV for re-upload to Mercari Shops.

Official Mercari Documentation: CSV File Format for Bulk Product Updates

Implementation Status: This sub-package is planned for development. The commands pnpm mdsync:csv-to-md and pnpm mdsync:md-to-csv will be available from the root directory once implemented.

The Problem It Solves

Managing Existing Products in CSV

When managing already-registered products in Mercari Shops, users must:

1. Download CSV Export: Get the 162-column CSV containing all product information
2. Edit Product Data: Modify descriptions, prices, or other fields
3. Re-upload CSV: Import the updated CSV back to Mercari Shops

CSV Editing Challenges

Editing the exported CSV directly presents several difficulties:

• Unwieldy Format: 162 columns make the CSV extremely wide and hard to navigate
• Description Field: Long product descriptions are cramped in a single cell
• No Formatting Preview: Cannot see how descriptions will appear
• Error-Prone: Easy to accidentally modify wrong cells or break CSV structure
• Poor Readability: Multi-line content with escaped characters is hard to read

Our Solution

Product Markdown Sync streamlines this workflow:

1. Extract to Markdown: Convert product descriptions from CSV to individual markdown files
2. Easy Editing: Edit descriptions in your favorite text editor with markdown preview
3. Apply Changes: Sync edited markdown back to the original CSV
4. Upload Ready: Updated CSV maintains correct format for Mercari Shops import

Benefits:

• Organized Files: One markdown file per product for easy navigation
• Version Control: Track changes to product descriptions in Git
• Bulk Editing: Use find/replace across multiple product files
• Visual Editing: See formatted output while editing
• Preserve Structure: CSV structure remains intact, only descriptions are updated

Key Features

CSV to Markdown Conversion

Extracts product descriptions from Mercari CSV exports and creates individual markdown files:

# Convert CSV to markdown files
pnpm mdsync:csv-to-md

Expected behavior:

1. Automatically finds the latest CSV export file (162 columns) from /mercari-data/
2. For each product in the CSV:

• If markdown file exists: PRESERVES image1-image20 fields in frontmatter
• Updates only title and description from CSV
• Creates new files with product ID as filename

3. Saves to /sub-packages/zmdpreview/docs/products/ directory

Critical: Image fields (image1-image20) are NEVER overwritten during CSV-to-MD sync. These fields contain our permanent image management data that Mercari CSV exports don’t preserve.

Markdown to CSV Update

Updates the original 162-column CSV with edited markdown content for re-upload to Mercari Shops:

# Convert markdown back to CSV
pnpm mdsync:md-to-csv

Expected behavior:

1. Reads all markdown files from /sub-packages/zmdpreview/docs/products/
2. Loads the original 162-column CSV export from /mercari-data/
3. For each product, updates from markdown:

• 商品名 (title) from frontmatter
• 商品説明 (description) from content body
• Image columns with full URLs generated from slugs

4. Preserves all other CSV fields unchanged
5. Saves updated 162-column CSV to /mercari-data/updated/ with timestamp

Image Handling System

Image URL Generation:

• Markdown stores image slugs: rail-nuts2
• CSV gets full URLs: https://takazudomodular.com/images/p/rail-nuts2/mercari.png
• URL pattern: https://takazudomodular.com/images/p/{slug}/mercari.png

Smart Image Flag Logic:

The system intelligently handles image updates based on the current registration status:

Special Flags (Temporary):

• R flag: Forces image replacement even if already registered
• D flag: Deletes the image from Mercari
• These flags are automatically removed after conversion

Post-Processing: After md-to-csv conversion, the system automatically:

1. Removes all R and D flags from markdown files
2. Preserves the image slugs for future reference
3. Updates the markdown files to reflect the clean state

Example transformation:

# Before conversion
image1: rail-nuts
image2: rail-nuts2 R
image3: connector1
image4: D

# After conversion (auto-cleaned)
image1: rail-nuts
image2: rail-nuts2
image3: connector1
image4: ""

File Structure

Directory Organization

/mercari-data/
├── product_data_2025-08-02.csv     # Original export from Mercari (162 columns)
└── updated/                         # Updated 162-column CSVs ready for re-upload
    └── 20250810-1754854393.csv

/sub-packages/zmdpreview/docs/products/
├── oxi-one-black__rkJCVU3DDBrbvCV5gSJqed.md
├── zudo-rail-40-dual-set1__MHQ75HutwN7fC7zGxhAjk7.md
└── ... (one file per product)

Markdown File Naming

Files follow a strict naming convention:

{product-slug}__{mercariProductId}.md

• product-slug: URL-friendly product identifier from master data
• mercariProductId: Unique 22-character ID from Mercari (e.g., rkJCVU3DDBrbvCV5gSJqed)

This dual-key system ensures:

• Files are human-readable (via slug)
• Programmatic matching is reliable (via Mercari ID)
• No naming conflicts occur

CSV File Reading Requirements

CSV File Location and Naming Convention

The system reads CSV files from the /mercari-data/ directory with a strict naming convention:

product_data_YYYY-MM-DD.csv

Examples:

• product_data_2025-09-14.csv (latest)
• product_data_2025-08-10.csv (historical)
• product_data_2025-08-02.csv (historical)

Critical: Always Use Latest Date File

:::danger Important Requirement The application MUST always detect and use the CSV file with the most recent date in the filename. Using older CSV files will cause data inconsistency and inventory management issues. :::

Purpose of Historical Files

Older CSV files in the /mercari-data/ directory serve as:

• Backup records: Historical snapshots of product data
• Stock tracking: Log of inventory changes over time
• Recovery points: Ability to restore previous states if needed
• Audit trail: Documentation of price and description evolution

:::warning Data Consistency Warning Using an outdated CSV file as the source will result in:

• Reverting price changes to old values
• Overwriting updated product descriptions
• Losing recent inventory adjustments
• Creating conflicts with current Mercari Shops data :::

Implementation Details: File Detection Logic

The application should implement robust file detection to ensure the latest CSV is always selected:

// Example implementation for detecting latest CSV file
const fs = require('fs').promises;
const path = require('path');

async function getLatestCSVFile(directory = '/mercari-data/') {
  // Read all files in the directory
  const files = await fs.readdir(directory);
  
  // Filter for CSV files matching the pattern
  const csvFiles = files.filter(file => {
    return /^product_data_\d{4}-\d{2}-\d{2}\.csv$/.test(file);
  });
  
  if (csvFiles.length === 0) {
    throw new Error('No CSV files found in /mercari-data/ directory');
  }
  
  // Extract dates and sort to find the latest
  const filesWithDates = csvFiles.map(file => {
    const match = file.match(/product_data_(\d{4}-\d{2}-\d{2})\.csv/);
    return {
      filename: file,
      date: match[1],
      timestamp: new Date(match[1]).getTime()
    };
  });
  
  // Sort by timestamp descending (newest first)
  filesWithDates.sort((a, b) => b.timestamp - a.timestamp);
  
  const latestFile = filesWithDates[0];
  console.log(`Selected latest CSV: ${latestFile.filename} (${latestFile.date})`);
  
  return path.join(directory, latestFile.filename);
}

File Selection Verification

Before processing, the system should:

1. Display selected file: Show which CSV file was detected as the latest
2. Confirm date: Display the date extracted from the filename
3. Log file size: Verify the file is not empty or corrupted
4. Optional confirmation: In interactive mode, ask user to confirm the selection

// Example verification output
console.log('================================================');
console.log('CSV File Selection:');
console.log(`  File: product_data_2025-09-14.csv`);
console.log(`  Date: 2025-09-14`);
console.log(`  Size: 2.4MB`);
console.log(`  Rows: 247 products`);
console.log('================================================');

Edge Cases and Error Handling

The implementation must handle these scenarios:

• No CSV files found: Provide clear error message with expected format
• Multiple files same date: Use additional timestamp or prompt user
• Corrupted filename: Skip files not matching the pattern exactly
• Empty directory: Guide user to download and save CSV first

:::tip Best Practice Always validate the CSV structure after loading to ensure it’s the expected 162-column Mercari export format before proceeding with any data operations. :::

Usage Commands

Complete Workflow for Managing Existing Products

1. Export Current Products from Mercari Shops

• Log into Mercari Shops admin panel
• Export all existing products (162-column CSV)
• Save as product_data_YYYY-MM-DD.csv in /mercari-data/

2. Extract Descriptions to Markdown

   pnpm mdsync:csv-to-md

   Creates individual markdown files for each product’s description.

3. Edit Product Descriptions

• Open markdown files in your preferred editor
• Edit and organize product descriptions
• Use markdown formatting for better structure
• Save files (UTF-8 encoding preserved)

4. Apply Changes Back to CSV

   pnpm mdsync:md-to-csv

   Updates the original 162-column CSV with edited descriptions.

5. Re-upload to Mercari Shops

• Use updated CSV from /mercari-data/updated/
• Import through Mercari Shops admin panel
• Only descriptions are changed; all other data preserved

Advanced Features (Planned)

Selective Processing:

# Process only products with changes
pnpm mdsync:csv-to-md -- --changed-only

# Process specific product by slug
pnpm mdsync:csv-to-md -- --slug oxi-one-black

Validation:

# Validate markdown files match CSV data
pnpm mdsync:validate

These features will be part of the complete implementation in the Product Markdown Sync sub-package.

Benefits of Using This Tool

For Content Management

1. Easier Editing

• Use your favorite text editor (VS Code, Sublime, etc.)
• Live markdown preview while editing
• Spell check and grammar tools work naturally
• Multi-file search and replace capabilities

2. Better Organization

• One file per product - easy to find and manage
• Files named with readable slugs
• Can organize into subdirectories if needed
• Quick backup and restore of descriptions

For Version Control

1. Clean Diffs

• See exactly what changed in descriptions
• Review changes before committing
• Track edit history per product
• Easy rollback to previous versions

2. Collaboration

• Multiple people can edit different products simultaneously
• Merge conflicts are easier to resolve in markdown
• Comments and suggestions via pull requests
• Maintain audit trail of changes

For Data Integrity

1. Backup System

• Descriptions stored separately from volatile CSV data
• Protection against accidental CSV corruption
• Easy to restore individual product descriptions
• Can maintain multiple versions

2. Format Preservation

• No character encoding issues
• Preserves formatting that CSV might lose
• Handles special characters and emojis correctly
• Maintains line breaks and paragraph structure

For Workflow Efficiency

1. Batch Operations

• Update multiple products at once
• Find and replace across all descriptions
• Apply consistent formatting rules
• Automate repetitive changes

2. Integration Options

• Can integrate with translation services
• Automated quality checks possible
• Connect to CMS or other systems
• Export to different formats as needed

Technical Details

CSV Format Specifications

Export Format (162 columns):

• Encoding: UTF-8 with BOM
• Key fields: Product ID (column 1), Description (column 64), Price (column 146)
• Contains full product data including 10 SKUs and 20 image URLs

Import Format (72 columns):

• Strict column requirement for Mercari import
• Numeric codes for status fields (not text values)
• Must include UTF-8 BOM for proper Japanese text handling

Character Encoding

• CSV Files: UTF-8 with BOM (required for Mercari)
• Markdown Files: UTF-8 without BOM
• Special Characters: Full Unicode support including emojis
• Line Endings: LF (Unix-style) preferred

Libraries Used

• Papa Parse: Robust CSV parsing with Japanese text support
• Node.js fs/promises: Asynchronous file operations
• Path utilities: Cross-platform path handling

Future Enhancements

• Automated markdown to CSV synchronization
• Real-time preview of changes
• Bulk editing interface
• Integration with product master data updates
• Automatic backup system
• Change tracking and history
• Validation and error reporting
• Support for product images in markdown

Related Tools

• Mercari Viewer: Web interface for CSV viewing and editing
• Products Viewer: Product master data management tool
• Update Mercari Prices: Script for syncing prices from CSV to master data

This tool is essential for maintaining high-quality product descriptions while working within the constraints of e-commerce platform data formats.

Related Pages