DocWen

English · 简体中文 · 繁體中文 · Deutsch · Français · Español · Português · Русский · 日本語 · 한국어 · Tiếng Việt · العربية

DocWen은 Word, Markdown, Excel 등 업무용 형식을 위한 로컬 문서·표 변환 도구입니다. 안정적인 오프라인 작업 흐름을 지향하며 문서 처리를 사용자의 장치 안에서 수행합니다.

인터페이스 언어는 앱의 문구와 배치를 제어합니다. 일반 설정의 작업 출력 언어는 생성 라벨, 문서 스타일 및 교정 주석을 별도로 제어하며 본문을 번역하지 않습니다. 인터페이스 언어를 바꿔도 저장된 출력 언어나 템플릿은 유지됩니다. OCR 자동은 작업 출력 언어를 따릅니다. 일반 Markdown 본문의 각 줄을 Word 단락으로 만드는 옵션은 기본적으로 꺼져 있습니다.

DocWen으로 할 수 있는 일

Word와 Markdown을 변환하고, 스프레드시트와 PDF를 정리하거나 사용자 규칙으로 문서를 교정합니다. 일반적인 작업은 GUI, 반복 작업은 CLI를 사용하세요. 가능한 변환은 형식과 설치된 소프트웨어에 따라 다르므로 기능 목록을 확인하세요.

✨ 핵심 기능

• 📄 문서 변환 - Word ↔ Markdown 양방향 변환. 수식 변환, 구분선(---/***/___)과 페이지/구역/가로선 매핑을 지원하며, Markdown 표의 명시적 < / ^ 병합 표시를 Word의 직사각형 셀 병합으로 복원할 수 있습니다. DOCX/DOC/WPS/RTF/ODT 지원.
• 📊 스프레드시트 변환 – Excel ↔ Markdown 양방향 변환으로 XLSX/XLS/ET/ODS/CSV/TSV를 지원합니다. 병합 셀은 내용을 반복하거나, 빈칸으로 두거나, 병합 표시를 사용해 내보낼 수 있습니다. XLSX 템플릿에서 YAML 필드, 표의 행과 열, 이미지, 병합 셀을 다룰 수 있으며 여러 표를 합칠 수도 있습니다.
• 📑 PDF/레이아웃 파일 - PDF/XPS/OFD → Markdown 또는 DOCX. PDF 병합/분할 등 지원.
• 🖼️ 이미지 처리 - JPEG/PNG/GIF/BMP/TIFF/WebP/HEIC 변환 및 압축.
• 📥 기타 형식 가져오기 - HTML/MHTML/ENEX/EPUB/PPTX/PPT에서 Markdown으로의 단방향 변환을 지원합니다.
• 🔍 OCR 텍스트 인식 - RapidOCR을 통합하여 이미지와 PDF에서 텍스트를 추출합니다.
• ✏️ 교정(Proofread) - Word (.docx) 및 Markdown (.md) 파일의 사용자 사전 기반 오탈자/문장부호/기호/민감어 검사. 규칙은 설정 화면에서 편집할 수 있습니다.
• 📝 템플릿 시스템 - 문서/보고서 형식을 템플릿으로 관리.
• 💻 GUI + CLI - 그래픽 UI와 명령행 모두 제공.
• 🔒 종속성 송신 보호를 갖춘 로컬 처리 - 변환은 온라인 서비스에 의존하지 않습니다. DocWen 실행 중 Python 프로세스 내부 종속성의 DNS 및 IPv4/IPv6 사용을 차단하며, 외부 Office 프로그램은 자체 시스템 네트워크 정책을 따릅니다.
• 🔗 단일 인스턴스 실행 - 프로그램 인스턴스를 자동으로 관리하며, 동반 Obsidian 플러그인과의 연동을 지원합니다.

📸 스크린샷

Word 문서를 가져와 Markdown 내보내기 옵션을 선택합니다(영어 화면).

Markdown을 가져와 템플릿을 선택하고 Word 문서를 생성합니다(영어 화면).

변경 이력: CHANGELOG.md 참고

🚀 빠른 시작

다운로드하여 실행

Releases에서 환경에 맞는 압축 파일을 받으세요. Windows x64, Ubuntu 24.04 x64, Apple Silicon macOS 14+ 패키지를 제공하며 Python 설치는 필요 없습니다. 전체 압축을 푼 뒤 Windows에서는 DocWen.exe, Ubuntu에서는 ./DocWen을 실행하세요. Mac에서는 DocWen.app을 응용 프로그램으로 옮긴 뒤 첫 실행 안내를 따르세요. Ubuntu와 macOS에는 CLI 전용 패키지도 있습니다. 다른 Linux 배포판과 Intel Mac은 패키지 대상이 아닙니다.

제공되는 파일은 버전마다 다릅니다. 사용 중인 시스템용으로 실제 등록된 파일을 선택하세요. 이전 버전에는 macOS 패키지가 없을 수 있습니다.

소스에서 실행

개발하거나 소스에서 설치하려면 Python 3.12와 uv 0.12.0을 설치한 뒤 저장소에서 실행하세요.

git clone https://github.com/ZHYX91/docwen.git
cd docwen
uv sync --frozen --all-extras
uv run --frozen docwen-gui
uv run --frozen docwen --help

uv run --frozen은 동기화된 환경을 사용하므로 수동 활성화가 필요 없습니다. CI와 제품 빌드는 uv 0.12.0을, 의존성 관리는 호환되는 0.12.x를 사용합니다. pip install -e는 저장소의 특정 의존성 제외 규칙을 적용할 수 없어 지원하지 않습니다.

macOS 설치 안내

Mac 패키지는 ad-hoc 서명을 유지하며 Developer ID 서명과 Apple 공증은 사용하지 않습니다. 설치 및 첫 실행을 참고하세요.

LibreOffice 지원(선택)

.doc, .xls 같은 구형 포맷 변환이 필요하다면 LibreOffice를 설치하세요:
다운로드: https://www.libreoffice.org/download/

HEIC/HEIF 이미지

