peach-markitdown

Document file md conversion skill

MarkItDown과 python-hwpxcombine to convert document files to md.

• MarkItDown From the official scope, inputs adopted by this skill: PDF, PowerPoint, Word, Excel, HTML, CSV, JSON, XML, ZIP, EPUB, images

• Separate handling of this skill: HWPX

• Processing method: single file conversion + folder batch conversion

• PDF, PPTX, DOCX, XLSX, HTML, CSV, JSON, XML, ZIP, EPUB, images: markitdown

• HWPX: python-hwpx -based built-in extractor

• Output: separate folder

• Failure: log file

Scope

This skill handles only the following.

• markitdown Installation/verification
• .venv creation and python-hwpx, lxml installation/verification
• Single file -> md conversion
• Batch conversion of document file bundle folder
• Create result summary and failure log

This skill does not handle the following.

• YouTube transcript extraction
• Audio file transcription
• Speaker diarization
• Document editing
• Document -> PDF conversion
• OCR quality improvement
• HWP/HWPX high-fidelity layout restoration

Execution order

1. Environment preparation

Run from the current working project root.

bash <skill-dir>/scripts/bootstrap.sh

2. Single file conversion

python3 <skill-dir>/scripts/convert_one.py \
  --source "/절대경로/입력파일" \
  --output "/절대경로/출력파일.md"

Example:

python3 <skill-dir>/scripts/convert_one.py \
  --source "$PWD/sample.docx" \
  --output "$PWD/output/sample.md"

3. Folder batch conversion

python3 <skill-dir>/scripts/convert_folder.py \
  --input-dir "/절대경로/입력폴더" \
  --output-dir "/절대경로/출력폴더"

Example:

python3 <skill-dir>/scripts/convert_folder.py \
  --input-dir "$PWD/백업솔루션/원본" \
  --output-dir "$PWD/백업솔루션/md"

Processing rules

Extension	Processing method
.pdf, .pptx, .docx, .xlsx, .xls	markitdown
.html, .csv, .json, .xml, .zip, .epub	markitdown
Image-related extensions	markitdown
.hwpx	extract_hwpx.py --format markdown
Other	Skip + log

Note:

• Some formats may succeed or fail depending on upstream status.
• YouTube transcript는 baoyu-youtube-transcript use the skill.
• For audio transcription and speaker diarization, NotebookLM or a separate audio transcription path is used.

Official support vs current verification

They must be viewed separately.

• MarkItDown The official support scope is broader, but this skill is limited to document files and images
• Current automation scope of this skill: delegate the above formats to markitdown, and HWPXis handled by a separate extractor
• Actually verified in this environment:
  • PDF, PPTX, HWPX Folder batch conversion succeeded
• Items requiring caution in this environment:
  • New formats require single-case verification before practical application

Practical principle:

• "Official support" and "currently verified" are not to be spoken of as having the same meaning.
• Before using a new format in practice, first perform single-case verification with convert_one.py.
• YouTube transcript는 baoyu-youtube-transcriptis used as the default.
• For audio transcription and speaker diarization, NotebookLM or a separate STT path is separated out.

Deliverables

Leave the following files in the output folder.

• Converted .md
• conversion-summary.json
• conversion-errors.log

Operating principles

• Never modify the original file.
• Always write output to a separate folder.
• If a result with the same name exists, overwrite it by default.
• For unsupported files, do not stop with a failure; only log it.