peach-markitdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

문서파일 md 변환 스킬

文档文件转md技能

MarkItDown

과

python-hwpx

를 조합해 문서파일을

md

로 변환한다.

```
MarkItDown
```
공식 범위 중 이 스킬이 채택한 입력:
```
PDF
```
,
```
PowerPoint
```
,
```
Word
```
,
```
Excel
```
,
```
HTML
```
,
```
CSV
```
,
```
JSON
```
,
```
XML
```
,
```
ZIP
```
,
```
EPUB
```
, 이미지
이 스킬의 별도 처리:
```
HWPX
```
처리 방식: 단일 파일 변환 + 폴더 일괄 변환

PDF

PPTX

DOCX

XLSX

HTML

CSV

JSON

XML

ZIP

EPUB

, 이미지:

markitdown

```
HWPX
```
:
```
python-hwpx
```
기반 내장 추출기
출력: 별도 폴더
실패: 로그 파일

通过结合

MarkItDown

和

python-hwpx

将文档文件转换为

md

格式。

本技能采用的
```
MarkItDown
```
官方支持输入格式：
```
PDF
```
,
```
PowerPoint
```
,
```
Word
```
,
```
Excel
```
,
```
HTML
```
,
```
CSV
```
,
```
JSON
```
,
```
XML
```
,
```
ZIP
```
,
```
EPUB
```
, 图片
本技能单独处理的格式：
```
HWPX
```
处理方式：单文件转换 + 文件夹批量转换

PDF

PPTX

DOCX

XLSX

HTML

CSV

JSON

XML

ZIP

EPUB

, 图片：使用

markitdown

处理

```
HWPX
```
：基于
```
python-hwpx
```
的内置提取器
输出：单独文件夹
失败：生成日志文件

범위

适用范围

이 스킬은 아래만 처리한다.

```
markitdown
```
설치/확인
```
.venv
```
생성 및
```
python-hwpx
```
,
```
lxml
```
설치/확인
단일 파일 ->
```
md
```
변환
문서파일 묶음 폴더 일괄 변환
결과 요약과 실패 로그 작성

이 스킬은 아래를 처리하지 않는다.

YouTube transcript 추출
음성 파일 전사
화자 분리
문서 편집
문서 -> PDF 변환
OCR 품질 개선
HWP/HWPX 고충실도 레이아웃 복원

本技能仅处理以下内容：

```
markitdown
```
的安装/验证
创建
```
.venv
```
并安装/验证
```
python-hwpx
```
,
```
lxml
```
单文件 ->
```
md
```
格式转换
批量转换文件夹中的文档文件
生成结果总结和失败日志

本技能不处理以下内容：

YouTube字幕提取
音频文件转写
说话人分离
文档编辑
文档 -> PDF转换
OCR质量提升
HWP/HWPX高保真布局还原

실행 순서

执行步骤

1. 환경 준비

1. 环境准备

현재 작업 프로젝트 루트에서 실행한다.

bash

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

在当前工作项目根目录下执行。

bash

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

2. 단일 파일 변환

2. 单文件转换

bash

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

예시:

bash

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

bash

python3 <skill-dir>/scripts/convert_one.py \
  --source "/绝对路径/输入文件" \
  --output "/绝对路径/输出文件.md"

示例:

bash

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

3. 폴더 일괄 변환

3. 文件夹批量转换

bash

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

예시:

bash

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

bash

python3 <skill-dir>/scripts/convert_folder.py \
  --input-dir "/绝对路径/输入文件夹" \
  --output-dir "/绝对路径/输出文件夹"

示例:

bash

python3 <skill-dir>/scripts/convert_folder.py \
  --input-dir "$PWD/备份方案/原文件" \
  --output-dir "$PWD/备份方案/md"

처리 규칙

处理规则