배포 패키지는 자체 이미지 백엔드를 사용합니다. DocWenCLI doctor --json으로 설치된 빌드를 확인하세요(Mac CLI 경로는 아래 안내 참조). 시스템 Python에 pillow-heif를 설치해도 배포 앱은 바뀌지 않습니다. 소스의 uv sync --frozen --all-extras에는 이미 pillow-heif가 포함되어 있습니다. macOS 백엔드가 네이티브 라이브러리 누락을 알리면 brew install libheif를 실행한 뒤 uv run --frozen docwen doctor --json으로 다시 확인하세요. 실제 지원 여부는 빌드와 백엔드에 따라 달라집니다.

Linux GUI 버전 사전 준비

지원 패키지 대상: DocWen은 Ubuntu 24.04 x64 패키지의 GUI와 CLI를 지원합니다. 이 요구 사항은 다른 배포판이나 아키텍처로 지원 범위를 확장하지 않습니다.

• 데스크톱 환경이 설치되어 있어야 합니다(GNOME, KDE, XFCE 등)
• GUI는 PySide6(Qt6) 기반입니다. 시작 시 시스템 라이브러리가 부족하다는 오류가 나면, 오류 메시지에 표시된 Qt 런타임 의존성(보통 OpenGL/X11 관련)을 설치하세요.
• 데스크톱 환경이 없으면 압축을 푼 CLI 패키지에서 ./DocWenCLI를, 소스 디렉터리에서는 uv run --frozen docwen을 실행하세요.

빠른 시작 가이드

1. Markdown 파일 준비:

   ---
   title: 테스트 문서
   ---
   
   ## 테스트 제목
   
   테스트 본문 내용입니다.
   

2. 드래그 앤 드롭 변환:

   • 프로그램을 실행합니다.
   • .md 파일을 창으로 드래그합니다.
   • 템플릿을 선택합니다.
   • "생성 DOCX"을 클릭합니다.

3. 결과 확인:

   • Word 문서가 하나이면 설정한 출력 위치에 직접 저장됩니다. 상태 표시줄에서 출력 위치를 열어 확인하세요.

팁: samples/ 디렉터리의 샘플 파일을 사용하면 기능을 빠르게 체험할 수 있습니다.

🖥️ 그래픽 인터페이스 사용

작업을 시작하면 실제 요청의 설정 요약이 표시됩니다. 템플릿은 이름이나 용도로 검색할 수 있습니다. “이번 세션에서 최근 사용”은 시작한 작업의 템플릿을 표시하며 기본 템플릿을 바꾸지 않습니다. 표 병합은 범위, 모드 및 결과 확인 안내를 참고하세요.

인터페이스 개요

프로그램은 적응형 3열 레이아웃을 사용합니다:

영역	설명	표시 시점
중앙 열(메인 영역)	파일 드래그 앤 드롭 영역, 작업 패널, 상태 표시줄	항상 표시
오른쪽 열	템플릿 선택기 / 포맷 변환 패널	파일 선택 후 자동 확장
왼쪽 열	배치 파일 목록(형식별 그룹)	배치 모드에서 표시

기본 작업 흐름

1. 프로그램 실행: DocWen.exe(Windows 패키지) 더블클릭 또는 uv run --frozen docwen-gui 실행.
2. 파일 가져오기:
   • 방법 1: 파일을 창으로 드래그합니다.
   • 방법 2: 드래그 영역의 "추가" 버튼을 눌러 파일을 선택합니다.
3. 템플릿 선택(변환이 필요한 경우): 오른쪽 템플릿 패널이 자동으로 확장되며, 적절한 템플릿을 선택합니다.
4. 옵션 설정: 작업 패널에서 필요한 변환/내보내기 옵션을 체크합니다.
5. 작업 실행: 해당 기능 버튼(예: "MD 내보내기", "생성 DOCX")을 클릭합니다.
6. 결과 확인: 상태 표시줄에 진행 상황과 결과가 표시되며, 오른쪽의 "출력 열기" 동작을 클릭하면 출력 위치를 열 수 있습니다.

단일 파일 모드 vs 배치 모드

프로그램은 2가지 처리 모드를 지원하며, 드래그 앤 드롭 영역의 토글 버튼으로 전환할 수 있습니다:

단일 파일 모드(기본값):

• 한 번에 한 파일 처리
• 인터페이스가 단순해 일상 사용에 적합

배치 모드:

• 여러 파일을 동시에 가져오기
• 왼쪽 열에 파일 목록을 형식별로 그룹화해 표시
• 일괄 추가/제거/정렬 지원
• 목록에서 파일을 클릭해 현재 작업 대상을 전환

작업 패널 기능

작업 패널은 파일 형식에 따라 사용 가능한 기능을 자동으로 조정합니다:

파일 형식	사용 가능한 작업
Word 문서	MD 내보내기, PDF 변환, 텍스트 교정, OCR
Markdown	DOCX 변환, PDF 변환, 텍스트 교정
Excel 스프레드시트	MD 내보내기, PDF 변환, 표 요약
PDF	MD 내보내기, 병합, 분할, OCR
이미지	포맷 변환, 압축, OCR
HTML/EPUB/PPTX 등	MD 내보내기

설정 화면

창 아래쪽 설정 아이콘이나 **Ctrl+,**로 설정을 엽니다. 왼쪽 탐색 메뉴는 기본 설정, 입력 유형, 콘텐츠, 전용 기능으로 나뉩니다. 창 높이가 낮으면 스크롤할 수 있고, 너비가 부족할 때만 페이지 선택 드롭다운으로 전환됩니다.

OCR 및 이미지에서 공통 인식 설정과 Markdown 이미지 출력을 관리합니다. 입력 유형별 OCR 기본 선택은 각 입력 페이지에, 이미지 변환과 압축은 입력 이미지 페이지에 있습니다. Markdown 생성에서 출력 문법과 확장을 설정하고, Markdown 해석에서 입력 인식, 확장 및 Markdown에서 Word로 변환하는 매핑을 설정합니다. 모든 입력 형식이나 특수 최적화에 모든 문법 설정이 적용되지는 않습니다. 확장을 켜도 인식 기능이 추가되지는 않습니다.

