Markdown File Editing Guide

Overview

This guide explains how to edit product markdown files for Mercari Shops. Each product has its own markdown file containing the product title, images, and description. By editing these files, you can update your product listings efficiently.

File Structure

Each markdown file consists of two main sections:

---
title: Product Name Here
image1: image-slug-here
image2: another-image-slug
...
---

Product description content goes here...

1. Frontmatter (Top Section)

The section between --- markers contains metadata:

title: Product name
image1-image20: Product images

2. Content (Bottom Section)

Everything after the frontmatter is your product description.

Frontmatter Fields

Title Field

The title field sets your product name in Mercari Shops.

Format:

title: "Your Product Name"

Rules:

Maximum 100 characters
Use quotes if your title contains special characters
This becomes the product listing title

Example:

title: "OXI ONE MK2 Black - Advanced Sequencer Module"

Image Fields

You can specify up to 20 product images using image1 through image20.

Basic Format:

image1: oxi-one-black
image2: oxi-one-detail
image3: ""  # Empty means no image

How Images Work

Image Slugs: Use the image identifier from your image library (e.g., rail-nuts2)
Empty Values: Use "" or leave blank for no image
Order Matters: Images display in numerical order
PRESERVED ON SYNC: Image fields are NEVER overwritten when syncing from CSV. Your image data is safe!
URL Generation: When converting to CSV, slugs become full URLs:
- Markdown: image1: rail-nuts2
- CSV: https://takazudomodular.com/images/p/rail-nuts2/mercari.png

Special Control Flags

The system uses intelligent flags to control image updates based on Mercari’s requirements:

Smart Update Logic

The system automatically determines whether to upload an image based on its current registration status in Mercari:

Your Markdown	Mercari Status	What Happens	CSV Output
`image1: oxi-one-black`	Not registered	Uploads image	URL with flag=2
`image1: oxi-one-black`	Already registered	Keeps existing	Empty with flag=1
`image1: oxi-one-black R`	Any status	Forces replacement	URL with flag=2
`image1: D`	Any status	Deletes image	Empty with flag=3

Replace Flag (R)

Add R (space + R) after the slug to force replace an existing image:

image2: new-product-image R

When to use:

When you want to update an image that’s already registered in Mercari
When the image file has changed but the filename is the same
When you need to force a re-upload regardless of registration status

How it works:

Sets 商品画像更新フラグ_2 to 2 (変更あり)
Includes the full URL in 商品画像名_2
After conversion, the R flag is automatically removed

Delete Flag (D)

Use D to remove an image from that position:

image3: D

When to use:

To remove an unwanted image from your Mercari listing
To clear an image slot for future use

How it works:

Sets 商品画像更新フラグ_3 to 3 (削除)
Leaves 商品画像名_3 empty
After conversion, the field becomes image3: ""

Automatic Flag Cleanup

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

Removes all R and D flags from your markdown files
Preserves the image slugs (without flags) for reference
Clears deleted images (D becomes "")

You never need to manually remove these flags! :::

Example of automatic cleanup:

# Your edit (with flags)
image1: oxi-one-front
image2: oxi-one-detail R    # Force replace
image3: oxi-one-patch
image4: D                    # Delete this image

# After conversion (automatically cleaned)
image1: oxi-one-front
image2: oxi-one-detail       # R flag removed
image3: oxi-one-patch
image4: ""                   # D converted to empty

Understanding Registration Status

The system reads Mercari’s 商品画像登録有無_X field to determine registration status:

1 = Image is registered (already uploaded)
2 = Image is not registered (empty slot)

Based on this status, the system intelligently decides whether to include the URL in the CSV output, ensuring efficient updates without unnecessary re-uploads.

Content Section

The content section contains your product description in markdown format.

Supported Formatting

Bold text: **text**
Italic text: *text*
Line breaks: Leave a blank line between paragraphs
Lists: Use - or * for bullet points
Headers: Use #, ##, ### for different heading levels

Character Limit

Maximum 5000 characters for the entire description
Line breaks and formatting marks count toward the limit

Example Description

High-performance sequencer module with advanced features.

**Key Features:**
- 64 steps per pattern
- 8 tracks of sequencing
- Probability and ratcheting
- USB connectivity

