converter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HWPX Converter

HWPX 转换器

Markdown 파일을 한글 문서(HWPX)로 변환합니다.

将Markdown文件转换为韩文字档（HWPX）。

사용자 입력 스키마

用户输入规范

필수 입력

必填输入

항목	설명	예시
입력 경로	변환할 .md 파일 또는 폴더	`./report.md` 또는 `./docs/`

项目	说明	示例
输入路径	要转换的.md文件或文件夹	`./report.md` 或 `./docs/`

선택 입력

可选输入

항목	설명	기본값
출력 경로	출력 위치	입력과 동일 위치

项目	说明	默认值
输出路径	输出位置	与输入路径相同

Prerequisites (필수 설치)

前置要求（必须安装）

⚠️ 이 스킬을 사용하려면 아래 프로그램이 설치되어 있어야 합니다.

⚠️ 使用本技能前，必须安装以下程序。

자동 설치 (권장)

自动安装（推荐）

hwpx-setup
스킬을 호출하면 의존성을 자동으로 설치합니다.

hwpx-setup 스킬을 사용해서 의존성을 설치해줘

调用
hwpx-setup
技能即可自动安装依赖。

请使用hwpx-setup技能来安装依赖

수동 설치

手动安装

1. Pandoc 설치 (시스템 의존성)

Windows:
```
winget install pandoc
```
또는 공식 다운로드
macOS:
```
brew install pandoc
```
Linux:
```
sudo apt install pandoc
```

2. pypandoc-hwpx 설치

bash

pip install pypandoc-hwpx

설치 확인:

bash

pandoc --version
pypandoc-hwpx --help

1. 安装Pandoc（系统依赖）

Windows:
```
winget install pandoc
```
或官方下载
macOS:
```
brew install pandoc
```
Linux:
```
sudo apt install pandoc
```

2. 安装pypandoc-hwpx

bash

pip install pypandoc-hwpx

安装验证：

bash

pandoc --version
pypandoc-hwpx --help

상세 설치 가이드

详细安装指南

필수 의존성

必备依赖

프로그램	버전	용도
Pandoc	3.0+	문서 변환 엔진
Python	3.6+	pypandoc-hwpx 실행 환경
pypandoc-hwpx	최신	HWPX 변환 도구

程序	版本	用途
Pandoc	3.0+	文档转换引擎
Python	3.6+	pypandoc-hwpx运行环境
pypandoc-hwpx	最新版	HWPX转换工具

1. Pandoc 설치

1. 安装Pandoc

Windows

방법 A: 공식 설치 파일 (권장)

https://pandoc.org/installing.html 접속
Windows 설치 파일(.msi) 다운로드
설치 파일 실행 및 설치 완료
터미널 재시작

방법 B: winget 사용

powershell

winget install --id JohnMacFarlane.Pandoc

방법 C: Chocolatey 사용

powershell

choco install pandoc

方法A：官方安装包（推荐）

访问https://pandoc.org/installing.html
下载Windows安装文件（.msi）
运行安装文件完成安装
重启终端

方法B：使用winget

powershell

winget install --id JohnMacFarlane.Pandoc

方法C：使用Chocolatey

powershell

choco install pandoc

macOS

Homebrew 사용 (권장)

bash

brew install pandoc

MacPorts 사용

bash

sudo port install pandoc

使用Homebrew（推荐）

bash

brew install pandoc

使用MacPorts

bash

sudo port install pandoc

Linux (Ubuntu/Debian)

Linux（Ubuntu/Debian）

bash

sudo apt update
sudo apt install pandoc

bash

sudo apt update
sudo apt install pandoc

Linux (Fedora/RHEL)

Linux（Fedora/RHEL）

bash

sudo dnf install pandoc

bash

sudo dnf install pandoc

Linux (Arch)

Linux（Arch）

bash

sudo pacman -S pandoc

bash

sudo pacman -S pandoc

2. Python 설치

2. 安装Python

Windows

https://python.org/downloads/ 접속
최신 Python 설치 파일 다운로드
"Add Python to PATH" 체크 (중요!)
설치 완료

访问https://python.org/downloads/
下载最新Python安装文件
勾选"Add Python to PATH"（重要！）
完成安装

macOS

Homebrew 사용 (권장)

bash

brew install python

使用Homebrew（推荐）

bash

brew install python

Linux

대부분의 Linux 배포판에 기본 설치되어 있습니다.

bash

undefined

大多数Linux发行版已默认安装。

bash

undefined

확인

验证版本

python3 --version

미설치 시 (Ubuntu/Debian)

未安装时（Ubuntu/Debian）

sudo apt install python3 python3-pip

undefined

sudo apt install python3 python3-pip

undefined

3. pypandoc-hwpx 설치

3. 安装pypandoc-hwpx

Python과 pip가 설치된 후:

bash

pip install pypandoc-hwpx

또는 Python 3 명시적 사용:

bash

python3 -m pip install pypandoc-hwpx

安装好Python和pip后：

bash

pip install pypandoc-hwpx

或指定使用Python 3：

bash

python3 -m pip install pypandoc-hwpx

설치 확인

安装验证

모든 설치가 완료되면 아래 명령어로 확인합니다:

bash

undefined

所有安装完成后，使用以下命令验证：

bash