최적화는 현재 인터페이스 언어와 감지된 입력 형식을 모두 지원하고 필요한 변환 프로그램을 사용할 수 있을 때만 표시됩니다. 해당 설정 페이지도 적용 가능한 최적화가 있을 때만 표시됩니다. 현재 내장된 중국 공문서 및 중국 송장 최적화는 중국어 간체 인터페이스(zh_CN)에만 적용됩니다. 다른 언어에서는 선택 항목과 설정 페이지를 숨기고 저장된 기본값도 적용하지 않습니다. 저장된 설정은 유지되며 지원 언어로 돌아오면 다시 사용할 수 있습니다. 이 규칙은 GUI의 선택과 기본값에 적용되며, CLI 또는 Machine에서 명시적으로 지정한 작업은 변경하지 않습니다.

모든 인터페이스 언어에서 **입력 텍스트 → 제목 번호(마크다운 → 문서)**에서 출력 방식 하나를 선택합니다. 텍스트는 새 번호를 제목 텍스트에 쓰고, DOCX 기본는 Word 다단계 번호 매기기를 사용합니다. 새 제목 번호에 메모 추가는 독립된 설정이며 두 방식 모두에서 사용할 수 있습니다. 텍스트 방식에서는 추가된 번호에, 기본 번호 매기기 방식에서는 제목의 첫 번째 보이는 문자에 메모를 붙입니다. 제목 번호 추가는 별도로 켜야 합니다.

적용 가능한 최적화가 있을 때 공문서와 송장 설정 페이지가 표시됩니다. 공문서의 문서 → Markdown은 인식 기본 선택을, Markdown → 문서는 템플릿 필드 서식을 다루며, 정보 아이콘에서 첨부 설명, 참조 수신처, 날짜 및 비고 규칙을 볼 수 있습니다. 송장 기본값은 PDF / OFD → Markdown과 이미지 → Markdown으로 나뉩니다. 이 기본값은 호환 파일의 초기 선택에만 영향을 주며, 파일을 자동 분류하지 않습니다. 적용／확인으로 저장하고 취소로 미적용 변경을 버립니다.

별도로 Markdown → 문서의 중국 공문서 필드 서식은 template_fill.gongwen_fields_enabled(기본값 켜짐)가 제어하며, 인터페이스 및 작업 출력 언어와 무관합니다. 공문서 설정 페이지가 숨겨져도 이 기능은 꺼지지 않습니다. 고정된 중국어 템플릿 필드의 서식을 처리하며, 문서 → Markdown 공문서 인식을 제어하지 않습니다.

적용 범위: 공문서 필드 전용 서식은 중국 공문서 규칙을, 송장 추출 최적화는 중국 송장 형식을 대상으로 합니다. 다른 파일은 일반 변환 경로를 이용할 수 있습니다.

단축 동작

• 외부 파일 드래그: 창으로 직접 드래그해 가져오기
• 출력 위치 열기: 상태 표시줄 오른쪽의 "출력 열기" 동작을 클릭해 출력 위치를 엽니다.
• 템플릿 항목 우클릭: 템플릿 파일 위치 열기

---

🔧 명령줄 사용

CLI 예시는 명령 이름으로 docwen을 사용합니다. 소스 디렉터리에서는 앞에 uv run --frozen을 붙이고, 배포 패키지에서는 Windows의 DocWenCLI.exe 또는 Linux/macOS의 ./DocWenCLI로 바꾸세요.

명령줄(CLI)에서는 터미널에서 파일을 확인하고 변환하거나 로컬 작업을 스크립트로 자동화할 수 있습니다. 다른 앱과 연동할 때는 아래의 Machine Protocol 인터페이스를 사용하세요.

자동화 권장 호출 순서

로컬 자동화 스크립트에서는 다음 순서로 변환을 확인하고 실행할 수 있습니다:

1. inspect <file> [--json]: 먼저 실제 파일 범주, 형식, 지원 동작을 확인합니다.
2. resources list formats --json: 현재 DocWen에서 실제로 사용할 수 있는 경로와 의존성 조건을 확인합니다.
3. schema convert: convert 의 기계 판독 가능한 계약과 조건 규칙을 읽습니다.
4. convert <file> --to <fmt> (--output-dir <dir> | --output <path>) --dry-run --json: 결과를 쓰지 않고 탐지, 정규화, 라우팅을 미리 확인합니다.
5. convert <file> --to <fmt> (--output-dir <dir> | --output <path>) ...: 확인 후 실제 변환을 실행합니다.

앱과 플러그인은 serve --stdio와 Machine Protocol v2로 연결하여 가능한 작업을 확인하고, 작업을 계획하고 실행합니다. 이는 외부 연동을 위한 안정적인 인터페이스이며 CLI --json은 터미널 스크립트용입니다. 데스크톱 앱에서 파일을 열거나 창을 앞으로 가져오려면 gui open|activate|status를 사용하세요.

자주 쓰는 예시

Markdown으로 변환할 때는 항상 --output-dir DIR로 선택한 상위 폴더 아래에 결과 폴더를 만듭니다. Markdown에서 문서나 스프레드시트로 변환한 최종 파일이 하나이면 해당 상위 폴더에 직접 저장합니다. 여러 파일 또는 명시적으로 요청한 감사용 부속 파일이 있으면 결과 폴더를 사용합니다. 자동 생성 이름에는 원본 이름, 타임스탬프와 현재 입력 형식이 포함됩니다. Markdown에서 생성한 경우를 포함하여 단일 최종 파일의 정확한 경로를 지정하려면 --output PATH를 사용하세요. 묶음 결과에는 --output-dir가 필요합니다.

# Windows 패키지
DocWenCLI.exe inspect document.docx --json

# 스크립트 / Agent 용 convert 계약 내보내기
DocWenCLI.exe schema convert

