WINDOWS BEGINNER GUIDE v1.5.18

WINDOWS
QUICK START

컴퓨터에 아무것도 설치되어 있지 않은 상태에서, 마크다운 파일을 전자책(EPUB)과 PDF로 변환할 수 있는 환경을 만드는 완벽 가이드

요리로 이해하기

기술을 '요리'로 이해하기

당신이 맛있는 요리(전자책)를 만들고 싶다고 상상해 보세요.

비유 실제 설명
재료 마크다운 파일 (.md) 당신이 작성한 글
가스레인지 Node.js 요리를 할 수 있게 해주는 기본 시스템
프라이팬 Pandoc 재료를 요리로 변환하는 도구
요리사 NpxMagicDoc 모든 것을 조합해서 요리를 완성하는 셰프
오븐 Python + WeasyPrint PDF라는 특별한 요리를 만들 때만 필요

결론: 가스레인지(Node.js)와 프라이팬(Pandoc)만 있으면 EPUB은 만들 수 있습니다!
PDF도 만들고 싶다면 오븐(Python + WeasyPrint)을 추가로 설치하세요.

설치 순서

┌─────────────────────────────────────────────────────────────┐
│  1단계: Node.js 설치 (가스레인지 설치)                        │
│     ↓                                                       │
│  2단계: Pandoc 설치 (프라이팬 구입)                          │
│     ↓                                                       │
│  3단계: 설치 확인 (불이 켜지는지 테스트)                      │
│     ↓                                                       │
│  🎉 EPUB 변환 가능!                                         │
│     ↓                                                       │
│  [선택] 4단계: Python 설치 (오븐 설치)                       │
│     ↓                                                       │
│  [선택] 5단계: WeasyPrint 설치 (오븐 예열)                   │
│     ↓                                                       │
│  🎉 PDF 변환도 가능!                                        │
└─────────────────────────────────────────────────────────────┘

1단계: Node.js 설치

01 REQUIRED ENGINE

Node.js가 뭔가요?

Node.js는 자바스크립트 프로그램을 실행할 수 있게 해주는 환경입니다. NpxMagicDoc은 자바스크립트로 만들어졌기 때문에, Node.js가 있어야 실행됩니다.

요리로 비유하면, 가스레인지 없이는 요리를 할 수 없는 것과 같습니다.

설치 방법

  1. nodejs.org 방문
  2. LTS 버전 (왼쪽 초록 버튼) 다운로드
  3. 다운로드된 파일 (node-v20.x.x-x64.msi) 더블클릭
  4. 설치 마법사에서 [Next] 클릭
  5. "I accept the terms..." 체크 → [Next]
  6. 설치 경로 그대로 → [Next]
중요! "Automatically install the necessary tools" 옵션이 보이면 반드시 체크하세요!
  1. [Install] 클릭 → 설치 완료 후 [Finish]
  2. 컴퓨터 재시작 (권장)

설치 확인

1. Windows 키 + X → "Windows PowerShell" 클릭

2. 아래 명령어 입력:

node --version

3. v20.10.0 같은 버전이 나오면 성공!

2단계: Pandoc 설치

02 CONVERSION ENGINE

Pandoc이 뭔가요?

Pandoc은 문서 형식을 변환하는 만능 도구입니다. 마크다운을 EPUB, PDF, HTML, Word 등 거의 모든 형식으로 바꿀 수 있습니다.

요리로 비유하면, 재료를 원하는 요리로 변환하는 프라이팬입니다.

방법 A: winget (권장)

PowerShell에서 한 줄 입력:

winget install --id JohnMacFarlane.Pandoc

방법 B: 직접 다운로드

1. pandoc.org/installing.html 방문

2. Windows 설치 파일 (.msi) 다운로드

3. 더블클릭해서 설치

설치 확인

새 PowerShell 창을 열고 (기존 창 말고!) 아래 명령어 입력:

pandoc --version

pandoc 3.1.9 같은 버전이 나오면 성공!

🎉 여기까지 왔다면 EPUB 변환 가능!

축하합니다! 이제 마크다운 파일을 EPUB 전자책으로 변환할 수 있습니다.

npx markdown-to-document-cli@latest interactive

4단계: Python 설치

03 OPTIONAL - PDF용

Python 설치하기 (오븐 설치)

PDF 변환이 필요 없다면 이 단계를 건너뛰세요!

Python은 프로그래밍 언어입니다. WeasyPrint라는 PDF 변환 도구가 Python으로 만들어져서, Python이 있어야 WeasyPrint를 사용할 수 있습니다.

방법 A: winget (권장)

winget install --id Python.Python.3.12

방법 B: 직접 다운로드

python.org/downloads에서 다운로드

매우 중요! 설치 시 "Add python.exe to PATH" 반드시 체크!
체크하지 않으면 Python이 설치되어도 PowerShell에서 인식하지 못합니다.