undefined

Pandoc 버전 확인

查看Pandoc版本

pandoc --version

Python 버전 확인

查看Python版本

python --version

pypandoc-hwpx 도움말

查看pypandoc-hwpx帮助

pypandoc-hwpx --help


**예상 출력:**

pandoc 3.x.x ...

Python 3.x.x

usage: pypandoc-hwpx [-h] [--reference-doc REFERENCE_DOC] [-o OUTPUT] input ...

undefined

pypandoc-hwpx --help


**预期输出：**

pandoc 3.x.x ...

Python 3.x.x

usage: pypandoc-hwpx [-h] [--reference-doc REFERENCE_DOC] [-o OUTPUT] input ...

undefined

트러블슈팅

问题排查

"pandoc: command not found"

원인: Pandoc이 PATH에 등록되지 않음

해결:

Windows: 터미널 재시작 또는 시스템 재부팅
macOS/Linux: 셸 설정 파일 리로드 (
```
source ~/.bashrc
```
또는
```
source ~/.zshrc
```
)

原因： Pandoc未添加到PATH中

解决方法：

Windows：重启终端或重启系统
macOS/Linux：重新加载shell配置文件（
```
source ~/.bashrc
```
或
```
source ~/.zshrc
```
）

"pip: command not found"

원인: Python pip가 PATH에 없음

해결:

bash

undefined

原因： Python pip未在PATH中

解决方法：

bash

undefined

Python 모듈로 pip 실행

通过Python模块运行pip

python -m pip install pypandoc-hwpx

또는 python3 사용

或使用python3

python3 -m pip install pypandoc-hwpx

undefined

python3 -m pip install pypandoc-hwpx

undefined

"Permission denied" (Linux/macOS)

"Permission denied"（Linux/macOS）

원인: 시스템 Python에 설치 시도

해결:

bash

undefined

原因： 尝试安装到系统Python中

解决方法：

bash

undefined

사용자 설치 (권장)

用户级安装（推荐）

pip install --user pypandoc-hwpx

또는 venv 사용

或使用虚拟环境

python -m venv .venv source .venv/bin/activate pip install pypandoc-hwpx

undefined

python -m venv .venv source .venv/bin/activate pip install pypandoc-hwpx

undefined

변환 시 한글 깨짐

转换时韩文乱码

원인: 파일 인코딩 문제

해결:

소스 .md 파일이 UTF-8로 저장되어 있는지 확인
BOM 없는 UTF-8 권장

原因： 文件编码问题

解决方法：

确认源.md文件以UTF-8编码保存
推荐使用无BOM的UTF-8编码

참고 링크

参考链接

워크플로우

工作流程

Phase 1: 입력 검증

阶段1：输入验证

입력 경로 존재 확인
.md 파일 여부 확인 (폴더면 내부 .md 파일 목록 생성)

验证输入路径是否存在
确认是否为.md文件（如果是文件夹，则生成内部.md文件列表）

Phase 2: 환경 체크

阶段2：环境检查

```
pandoc --version
```
실행하여 Pandoc 설치 확인
미설치 시 설치 가이드 안내 후 중단

执行
```
pandoc --version
```
验证Pandoc是否已安装
未安装时，引导至安装指南后终止流程

Phase 3: 변환 실행

阶段3：执行转换

단일 파일:

bash

pypandoc-hwpx [input.md] -o [input.hwpx]

폴더 배치 (1단계만):

bash

for file in [folder]/*.md; do
  pypandoc-hwpx "$file" -o "${file%.md}.hwpx"
done

单个文件：

bash

pypandoc-hwpx [input.md] -o [input.hwpx]

文件夹批量转换（仅一级目录）：

bash

for file in [folder]/*.md; do
  pypandoc-hwpx "$file" -o "${file%.md}.hwpx"
done

Phase 4: 결과 출력

阶段4：结果输出

변환 성공: 생성된 .hwpx 파일 경로 출력
변환 실패: Pandoc 에러 메시지 그대로 전달

转换成功：输出生成的.hwpx文件路径
转换失败：直接返回Pandoc错误信息

에러 처리

错误处理

상황	처리
Pandoc 미설치	설치 가이드 안내 후 중단
파일 없음	에러 메시지 출력
변환 실패	pypandoc-hwpx 에러 메시지 전달

场景	处理方式
Pandoc未安装	引导至安装指南后终止流程
文件不存在	输出错误信息
转换失败	返回pypandoc-hwpx错误信息

Limitations (v1.0)

限制（v1.0版本）

MD→HWPX만 지원 (DOCX→HWPX 미지원)
기본 템플릿만 (
```
--reference-doc
```
옵션 미지원)
1단계 폴더만 (하위 폴더 재귀 탐색 안 함)
자동 덮어쓰기 (동일 이름 hwpx 파일 존재 시)

仅支持MD→HWPX（不支持DOCX→HWPX）
仅使用默认模板（不支持
```
--reference-doc
```
选项）
仅处理一级目录（不递归遍历子文件夹）
自动覆盖（若存在同名hwpx文件则直接覆盖）

리소스

资源

상세 설치 가이드는 위 Prerequisites 섹션의 "상세 설치 가이드"를 참조하세요.

详细安装指南请参考上方前置要求章节中的「详细安装指南」。