# 실제 파일 생성 없이 변환 경로 미리 보기
DocWenCLI.exe convert report.docx --to md --output-dir exports --extract-img --ocr --dry-run --json

# Word 를 Markdown 으로 내보내기 (이미지 추출 + OCR)
DocWenCLI.exe convert report.docx --to md --output-dir exports --extract-img --ocr

# Markdown 을 Word 로 변환 (템플릿 + 제목/본문 병합 모드)
DocWenCLI.exe convert document.md --to docx --output-dir exports --template template.docx.6cd486f34e59c79ded078a008b269af37860b63ccb74d8d0ab0080a7229a9ab5 --heading-merge-mode punct_required

# Markdown을 Word로 변환한 뒤 게시 전에 생성된 DOCX 교정
DocWenCLI.exe convert document.md --to docx --output-dir exports --proofread --check typo --check punct

# Markdown 출력 시 이미지 모드와 OCR 텍스트 배치 제어
DocWenCLI.exe convert report.docx --to md --output-dir exports --extract-img --image-mode file --ocr --ocr-placement image_md

# 런타임 능력과 의존성 게이트 확인
DocWenCLI.exe doctor --json
DocWenCLI.exe resources list formats --json

# 문서 교정
DocWenCLI.exe validate document.docx --check typo --check punct
DocWenCLI.exe validate input.md --check typo --check punct

# 소스 / uv 설치
# inspect -> schema -> dry-run -> convert
# docwen inspect document.docx --json
# docwen schema convert
# docwen convert document.docx --to md --output-dir exports --dry-run --json
# docwen convert document.docx --to md --output-dir exports

자주 쓰는 명령과 옵션

아래 표는 자주 쓰는 명령만 정리합니다. 전체 명령 집합은 docwen --help(소스 / uv) 또는 DocWenCLI --help(패키지판)를 참고하세요.

명령 / 옵션	설명
convert <file> --to <fmt> (--output-dir <dir> | --output <path>)	변환의 통합 진입점입니다.
convert <markdown> --to docx --output-dir <dir> --proofread [--check ...]	Markdown→DOCX 뒤 생성된 DOCX를 교정합니다. convert의 --check는 --proofread와 함께 사용해야 하며, --check를 생략하면 구성된 교정 기본값을 사용합니다.
convert <file> --to <fmt> (--output-dir <dir> | --output <path>) --dry-run --json	실제 변환 없이 탐지, 정규화, 라우팅, 적용 옵션만 미리 확인합니다.
schema convert	convert 의 기계 판독 가능한 계약, 기본값, 조건, 정규 키를 내보냅니다.
validate <file> --check ...	문서 교정(typo/punct/symbol/sensitive/all/none). CLI envelope에는 --json을 사용합니다. --report는 선택적 보고서 파일 경로입니다.
inspect <file> [--json]	파일 범주/형식, 권장 동작, 확장자와 내용 불일치 경고를 확인합니다.
doctor --json	진단 결과와 함께 런타임 능력 요약 및 의존성 게이트를 출력합니다.
resources list formats --json	원본 범주별 대상 형식과 의존성 게이트 / 제한 요약을 출력합니다.
resources list optimizations --json	형식화된 최적화 리소스와 정규 경로 연결을 나열합니다.
resources list templates	사용 가능한 템플릿을 나열합니다.
resources list numbering-schemes	사용 가능한 번호 체계를 나열합니다.
gui open [ABSOLUTE_FILE] [--timeout <seconds>] [--json]	별도의 로컬 GUI 제어로 DocWen을 시작하거나 활성화하고 필요하면 절대 경로 파일 하나를 엽니다.
--template <id>	resources list templates가 반환한 정규 리소스 ID를 그대로 사용합니다. 표시 이름·파일명·경로는 거부됩니다. DOCX ID는 docx/doc/odt/rtf/wps/pdf, XLSX ID는 xlsx/xls/ods/csv에 적용됩니다.
--extract-img / --no-extract-img / --ocr	convert --to md 용 이미지 추출 및 OCR 옵션입니다.
--image-mode file|base64|embed|omit	Markdown 내보내기 시 이미지 출력 방식을 제어합니다.
--ocr-placement image_md|main_md	OCR 텍스트를 이미지용 Markdown 에 쓸지 메인 Markdown 에 쓸지 제어합니다.
--heading-merge-mode punct_required|always|never	convert --to docx 시 "제목 + 본문" 병합 전략을 제어합니다.
--optimization <id>	최적화 프로필을 명시적으로 활성화합니다 (resources list optimizations 참고).
batch convert|validate ... --jobs <n> [--continue-on-error]	배치 처리 제어 옵션입니다.
--json / --quiet / --timing	터미널 스크립트에서 JSON을 출력하거나 로그를 줄이거나 소요 시간을 표시합니다.

punct_required 모드의 정확한 기본값은 。：！？.:!?입니다. 서식 설정에서 수정할 수 있으며, 값을 비우면 이 모드에서 병합하지 않습니다. 쉼표, 세미콜론, 열거 쉼표, 대시 및 줄임표는 기본값에 포함되지 않습니다.

CLI 추가 예시입니다. 최적화는 공개 리소스 ID를 먼저 확인하고, 보고서는 --report를 지정할 때만 저장합니다.

DocWenCLI.exe resources list optimizations --json
DocWenCLI.exe convert report.docx --to md --output-dir exports --optimization gongwen
DocWenCLI.exe validate input.md --check typo --report report.json

📝 Markdown 문법 규칙

Obsidian Markdown 확장 문법을 사용하나요? 새로 설치한 DocWen에서는 다음 네 가지 선택 확장이 기본적으로 꺼져 있습니다: structural_tables(병합 셀 및 여러 행의 머리글), captions_references(Number Suite 캡션과 상호 참조), extended_headings(H7–H9), typed_endnotes(유형별 미주).

