HWPX Converter
Markdown 파일을 한글 문서(HWPX)로 변환합니다.
사용자 입력 스키마
필수 입력
항목 설명 예시
입력 경로 변환할 .md 파일 또는 폴더 ./report.md 또는 ./docs/
선택 입력
항목 설명 기본값
출력 경로 출력 위치 입력과 동일 위치
Prerequisites (필수 설치)
⚠️ 이 스킬을 사용하려면 아래 프로그램이 설치되어 있어야 합니다.
자동 설치 (권장)
hwpx-setup 스킬을 호출하면 의존성을 자동으로 설치합니다.
hwpx-setup 스킬을 사용해서 의존성을 설치해줘
수동 설치
- Pandoc 설치 (시스템 의존성)
-
Windows: winget install pandoc 또는 공식 다운로드
-
macOS: brew install pandoc
-
Linux: sudo apt install pandoc
- pypandoc-hwpx 설치
pip install pypandoc-hwpx
설치 확인:
pandoc --version pypandoc-hwpx --help
상세 설치 가이드
필수 의존성
프로그램 버전 용도
Pandoc 3.0+ 문서 변환 엔진
Python 3.6+ pypandoc-hwpx 실행 환경
pypandoc-hwpx 최신 HWPX 변환 도구
- Pandoc 설치
Windows
방법 A: 공식 설치 파일 (권장)
-
Windows 설치 파일(.msi) 다운로드
-
설치 파일 실행 및 설치 완료
-
터미널 재시작
방법 B: winget 사용
winget install --id JohnMacFarlane.Pandoc
방법 C: Chocolatey 사용
choco install pandoc
macOS
Homebrew 사용 (권장)
brew install pandoc
MacPorts 사용
sudo port install pandoc
Linux (Ubuntu/Debian)
sudo apt update sudo apt install pandoc
Linux (Fedora/RHEL)
sudo dnf install pandoc
Linux (Arch)
sudo pacman -S pandoc
- Python 설치
Windows
-
최신 Python 설치 파일 다운로드
-
"Add Python to PATH" 체크 (중요!)
-
설치 완료
macOS
Homebrew 사용 (권장)
brew install python
Linux
대부분의 Linux 배포판에 기본 설치되어 있습니다.
확인
python3 --version
미설치 시 (Ubuntu/Debian)
sudo apt install python3 python3-pip
- pypandoc-hwpx 설치
Python과 pip가 설치된 후:
pip install pypandoc-hwpx
또는 Python 3 명시적 사용:
python3 -m pip install pypandoc-hwpx
설치 확인
모든 설치가 완료되면 아래 명령어로 확인합니다:
Pandoc 버전 확인
pandoc --version
Python 버전 확인
python --version
pypandoc-hwpx 도움말
pypandoc-hwpx --help
예상 출력:
pandoc 3.x.x ...
Python 3.x.x
usage: pypandoc-hwpx [-h] [--reference-doc REFERENCE_DOC] [-o OUTPUT] input ...
트러블슈팅
"pandoc: command not found"
원인: Pandoc이 PATH에 등록되지 않음
해결:
-
Windows: 터미널 재시작 또는 시스템 재부팅
-
macOS/Linux: 셸 설정 파일 리로드 (source ~/.bashrc 또는 source ~/.zshrc )
"pip: command not found"
원인: Python pip가 PATH에 없음
해결:
Python 모듈로 pip 실행
python -m pip install pypandoc-hwpx
또는 python3 사용
python3 -m pip install pypandoc-hwpx
"Permission denied" (Linux/macOS)
원인: 시스템 Python에 설치 시도
해결:
사용자 설치 (권장)
pip install --user pypandoc-hwpx
또는 venv 사용
python -m venv .venv source .venv/bin/activate pip install pypandoc-hwpx
변환 시 한글 깨짐
원인: 파일 인코딩 문제
해결:
-
소스 .md 파일이 UTF-8로 저장되어 있는지 확인
-
BOM 없는 UTF-8 권장
참고 링크
-
Pandoc 공식 문서
-
pypandoc-hwpx GitHub
-
pypandoc-hwpx PyPI
워크플로우
Phase 1: 입력 검증
-
입력 경로 존재 확인
-
.md 파일 여부 확인 (폴더면 내부 .md 파일 목록 생성)
Phase 2: 환경 체크
-
pandoc --version 실행하여 Pandoc 설치 확인
-
미설치 시 설치 가이드 안내 후 중단
Phase 3: 변환 실행
단일 파일:
pypandoc-hwpx [input.md] -o [input.hwpx]
폴더 배치 (1단계만):
for file in [folder]/*.md; do pypandoc-hwpx "$file" -o "${file%.md}.hwpx" done
Phase 4: 결과 출력
-
변환 성공: 생성된 .hwpx 파일 경로 출력
-
변환 실패: Pandoc 에러 메시지 그대로 전달
에러 처리
상황 처리
Pandoc 미설치 설치 가이드 안내 후 중단
파일 없음 에러 메시지 출력
변환 실패 pypandoc-hwpx 에러 메시지 전달
Limitations (v1.0)
-
MD→HWPX만 지원 (DOCX→HWPX 미지원)
-
기본 템플릿만 (--reference-doc 옵션 미지원)
-
1단계 폴더만 (하위 폴더 재귀 탐색 안 함)
-
자동 덮어쓰기 (동일 이름 hwpx 파일 존재 시)
리소스
상세 설치 가이드는 위 Prerequisites 섹션의 "상세 설치 가이드"를 참조하세요.