설치 확인

python --version
pip --version

5단계: WeasyPrint 설치

04 OPTIONAL - PDF용

WeasyPrint + GTK 설치하기

WeasyPrint는 HTML/CSS를 PDF로 변환하는 도구입니다.

항목 WeasyPrint MiKTeX (LaTeX)
설치 간단 (pip 한 줄) 복잡 (수 GB 다운로드)
대화상자 없음 패키지 설치 대화상자 반복
Mac과 동일 ✅ 100% 동일한 결과 ❌ HTML 태그 노출, 레이아웃 깨짐
한글 ✅ 완벽 지원 ⚠️ 폰트 설정 필요

WeasyPrint 설치

pip install weasyprint

GTK 런타임 설치 (필수!)

WeasyPrint는 GTK 런타임 라이브러리가 필요합니다.

  1. msys2.org에서 MSYS2 다운로드 및 설치
  2. 시작 메뉴에서 "MSYS2 MINGW64" 검색하여 실행
주의! UCRT64가 아닌 MINGW64를 실행하세요!

3. MSYS2 터미널에서 GTK3 설치:

pacman -S --needed mingw-w64-x86_64-gtk3

4. 시스템 PATH 설정:

  • Win + R → sysdm.cpl → 고급 → 환경 변수
  • Path 편집 → C:\msys64\mingw64\bin 추가
  • 기존에 C:\msys64\ucrt64\bin이 있다면 제거

설치 확인

새 PowerShell 열고:

weasyprint --version

WeasyPrint version 60.1 같은 결과가 나오면 성공!

최종 확인

전체 설치 확인 명령어

PowerShell에서 아래 명령어들을 하나씩 입력해보세요:

# 1. Node.js 확인
node --version
# 예상 결과: v20.10.0

# 2. Pandoc 확인
pandoc --version
# 예상 결과: pandoc 3.1.9

# 3. Python 확인 (PDF 변환 시 필요)
python --version
# 예상 결과: Python 3.12.0

# 4. WeasyPrint 확인 (PDF 변환 시 필요)
weasyprint --version
# 예상 결과: WeasyPrint version 60.1

EPUB 변환

Node.js + Pandoc만 있으면 됨

npx markdown-to-document-cli@latest "문서.md" --format epub

PDF 변환

Python + WeasyPrint 필요

npx markdown-to-document-cli@latest "문서.md" --format pdf

대화형 모드 (가장 쉬움!)

안내에 따라 진행하면 됩니다.

npx markdown-to-document-cli@latest interactive

터미널 사용 팁

붙여넣기 방법

마우스 오른쪽 클릭 가장 확실! 클릭만 하면 붙여넣기
Ctrl+Shift+V 일부 최신 터미널에서 작동
Windows Terminal Microsoft Store에서 설치, Ctrl+V 기본 지원

경로 입력 팁

  • 경로에 공백이 있으면 따옴표로 감싸세요
  • 드래그 앤 드롭: 파일을 PowerShell 창에 끌어다 놓으면 경로 자동 입력
  • 네트워크 드라이브 UNC 경로 지원: \\Mac\Home\file.md

흔한 문제 해결

'm2d' 인식 안됨

해결: npx 사용

npx markdown-to-document-cli@latest interactive

'node' 인식 안됨

해결: 컴퓨터 재시작 후 새 PowerShell 열기

'python' 인식 안됨

해결: Python 삭제 → 재설치 시 PATH 체크

PowerShell 실행 정책 오류

해결 1: CMD 사용 (Win + R → cmd)

해결 2: 관리자 PowerShell에서:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

더 많은 문제 해결이 필요하신가요?

전체 문제 해결 가이드 보기 →

FAQ

Q: "명령어를 인식하지 못합니다" 오류가 나요

A: 환경 변수가 적용되지 않은 것입니다.

  1. 컴퓨터를 재시작하세요
  2. 새 PowerShell 창을 열고 다시 시도하세요
  3. 그래도 안 되면 해당 프로그램을 다시 설치하세요

Q: Python 설치 시 PATH 체크를 깜빡했어요

A: Python을 완전히 삭제하고 다시 설치해야 합니다.

  1. 설정 → 앱 → Python 찾아서 제거
  2. Python 다시 다운로드
  3. 설치 시 "Add python.exe to PATH" 반드시 체크!

Q: EPUB만 필요한데 Python도 설치해야 하나요?

A: 아니요! EPUB 변환에는 Node.js와 Pandoc만 있으면 됩니다. Python과 WeasyPrint는 PDF 변환에만 필요합니다.

Q: UCRT64 대신 MINGW64를 사용해야 하는 이유는?

A: WeasyPrint의 cffi 라이브러리가 UCRT64와 호환성 문제가 있습니다.

  • UCRT64: error 0x7e 오류 발생
  • MINGW64: 정상 작동