• Markdown → Word: 설정 → Markdown 해석에서 필요한 확장을 활성화하거나 입력 방향의 Obsidian 확장 사용 사전 설정을 선택하세요. 꺼져 있으면 특수 마커가 일반 텍스트로 남을 수 있습니다.
• Word → Markdown: 설정 → Markdown 생성에서 해당 출력 확장 또는 그 페이지의 사전 설정을 켜세요. 꺼져 있으면 구조가 단순화되거나 정규화되며 경고가 표시될 수 있습니다.

원본 Markdown을 보관하고 생성된 DOCX를 확인하세요. Word 번호는 DocWen 변환 옵션을 따르며, 왕복 변환에서 원본 마커와 공백의 완전한 복원은 보장되지 않습니다. 자세한 내용은 Markdown 호환성 문서를 참조하세요.

제목 수준 매핑

Markdown 제목은 Word 제목과 1:1로 대응됩니다:

• 문서 제목과 부제목은 YAML 메타데이터에 둡니다.
• Markdown # Heading 1 → Word "Heading 1"
• Markdown ## Heading 2 → Word "Heading 2"
• 이와 같은 방식으로 최대 9레벨까지 지원합니다.

팁: Markdown의 1레벨 제목(#)을 문서 제목으로 쓰고, 2레벨 제목(##)부터 본문 제목으로 쓰고 싶다면 Word 템플릿에서 "Heading 1" 스타일을 제목처럼 보이도록(예: 가운데 정렬, 굵게, 큰 글꼴) 조정한 뒤, 설정에서 1레벨 제목 번호를 건너뛰는 번호 매기기 스킴을 선택하면 됩니다.

줄바꿈과 단락

기본 규칙: 일반 Markdown의 소프트 줄바꿈은 기본적으로 독립된 Word 단락을 만들지 않습니다. 줄마다 단락을 나누려면 설정 → Markdown 해석에서 각 줄을 별도 문단으로를 켜세요. 목록, 인용, 코드 및 명시적인 줄바꿈에는 각각의 규칙이 적용됩니다.

혼합 단락: 소제목을 본문 텍스트와 같은 단락으로 섞어야 하는 경우(기본 모드: "문장부호 필요"), 아래 조건을 만족해야 합니다:

1. 소제목이 종결 문장부호로 끝납니다(마침표/물음표/느낌표 등 다국어 종결 문장부호 지원).
2. 본문 텍스트가 소제목의 바로 다음 줄에 위치합니다.
3. 본문 줄은 특수 Markdown 요소(제목, 코드 블록, 표, 목록, 인용, 수식 블록, 구분선 등)가 아니어야 합니다.

예시:

## I. 업무 요구사항.
이번 회의에서는 모든 부서가 합의된 업무를 성실히 이행하도록 요청합니다...

위 두 줄은 하나의 단락으로 병합되며, "I. 업무 요구사항."은 소제목 형식을 유지하고 "이번 회의에서는..."은 본문 형식을 유지합니다.

주의:

• 소제목과 본문 사이에 빈 줄이 있으면 별도 단락으로 인식됩니다.
• 기본(“문장부호 필요” 모드)에서는 소제목이 종결 문장부호로 끝나지 않으면 빈 줄이 없어도 다음 줄과 병합되지 않습니다.
• 설정 → 입력 텍스트 → 마크다운 → 문서 — 서식 처리 → 제목+본문 병합 모드에서 병합 모드와 병합을 시작하는 문자를 변경할 수 있습니다.

구분선 양방향 변환

Markdown 구분선과 Word의 페이지/구역/가로선 요소 간의 양방향 변환을 지원합니다:

• DOCX → MD: Word의 페이지 나눔, 구역 나눔, 가로선을 Markdown 구분선으로 자동 변환합니다.
• MD → DOCX: Markdown ---, ***, ___를 대응되는 Word 요소로 자동 변환합니다.
• 구성 가능: 구체적인 매핑 관계는 설정 화면에서 사용자 지정할 수 있습니다.

작업 목록

GFM 작업 목록의 양방향 변환을 지원합니다:

- [ ] 할 일
- [x] 완료

• MD → DOCX: ☐ / ☑ 텍스트 접두사가 포함된 글머리 기호 목록으로 렌더링됩니다.
• DOCX → MD: ☐ / ☑ / ☒로 시작하는 목록 항목을 - [ ] / - [x]로 변환합니다.
• 글꼴 참고: ☐/☑는 일부 글꼴에서 표시되지 않을 수 있습니다. 필요한 경우 Word 템플릿에서 "Segoe UI Symbol" 등의 글꼴을 사용하세요.

이미지 임베드 및 크기

Obsidian/Wiki 및 표준 Markdown 이미지 임베드를 지원하며, 크기 지정(px)도 가능합니다:

![[image.png]]
![[image.png|300]]
![[image.png\|300]]
![alt](image.png =300x200)
![alt](image.png =300x)
![alt|300](image.png)

• 크기 미지정: 원본 크기 사용(페이지/셀 사용 가능 너비를 상한으로 제한)
• 크기 지정: 확대를 허용하되, 사용 가능 너비 상한은 적용
• 이미지 전용 단락: 단락 스타일 “Image”(가운데 정렬, 단일 줄 간격) 사용

링크 처리

Markdown -> DOCX 변환 시 클릭 가능한 링크를 지원합니다:

[Docwen](https://example.com)
[[Target]]
[[Target|Open target]]
<https://example.com>
<[email protected]>

• Markdown 링크와 Wiki 링크는 기본적으로 Word 하이퍼링크로 출력됩니다
• Wiki 링크는 대상 파일을 찾으면 로컬 file:/// 링크로 해석됩니다
• 꺾쇠 괄호 자동 링크는 https://... 와 이메일 mailto:... 를 지원합니다
• 일반 URL 자동 링크는 Markdown -> DOCX 요청별로 평가되며 기본값은 꺼짐입니다. configs/link.toml의 [non_embed_links].auto_link_bare_url로 활성화할 수 있습니다
• Markdown -> XLSX 에서는 DOCX 하이퍼링크 플레이스홀더를 만들지 않고 원래 링크 문법을 유지합니다

📖 상세 사용 가이드

Word → Markdown

1. .docx 파일을 프로그램 창으로 드래그합니다.
2. 내보내기 옵션을 선택하고 Markdown 내보내기를 클릭합니다.
3. YAML 메타데이터가 포함된 .md 파일을 생성합니다.

지원 형식:

• .docx - 표준 Word 문서
• .doc - 자동으로 생성 DOCX 후 처리
• .wps - WPS 문서를 자동 변환 후 처리
• .rtf, .odt - DOCX로 변환한 뒤 처리합니다. .doc, .wps와 마찬가지로 호환되는 로컬 Office 변환 프로그램이 필요합니다.

내보내기 옵션:

옵션	설명
이미지 추출	체크 시 문서의 이미지를 출력 폴더로 추출하고, MD에 이미지 링크를 삽입합니다.
이미지 OCR	이미지의 텍스트를 인식합니다. OCR 출력 위치 설정에 따라 이미지별 Markdown 파일 또는 기본 Markdown 파일에 저장합니다.
문서 유형 최적화	선택한 문서 유형에 맞는 최적화를 적용합니다. 예를 들어 중국 공문서에서 필드를 추출할 수 있습니다. 끄면 표준 변환을 사용합니다. 내장된 중국 공문서 및 중국 송장 내보내기 최적화는 중국어 간체 인터페이스(zh_CN)에서 호환되는 입력 경로가 있을 때만 GUI에 표시됩니다. 이 GUI 제한은 CLI/Machine에서 gongwen 또는 invoice_cn을 명시적으로 선택하는 것을 막지 않습니다.
원본 제목 번호 제거	체크 시 소제목 앞 번호(예: "一、", "（一）", "1." 등)를 제거하고 순수 제목 텍스트로 변환합니다.
새 제목 번호 추가	체크 시 제목 레벨에 따라 자동 번호를 추가합니다(번호 스킴은 설정에서 구성 가능).

Word/WPS 다단계 목록의 제목 번호는 내보낼 때 유지됩니다. 원본 제목 번호 제거를 켜면 제목 수준은 유지하면서 번호를 제거할 수 있습니다.

Markdown → Word

1. YAML 헤더가 포함된 .md 파일을 준비합니다.
2. 프로그램 창으로 드래그하고 해당 Word 템플릿을 선택합니다.
3. 대상 형식을 DOCX로 설정하고 생성 DOCX를 클릭하면 템플릿을 채워 문서를 저장합니다.

변환 옵션:

옵션	설명
원본 제목 번호 제거	체크 시 소제목 앞 번호를 제거합니다.
새 제목 번호 추가	체크 시 제목 레벨에 따라 자동 번호를 추가합니다.

주의: 소제목과 본문이 같은 단락으로 섞이는 문장이 있다면, MD 파일에서 줄바꿈 규칙을 엄격히 유지해야 합니다(위 "줄바꿈과 단락" 참고).

템플릿 스타일 자동 처리

Markdown → DOCX 변환 시 변환기는 템플릿 스타일을 자동으로 감지하고 처리합니다:

스타일 분류

단락 스타일(Paragraph Style): 단락 전체에 적용됩니다.

스타일	감지 동작	없을 때 주입	출처
Heading (1~9)	단락 스타일 감지	템플릿의 Heading 스타일	Word 기본
Code Block	단락 스타일 감지	Consolas 글꼴 + 회색 배경	소프트웨어 정의
Quote (1~9)	단락 스타일 감지	회색 배경 + 왼쪽 테두리	소프트웨어 정의
Formula Block	단락 스타일 감지	수식 전용 스타일	소프트웨어 정의
Separator (1~3)	단락 스타일 감지	아래쪽 테두리 단락 스타일	소프트웨어 정의

문자 스타일(Character Style): 선택된 텍스트에 적용됩니다.

스타일	감지 동작	없을 때 주입	출처
Inline Code	문자 스타일 감지	Consolas 글꼴 + 회색 음영	소프트웨어 정의
Inline Formula	문자 스타일 감지	수식 전용 스타일	소프트웨어 정의

표 스타일(Table Style): 표 전체에 적용됩니다.

스타일	감지 동작	없을 때 주입	출처
Three-Line Table	사용자 설정 우선	3선 표 스타일 정의	소프트웨어 정의
Grid Table	사용자 설정 우선	격자 표 스타일 정의	소프트웨어 정의

번호 정의(Numbering Definition): 목록 포맷에 사용됩니다.

유형	감지 동작	없을 때 처리
List Numbering	템플릿의 기존 목록 정의 스캔	decimal/bullet 프리셋 사용

스타일 이름 국제화

• Word 기본 스타일(heading 1~9):
  • 스타일 이름은 Word 표준 영문 이름(예: heading 1)을 사용합니다.
  • Word는 시스템 언어에 따라 로컬라이즈된 표시 이름을 자동으로 제공합니다.
• 소프트웨어 정의 스타일(Code Block, Quote, Formula, Separator, Table 등):
  • 새 관리 대상 스타일 이름은 인터페이스 언어가 아니라 일반 설정의 작업 출력 언어를 따릅니다. UI 언어를 바꿔도 기존 템플릿 스타일은 변경되지 않습니다. 권장 사항: 템플릿에서 스타일을 커스터마이즈하면 변환기는 이를 우선 사용하며, 템플릿에 없으면 내장 프리셋을 사용합니다.

스프레드시트 파일 처리

1. Excel/CSV → Markdown: .xlsx 또는 .csv 파일을 추가하고 Markdown 내보내기를 클릭합니다.
2. Markdown → Excel: Markdown 표를 XLSX로 내보낼 수 있습니다. 템플릿은 YAML 필드, 표 열·이미지 플레이스홀더와 병합/보호 셀을 지원합니다.

지원 형식:

• .xlsx - 표준 Excel 문서
• .xls - 자동으로 XLSX로 변환 후 처리
• .et - WPS 스프레드시트를 자동 변환 후 처리
• .csv - CSV 텍스트 표
• .tsv - TSV 탭 구분 표

텍스트 교정 기능

프로그램은 4가지 사용자 정의 교정 규칙을 제공합니다:

1. 문장부호 짝 검사 - 괄호/따옴표 등 짝이 맞는지 검사합니다.
2. 기호 교정 - 한/영 문장부호 혼용 등을 검사합니다.
3. 오탈자 검사 - 사용자 사전 기반으로 오탈자를 검사합니다.
4. 민감어 탐지 - 사용자 사전 기반으로 민감어를 탐지합니다.

사용자 사전: 설정 화면에서 오탈자/민감어 사전을 시각적으로 편집할 수 있습니다.

사용 방법:

1. 교정할 Word 문서 또는 Markdown 파일을 프로그램에 드래그합니다.
2. 필요한 교정 규칙을 체크합니다.
3. "텍스트 교정" 버튼을 클릭합니다.
4. 결과는 문서의 주석(코멘트)로 표시됩니다. Markdown 파일의 경우 JSON 보고서로 출력됩니다.

추가 설명(Markdown 교정 JSON 보고서):

• 엔진: text_rules + Markdown 어댑터 md_spell
• 출력 방식: 현재 CLI 교정 경로는 validate입니다. CLI envelope에는 --json을 사용하세요. --report는 선택적 보고서 파일 경로입니다.

🛠️ 템플릿 시스템

기존 템플릿 사용

설정 → 템플릿에서 DOCX/XLSX 템플릿의 활성화, 비활성화, 순서 및 기본값을 관리합니다. 기본 제공 템플릿은 읽기 전용이며 사용자 지정 템플릿은 쓰기 가능한 사용자 폴더에 저장됩니다. MSIX에서도 WindowsApps를 수정할 필요가 없습니다.

사용자 정의 템플릿

1. 기본 제공 템플릿을 복사하여 편집하거나 기존 DOCX/XLSX 파일을 가져옵니다.
2. Word, Excel 또는 WPS에서 복사본의 내용, 스타일 및 자리 표시자를 수정합니다. 아래 규칙을 참고하세요.
3. 저장한 후 DocWen 목록을 새로 고칩니다. 다시 시작할 필요가 없습니다.

플레이스홀더 사용법

Word 템플릿 플레이스홀더

YAML 필드 플레이스홀더: 템플릿에서 {{Field Name}} 형식을 사용하면, 변환 시 Markdown 파일의 YAML 헤더에서 해당 필드 값으로 치환됩니다.

플레이스홀더	설명
{{Title}}	문서 제목(아래 우선순위 참고)
{{Body}}	Markdown 본문 삽입 위치
기타	임의의 사용자 정의 필드 지원

제목(Title) 가져오기 우선순위:

우선순위	출처	설명
1	YAML Title	최우선
2	YAML aliases	리스트의 첫 원소 또는 문자열 값
3	파일명	.md 확장자를 제외한 파일명

다국어 지원: 제목/본문 플레이스홀더는 다국어를 지원합니다. 예: 제목 {{title}}, {{标题}}, {{Titel}} 등, 본문 {{body}}, {{正文}}, {{Inhalt}} 등.

Excel 템플릿 플레이스홀더

XLSX 템플릿은 YAML 필드, 세로 {{↓필드}}와 가로 {{→필드}}, 이미지 플레이스홀더와 병합/보호 셀을 지원합니다.

1. YAML 필드 플레이스홀더 {{Field Name}}

Markdown 파일의 YAML 헤더에 있는 단일 값을 채웁니다:

---
ReportName: 2024 Annual Sales Statistics
Unit: Sales Dept
---

템플릿의 {{ReportName}}, {{Unit}}가 해당 값으로 치환됩니다. Title 필드도 동일한 우선순위를 따릅니다.

2. 열 채우기 플레이스홀더 {{↓Field Name}}

Markdown 표에서 데이터를 추출해 플레이스홀더 위치부터 아래로 행 단위로 채웁니다:

| ProductName | Quantity |
|:--- |:--- |
| Product A | 100 |
| Product B | 200 |

{{↓ProductName}}는 "Product A"로 치환되며, 다음 행은 "Product B"가 채워집니다.

3. 행 채우기 플레이스홀더 {{→Field Name}}

Markdown 표에서 데이터를 추출해 플레이스홀더 위치부터 오른쪽으로 열 단위로 채웁니다:

| Month |
|:--- |
| Jan |
| Feb |
| Mar |

{{→Month}}는 오른쪽으로 "Jan", "Feb", "Mar" 순서로 채워집니다.

병합 셀 처리:

• Markdown -> Excel 은 템플릿에 원래 있던 merged ranges 를 계속 유지합니다.
• 연속된 {{↓Field Name}} 플레이스홀더로 구성된 알려진 세로형 템플릿 영역에서는 Markdown 표의 명시적 < / ^ 병합 표시로부터 직사각형 병합을 복원할 수 있습니다.
• 앞뒤 공백을 제거한 내용이 정확히 < 또는 ^ 인 셀만 병합 판정에 참여하며, \< 와 \^ 는 리터럴 텍스트로 유지됩니다.
• 잘못된 직사각형이거나 템플릿의 기존 merged ranges 와 충돌하면 템플릿 구조를 강제로 덮어쓰지 않고 경고를 남긴 뒤 일반 텍스트로 강등합니다.

다중 표 데이터 병합: 동일한 헤더 이름을 가진 표가 Markdown에 여러 개 있으면, 데이터를 순서대로 병합해 연속으로 채웁니다.

🔌 Obsidian 플러그인

변환기와 함께 동작하는 동반 Obsidian 플러그인은 별도 저장소로 제공됩니다:

핵심 기능

• 🚀 원클릭 실행 - 사이드바 아이콘으로 변환기 빠르게 실행
• 📂 자동 전달 - 현재 열려 있는 파일 경로를 자동으로 전달
• 🔄 열린 창 사용 - 변환기를 다시 시작하지 않고 다른 파일을 엽니다.

플러그인 사용 방법

DocWen Assistant는 Windows와 Linux 데스크톱 호스트를 지원합니다. Windows Microsoft Store 설치는 자동 감지를 사용할 수 있고, Linux에서는 호환되는 압축 해제 패키지를 수동으로 선택합니다. Assistant는 현재 macOS를 지원하지 않습니다.

1. 처음 클릭 → 변환기를 실행하고 현재 파일을 엽니다.
2. 파일을 연 상태에서 다시 클릭 → 현재 입력 파일을 해당 파일로 바꿉니다(단일 파일 모드).
3. 열린 파일 없이 다시 클릭 → 변환기 창을 앞으로 가져옵니다.

설치

DocWen을 따로 설치한 다음 호환되는 DocWen Assistant 공개 릴리스를 선택하세요. 플러그인이 본체를 설치하지는 않습니다. 이 가이드의 고정 버전 번호가 아니라 릴리스 안내에서 호환 버전을 확인하세요. 연동에는 Machine Protocol v2 및 Artifact Bundle v3를 사용합니다.

🔌 OpenClaw (Plugin + Skill)

docwen-openclaw는 별도로 설치한 DocWen으로 OpenClaw에서 로컬 파일을 변환하고 교정합니다. 공개 릴리스에서 호환 버전을 확인하세요. 계약은 Machine Protocol v2 및 Artifact Bundle v3를 참고하세요.

❓ 자주 묻는 질문 (FAQ)

변환이 실패하면 어떻게 하나요?

• 파일이 다른 프로그램에서 사용 중인지 확인합니다.
• 파일 형식이 올바른지 확인합니다.
• 설정의 "현재 실제 로그 파일 경로"를 확인하거나 시스템 사용자 로그 디렉터리에서 오류 로그를 확인하세요. 패키지 검증에서 DOCWEN_LOG_DIR를 사용했다면 해당 덮어쓴 디렉터리를 확인하세요.

템플릿이 표시되지 않나요?

• 설정 → 템플릿에서 활성화되어 있고 출력 형식과 일치하는지 확인하세요.
• DOCX/XLSX 파일이 정상적으로 열리는지 확인하세요.
• 외부에서 수정한 후 목록을 새로 고치고 새 파일은 가져오세요.

교정 기능이 동작하지 않나요?

• CLI validate는 .md와 .docx를 직접 검사합니다. .doc, .wps, .rtf, .odt도 받지만 먼저 사용 가능한 로컬 Office 프로그램으로 DOCX로 변환한 뒤 교정합니다. 실패 시 변환 의존성을 확인하세요.
• 문서에 편집 가능한 텍스트가 있는지 확인합니다.
• 설정에서 교정 규칙이 활성화되어 있는지 확인합니다.

출력 형식이 기대와 다르나요?

• 설정 → 템플릿을 엽니다. 기본 제공 템플릿은 복사한 후 편집하고 사용자 지정 템플릿은 직접 편집할 수 있습니다.
• Word, Excel 또는 WPS에서 스타일을 조정하고 저장한 후 목록을 새로 고칩니다.
• 새 파일을 생성하기 전에 사용자 지정 템플릿을 선택하세요.

Excel → Markdown 변환 후 수식 셀이 비어 있나요?

이는 정상 동작입니다. 프로그램은 수식 자체가 아니라 셀의 캐시된 값을 읽습니다.

기술적 이유:

• Excel 파일에서 수식 셀은 수식과 마지막 계산 결과(캐시 값)를 함께 저장합니다.
• 프로그램은 data_only=True 모드를 사용해 캐시된 값만 읽습니다.
• 파일이 Excel에서 열려 계산/저장된 적이 없으면 캐시 값이 비어 있을 수 있습니다.

해결 방법:

1. Excel에서 파일을 엽니다.
2. 수식 계산이 완료될 때까지 기다립니다.
3. 파일을 저장합니다.
4. 다시 변환합니다.

🔒 보안 기능

DocWen은 사용자 컴퓨터에서 파일을 처리하며 파일 업로드, 원격 측정, 온라인 다운로드 또는 네트워크 서비스 기능을 제공하지 않습니다. 자체 Python 구성 요소의 네트워크 접근을 제한합니다. 이 보호 기능을 시작할 수 없으면 DocWen은 실행을 계속하지 않습니다.

별도로 실행되는 Word/Office, WPS, LibreOffice 등의 프로그램과 관련 보조 프로세스는 각 프로그램과 시스템의 네트워크 설정을 따르며 이 제한의 적용 대상이 아닙니다. 민감한 파일을 처리할 때는 해당 프로그램의 설정도 확인하세요.

보호 기능의 구현과 한계는 아키텍처 설명을 참고하세요. 프로그램이 시작되지 않거나 변환에 실패하면 문제 해결 안내를 확인할 수 있습니다.

📜 라이선스

이 프로젝트는 GNU Affero General Public License v3.0 (AGPL-3.0) 라이선스를 따릅니다.

• 이 프로젝트는 PyMuPDF(AGPL-3.0)를 사용하므로, 전체 프로젝트도 AGPL-3.0을 따릅니다.
• 현재 GUI 는 지원되는 호스트 경로에서 PySide6-Fluent-Widgets(QFluentWidgets)를 사용할 수 있습니다. 이 의존성은 GPLv3 / 상용 라이선스 이중 라이선스를 사용하며, 이 저장소는 계속 AGPL로 배포됩니다.
• 소프트웨어를 자유롭게 사용/수정/배포할 수 있습니다.
• 소프트웨어를 수정해 네트워크를 통해 서비스를 제공하는 경우, 수정된 소스 코드를 사용자에게 제공해야 합니다.
• 자세한 라이선스 정보는 LICENSE를 참고하세요.
• 서드파티 구성요소 고지는 LICENSE_THIRD_PARTY.txt, 배포 요약은 NOTICE.txt에서 확인할 수 있습니다.

연락처

• GitHub: https://github.com/ZHYX91/docwen
• 작성자 이메일: [email protected]

---

작성자: ZhengYX