확장자	처리 방식
`.pdf` , `.pptx` , `.docx` , `.xlsx` , `.xls`	`markitdown`
`.html` , `.csv` , `.json` , `.xml` , `.zip` , `.epub`	`markitdown`
이미지 계열 확장자	`markitdown`
`.hwpx`	`extract_hwpx.py --format markdown`
기타	스킵 + 로그

참고:

일부 포맷은 upstream 상태에 따라 성공 여부가 달라질 수 있다.
YouTube transcript는
```
baoyu-youtube-transcript
```
스킬을 사용한다.
음성 전사와 화자 분리는
```
NotebookLM
```
또는 별도 음성 전사 경로를 사용한다.

扩展名	处理方式
`.pdf` , `.pptx` , `.docx` , `.xlsx` , `.xls`	`markitdown`
`.html` , `.csv` , `.json` , `.xml` , `.zip` , `.epub`	`markitdown`
图片类扩展名	`markitdown`
`.hwpx`	`extract_hwpx.py --format markdown`
其他	跳过 + 记录日志

注意:

部分格式的转换成功率取决于上游工具的状态。
YouTube字幕提取请使用
```
baoyu-youtube-transcript
```
技能。
音频转写和说话人分离请使用
```
NotebookLM
```
或单独的音频转写工具。

공식 지원 vs 현재 검증

官方支持 vs 当前已验证

구분해서 봐야 한다.

```
MarkItDown
```
공식 지원 범위는 더 넓지만, 이 스킬은 문서파일과 이미지에만 한정한다
이 스킬의 현재 자동화 범위: 위 포맷을
```
markitdown
```
에 위임하고,
```
HWPX
```
는 별도 추출기로 처리
이 환경에서 실제 검증 완료:
- ```
PDF
```
  ,
```
PPTX
```
  ,
```
HWPX
```
  폴더 일괄 변환 성공
이 환경에서 주의가 필요한 항목:
- 새 포맷은 실무 적용 전 단건 검증이 필요하다

실무 원칙:

“공식 지원”과 “현재 검증 완료”를 같은 의미로 말하지 않는다.
새 포맷을 실무에 쓰기 전에는
```
convert_one.py
```
로 먼저 단건 검증한다.
YouTube transcript는
```
baoyu-youtube-transcript
```
를 기본값으로 쓴다.
음성 전사와 화자 분리는
```
NotebookLM
```
또는 별도 STT 경로로 분리한다.

需要区分以下内容：

```
MarkItDown
```
官方支持范围更广，但本技能仅限定于文档文件和图片
本技能当前的自动化范围：上述格式委托
```
markitdown
```
处理，
```
HWPX
```
使用单独提取器处理
本环境下已完成实际验证：
- 成功批量转换
```
PDF
```
  ,
```
PPTX
```
  ,
```
HWPX
```
  文件夹
本环境下需要注意的事项：
- 新格式在实际应用前需先进行单文件验证

实操原则:

不要将“官方支持”和“当前已验证”视为同一概念。
新格式投入实际使用前，先通过
```
convert_one.py
```
进行单文件验证。
YouTube字幕提取默认使用
```
baoyu-youtube-transcript
```
。
音频转写和说话人分离需通过
```
NotebookLM
```
或单独的STT工具处理。

결과물

输出产物

출력 폴더에 아래 파일을 남긴다.

변환된
```
.md
```
```
conversion-summary.json
```
```
conversion-errors.log
```

输出文件夹中会生成以下文件：

转换后的
```
.md
```
文件
```
conversion-summary.json
```
```
conversion-errors.log
```

운영 원칙

运营原则

원본 파일은 절대 수정하지 않는다.
출력은 항상 별도 폴더에 쓴다.
같은 이름의 결과가 있으면 기본적으로 덮어쓴다.
지원하지 않는 파일은 실패로 중단하지 않고 로그만 남긴다.

绝不修改原始文件。
输出始终保存到单独文件夹。
若存在同名结果文件，默认覆盖。
不支持的文件不会中断处理，仅记录日志。