**Specifications:**
- Width: 24HP
- Depth: 38mm
- Power: +12V 140mA, -12V 20mA

Perfect for complex rhythmic patterns and melodic sequences.

Complete File Example

Here’s a complete product markdown file:

---
title: "OXI ONE MK2 Black - Advanced Sequencer"
image1: oxi-one-black-front
image2: oxi-one-black-detail
image3: oxi-one-black-side
image4: oxi-one-in-system
image5: ""
image6: ""
image7: ""
image8: ""
image9: ""
image10: ""
image11: ""
image12: ""
image13: ""
image14: ""
image15: ""
image16: ""
image17: ""
image18: ""
image19: ""
image20: ""
---

Professional-grade sequencer module with unmatched flexibility.

**OXI ONE MK2** brings studio-quality sequencing to your modular system with an intuitive interface and powerful features.

## Main Features

- **64 steps** per pattern with individual step parameters
- **8 independent tracks** for complex compositions
- **Probability sequencing** for evolving patterns
- **Multiple play modes** including random and pendulum
- **Built-in arpeggiator** with various modes

## Connectivity

- 8 CV outputs
- 8 Gate outputs
- USB host and device ports
- MIDI in/out/thru
- Sync input/output

## Technical Specifications

- Width: 24HP
- Depth: 38mm (including power cable)
- Power consumption: +12V 140mA, -12V 20mA

Includes power cable and mounting screws.

Editing Examples

Example 1: Adding New Images

Before:

image1: oxi-one-front
image2: ""
image3: ""

After (adding two more images):

image1: oxi-one-front
image2: oxi-one-detail
image3: oxi-one-patch

Example 2: Replacing an Existing Image

Before:

image1: old-product-photo
image2: detail-shot

After (forcing replacement of first image):

image1: new-product-photo R
image2: detail-shot

After processing, the R will be removed automatically:

image1: new-product-photo
image2: detail-shot

Example 3: Removing Images

Before:

image1: product-front
image2: product-back
image3: product-detail

After (removing the third image):

image1: product-front
image2: product-back
image3: D

After processing:

image1: product-front
image2: product-back
image3: ""

Important Notes

What NOT to Edit

Never change:

The filename of the markdown file
The --- markers around frontmatter
Any system-generated metadata (if present)

Image Data Preservation

:::info Image Fields are Protected When you run pnpm mdsync:csv-to-md, the system will:

UPDATE: title and description from the CSV
PRESERVE: All image1-image20 fields exactly as they are

This means you can safely edit image fields in markdown without fear of losing them during CSV sync. The image data is your permanent record, while title/description sync bidirectionally with Mercari. :::

When Changes Take Effect

Changes are processed when you run the sync command
Allow a few minutes for updates to appear in Mercari Shops
Check the preview before syncing to verify your changes

Backup Recommendations

Keep copies of your markdown files before major edits
Save the previous version if making significant changes
Consider version control (Git) for tracking changes

Tips for Success

Image Management

Organize your images: Use clear, descriptive slugs
Order matters: Put your best images first
Use all slots wisely: More images can increase sales
Test replacements: Use the R flag when updating existing products

Description Writing

Be clear and concise: Buyers scan quickly
Use formatting: Bold text for important features
Include specifications: Technical details matter
Add keywords naturally: Help buyers find your products

Workflow Tips

Edit one product at a time initially
Preview before syncing to catch errors
Keep descriptions under 4000 characters for safety
Use consistent formatting across products

Troubleshooting

Common Issues

Images not updating?

Check if you need the R flag to force replacement
Verify the image slug is correct
Ensure the image exists in your library

Title too long?

Keep under 100 characters
Remove unnecessary words
Use standard abbreviations

Description formatting lost?

Check your markdown syntax
Ensure proper line breaks between paragraphs
Verify special characters are escaped

Getting Help

If you encounter issues:

Check this guide first
Verify your markdown syntax
Review the preview before syncing
Keep backups of working versions

Summary

Editing markdown files gives you powerful control over your Mercari product listings. Remember:

Frontmatter controls title and images
Content is your product description
Special flags (R, D) handle updates and deletions
Preview before syncing to production

With practice, you’ll be able to quickly update your entire product catalog efficiently!