docs: 전체 문서 말투 통일 및 마크다운 렌더링 수정

es-toolkit 스타일의 친근한 존댓말(~예요/~해요)로 전체 문서 통일.
adding-formats.md에서 리스트 앞 빈 줄 누락으로 렌더링이 깨지던
문제 수정. architecture.md 제목 한글화.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: wkdgus1164

docs/adding-formats.md

@@ -1,12 +1,12 @@
-# Adding New Formats
+# 포맷 확장 가이드
 
-새 입력 포맷(Parser)이나 출력 포맷(Writer)을 추가하는 가이드.
+새 입력 포맷(Parser)이나 출력 포맷(Writer)을 추가하는 방법을 안내해요.
 
 ## 새 Parser 추가
 
 ### 1. 파서 패키지 생성
 
-`src/ureca_document_parser/` 아래에 확장자명 디렉토리를 만들고 `parser.py`를 생성한다.
+`src/ureca_document_parser/` 아래에 확장자명 디렉토리를 만들고 `parser.py`를 생성하세요.
 
 ```python
 # src/ureca_document_parser/pdf/parser.py
@@ -46,7 +46,7 @@ class PdfParser:
         return parse_pdf(filepath)
 ```
 
-`__init__.py`에서 re-export한다:
+`__init__.py`에서 re-export해 주세요.
 
 ```python
 # src/ureca_document_parser/pdf/__init__.py
@@ -55,14 +55,15 @@ from .parser import PdfParser
 __all__ = ["PdfParser"]
 ```
 
-핵심 규칙:
-- `protocols.py`의 `Parser` Protocol 시그니처를 따른다
-- `models.py`의 `Document`를 반환한다
-- 선택적 의존성은 **함수 내부에서 lazy import**한다
+핵심 규칙은 다음과 같아요.
+
+- `protocols.py`의 `Parser` Protocol 시그니처를 따라야 해요
+- `models.py`의 `Document`를 반환해야 해요
+- 선택적 의존성은 **함수 내부에서 lazy import**해야 해요
 
 ### 2. 레지스트리에 등록
 
-`src/ureca_document_parser/registry.py`의 `_auto_register()` 함수에 추가한다.
+`src/ureca_document_parser/registry.py`의 `_auto_register()` 함수에 추가하세요.
 
 ```python
 def _auto_register(registry: FormatRegistry) -> None:
@@ -75,7 +76,7 @@ def _auto_register(registry: FormatRegistry) -> None:
         pass  # pymupdf 미설치 시 건너뜀
 ```
 
-### 3. (선택) pyproject.toml에 optional dependency 추가
+### 3. pyproject.toml에 optional dependency 추가 (선택)
 
 ```toml
 [project.optional-dependencies]
@@ -85,12 +86,14 @@ all = ["ureca_document_parser[pdf,ocr]"]  # all에도 추가
 
 ### 완료
 
-이제 다음이 자동으로 동작한다:
+이제 다음이 자동으로 동작해요.
 
 ```python
 from ureca_document_parser import get_registry
 doc = get_registry().parse("document.pdf")
+```
 
+```bash
 # CLI
 ureca_document_parser document.pdf -o output.md
 ```
@@ -101,7 +104,7 @@ ureca_document_parser document.pdf -o output.md
 
 ### 1. Writer 모듈 생성
 
-`src/ureca_document_parser/writers/` 아래에 새 파일을 만든다.
+`src/ureca_document_parser/writers/` 아래에 새 파일을 만드세요.
 
 ```python
 # src/ureca_document_parser/writers/html.py
@@ -164,10 +167,14 @@ except ImportError:
 
 ### 완료
 
+이제 다음이 자동으로 동작해요.
+
 ```python
 from ureca_document_parser import get_registry
 md = get_registry().write(doc, "html")
+```
 
+```bash
 # CLI
 ureca_document_parser document.hwp -f html -o output.html
 ```
@@ -176,10 +183,10 @@ ureca_document_parser document.hwp -f html -o output.html
 
 ## 체크리스트
 
-새 포맷 추가 시 확인 사항:
+새 포맷을 추가할 때 다음 사항을 확인하세요.
 
-- [ ] Protocol 시그니처와 호환되는 클래스 작성
-- [ ] `models.py`의 `Document`만 사용하여 입출력
-- [ ] `registry.py:_auto_register()`에 `try/except ImportError`로 등록
-- [ ] 선택적 의존성은 `pyproject.toml`의 `[project.optional-dependencies]`에 추가
-- [ ] lazy import 사용 (함수 내부에서 import)
+- [ ] Protocol 시그니처와 호환되는 클래스를 작성했나요?
+- [ ] `models.py`의 `Document`만 사용해서 입출력하나요?
+- [ ] `registry.py`의 `_auto_register()`에 `try/except ImportError`로 등록했나요?
+- [ ] 선택적 의존성을 `pyproject.toml`의 `[project.optional-dependencies]`에 추가했나요?
+- [ ] lazy import를 사용하고 있나요? (함수 내부에서 import)

docs/api/index.md

@@ -1,14 +1,14 @@
 # API 레퍼런스
 
-`ureca_document_parser`의 공개 API 문서입니다.
+`ureca_document_parser`의 공개 API 문서예요.
 
 ## 모듈 구조
 
 | 모듈 | 설명 |
 |------|------|
-| [`ureca_document_parser.models`](models.md) | Document 모델 — 파서와 Writer의 공유 데이터 구조 |
-| [`ureca_document_parser.hwp`](parsers.md#hwp) | HWP v5 바이너리 파서 |
-| [`ureca_document_parser.hwpx`](parsers.md#hwpx) | HWPX (ZIP+XML) 파서 |
+| [`ureca_document_parser.models`](models.md) | Document 모델 — 파서와 Writer가 공유하는 데이터 구조 |
+| [`ureca_document_parser.hwp`](parsers.md#hwp-파서) | HWP v5 바이너리 파서 |
+| [`ureca_document_parser.hwpx`](parsers.md#hwpx-파서) | HWPX (ZIP+XML) 파서 |
 | [`ureca_document_parser.writers.markdown`](writers.md) | Markdown Writer |
 | [`ureca_document_parser.registry`](registry.md) | FormatRegistry — 파서/Writer 자동 라우팅 |
 

docs/api/models.md

@@ -1,6 +1,6 @@
 # Document 모델
 
-파서와 Writer가 공유하는 중간 표현(IR) 데이터 모델입니다. 모든 파서는 `Document`를 생산하고, 모든 Writer는 `Document`를 소비합니다.
+파서와 Writer가 공유하는 중간 표현(IR) 데이터 모델이에요. 모든 파서는 `Document`를 생산하고, 모든 Writer는 `Document`를 소비해요.
 
 ```
 Document

docs/api/parsers.md

@@ -1,12 +1,12 @@
 # 파서 (HWP / HWPX)
 
-문서 파일을 읽어 [`Document`](models.md) 모델로 변환하는 파서입니다.
+문서 파일을 읽어 [`Document`](models.md) 모델로 변환하는 파서예요.
 
-모든 파서는 [`Parser` Protocol](registry.md)을 구현합니다.
+모든 파서는 [`Parser` Protocol](registry.md)을 구현해요.
 
 ## HWP 파서
 
-HWP v5 바이너리 형식(아래한글 2007 이후)을 파싱합니다. 내부적으로 `olefile`을 사용하여 OLE2 컨테이너를 읽고, 레코드 스트림에서 텍스트와 표를 추출합니다.
+HWP v5 바이너리 형식(아래한글 2007 이후)을 파싱해요. 내부적으로 `olefile`을 사용해서 OLE2 컨테이너를 읽고, 레코드 스트림에서 텍스트와 표를 추출해요.
 
 ::: ureca_document_parser.hwp.parser.HwpParser
     options:
@@ -15,7 +15,7 @@ HWP v5 바이너리 형식(아래한글 2007 이후)을 파싱합니다. 내부
 
 ## HWPX 파서
 
-HWPX(한글 OOXML) 형식을 파싱합니다. ZIP 아카이브 내 XML 파일을 `xml.etree.ElementTree`로 처리합니다.
+HWPX(한글 OOXML) 형식을 파싱해요. ZIP 아카이브 내 XML 파일을 `xml.etree.ElementTree`로 처리해요.
 
 ::: ureca_document_parser.hwpx.parser.HwpxParser
     options:

docs/api/registry.md

@@ -1,6 +1,6 @@
 # FormatRegistry
 
-파서와 Writer를 중앙에서 관리하는 레지스트리입니다. 파일 확장자 기반으로 파서를 자동 라우팅하고, 포맷 이름으로 Writer를 선택합니다.
+파서와 Writer를 중앙에서 관리하는 레지스트리예요. 파일 확장자 기반으로 파서를 자동 라우팅하고, 포맷 이름으로 Writer를 선택해요.
 
 ## Protocol
 

docs/api/writers.md

@@ -1,12 +1,12 @@
 # Writer
 
-[`Document`](models.md) 모델을 출력 포맷 문자열로 변환하는 Writer입니다.
+[`Document`](models.md) 모델을 출력 포맷 문자열로 변환하는 Writer예요.
 
-모든 Writer는 [`Writer` Protocol](registry.md)을 구현합니다.
+모든 Writer는 [`Writer` Protocol](registry.md)을 구현해요.
 
 ## Markdown Writer
 
-Document를 GitHub Flavored Markdown으로 변환합니다. 헤딩, 리스트, 테이블, 이미지 등 구조를 보존합니다.
+Document를 GitHub Flavored Markdown으로 변환해요. 헤딩, 리스트, 테이블, 이미지 등 구조를 보존해요.
 
 ::: ureca_document_parser.writers.markdown.MarkdownWriter
     options:

docs/architecture.md

@@ -1,6 +1,8 @@
-# Architecture
+# 아키텍처
 
-## Pipeline
+## 파이프라인
+
+입력 파일이 변환되는 전체 흐름이에요.
 
 ```mermaid
 flowchart LR
@@ -14,7 +16,9 @@ flowchart LR
     G --> H["LangChain Documents\n(chunks)"]
 ```
 
-## Module Dependency Graph
+## 모듈 의존성 그래프
+
+각 모듈이 어떤 모듈에 의존하는지 보여줘요. 화살표 방향이 의존 방향이에요.
 
 ```mermaid
 graph TD
@@ -57,9 +61,11 @@ graph TD
     styles["styles.py"]
 ```
 
-핵심 원칙: **파서와 Writer는 `models.py`에만 의존**한다. 서로를 직접 import하지 않는다.
+핵심 원칙은 **파서와 Writer가 `models.py`에만 의존**하는 거예요. 서로를 직접 import하지 않아요.
 
-## Document Model
+## Document 모델
+
+`Document`는 파싱 결과의 중간 표현(IR)이에요. 모든 파서는 이 모델을 생산하고, 모든 Writer는 이 모델을 소비해요.
 
 ```mermaid
 classDiagram
@@ -118,16 +124,16 @@ classDiagram
 
 ## FormatRegistry
 
-`FormatRegistry`는 파서와 Writer를 중앙에서 관리한다.
+`FormatRegistry`는 파서와 Writer를 중앙에서 관리하는 레지스트리예요.
 
-- **파서 등록**: 파일 확장자(`.hwp`, `.hwpx`)를 키로 파서 클래스를 매핑
-- **Writer 등록**: 포맷 이름(`markdown`)을 키로 Writer 클래스를 매핑
-- **자동 등록**: `get_registry()` 최초 호출 시 `_auto_register()`가 내장 파서/Writer를 등록
-- **선택적 의존성**: `try/except ImportError`로 처리하여 없는 의존성은 건너뜀
+- **파서 등록** — 파일 확장자(`.hwp`, `.hwpx`)를 키로 파서 클래스를 매핑해요
+- **Writer 등록** — 포맷 이름(`markdown`)을 키로 Writer 클래스를 매핑해요
+- **자동 등록** — `get_registry()`를 최초 호출하면 `_auto_register()`가 내장 파서/Writer를 등록해요
+- **선택적 의존성** — `try/except ImportError`로 처리해서 없는 의존성은 건너뛰어요
 
 ## Protocol 기반 인터페이스
 
-ABC 대신 `typing.Protocol`을 사용하여 구조적 서브타이핑을 구현한다.
+ABC 대신 `typing.Protocol`을 사용해서 구조적 서브타이핑을 구현했어요.
 
 ```python
 class Parser(Protocol):
@@ -145,29 +151,31 @@ class Writer(Protocol):
     def write(doc: Document) -> str: ...
 ```
 
-- 상속 불필요 — 메서드 시그니처만 맞으면 Protocol 호환
-- `@staticmethod` — 현재 파서/Writer가 모두 무상태이므로 인스턴스 불필요
+- 상속이 필요 없어요 — 메서드 시그니처만 맞으면 Protocol과 호환돼요
+- `@staticmethod`을 사용해요 — 현재 파서/Writer가 모두 무상태이므로 인스턴스가 필요 없어요
 
 ## HWP 파서 내부 구조
 
 ### Record 파싱
 
-HWP 바이너리는 레코드 스트림이다. 각 레코드의 헤더는 4바이트:
+HWP 바이너리는 레코드 스트림이에요. 각 레코드의 헤더는 4바이트로 구성돼요.
 
 ```
 [tag: 10비트][level: 10비트][size: 12비트]
 ```
 
-`size == 0xFFF`이면 다음 4바이트가 실제 크기를 담는다.
+`size == 0xFFF`이면 다음 4바이트가 실제 크기를 담고 있어요.
 
 ### Character 스캐닝
 
-`scan_para_chars()`는 PARA_TEXT 바이트를 순회하여 `CharInfo`를 yield한다. 확장 제어문자(16바이트)와 일반 문자(2바이트)를 구분한다.
+`scan_para_chars()`는 PARA_TEXT 바이트를 순회하며 `CharInfo`를 yield해요. 확장 제어문자(16바이트)와 일반 문자(2바이트)를 올바르게 구분해요.
 
-`extract_text()`와 `has_table_marker()`는 모두 이 제너레이터를 사용하여 중복 로직을 제거했다.
+`extract_text()`와 `has_table_marker()`는 모두 이 제너레이터를 사용해서 중복 로직을 제거했어요.
 
 ### 테이블 파싱 3단계
 
+테이블은 세 단계에 걸쳐 파싱돼요.
+
 ```mermaid
 flowchart TD
     A["Phase 1: find_table_ctrl()"] -->|"ctrl_level"| B["Phase 2: read_table_dimensions()"]
@@ -181,4 +189,4 @@ flowchart TD
 
 ### RecordCursor
 
-인덱스 기반 `while i < n` 대신 `RecordCursor` 클래스로 명시적 순회를 구현한다.
+인덱스 기반 `while i < n` 대신 `RecordCursor` 클래스로 명시적 순회를 구현했어요.

docs/getting-started.md

@@ -10,6 +10,8 @@ uv add ureca_document_parser
 
 ### 선택적 의존성
 
+필요한 기능에 따라 추가 의존성을 설치할 수 있어요.
+
 ```bash
 # LangChain 청크 분할
 uv add ureca_document_parser[langchain]
@@ -26,6 +28,8 @@ uv add ureca_document_parser[all]
 
 ### 개발 환경
 
+소스 코드를 직접 수정하고 싶다면 다음과 같이 설정하세요.
+
 ```bash
 git clone https://github.com/ureca-corp/document_parser.git
 cd document_parser
@@ -36,6 +40,8 @@ uv sync --extra dev
 
 ### 기본 변환
 
+HWP 또는 HWPX 파일을 Markdown으로 변환할 수 있어요.
+
 ```bash
 ureca_document_parser document.hwp -o output.md
 ureca_document_parser document.hwpx -o output.md
@@ -55,8 +61,12 @@ uv run python -m ureca_document_parser document.hwp -o output.md
 
 ## 라이브러리 사용법
 
+세 가지 레벨의 API를 제공해요. 용도에 맞게 선택하세요.
+
 ### 간편 변환 (High-level)
 
+파일 경로만 전달하면 바로 변환돼요.
+
 ```python
 from ureca_document_parser import convert
 
@@ -65,6 +75,8 @@ convert("document.hwp", "output.md")
 
 ### 레지스트리 기반 (Mid-level)
 
+파싱과 출력을 분리해서 제어할 수 있어요.
+
 ```python
 from ureca_document_parser import get_registry
 
@@ -75,6 +87,8 @@ md = registry.write(doc, "markdown")
 
 ### 직접 파서/Writer 사용 (Low-level)
 
+특정 파서나 Writer를 직접 import해서 사용할 수도 있어요.
+
 ```python
 from ureca_document_parser.hwp import HwpParser
 from ureca_document_parser.writers.markdown import MarkdownWriter
@@ -85,7 +99,7 @@ md = MarkdownWriter.write(doc)
 
 ### LangChain 청크 분할
 
-RAG 파이프라인에서 사용할 수 있는 LangChain Document 리스트를 생성합니다.
+RAG 파이프라인에서 사용할 수 있는 LangChain Document 리스트를 생성해요.
 
 ```python
 from ureca_document_parser import convert_to_chunks
@@ -102,5 +116,5 @@ for chunk in chunks:
 ```
 
 !!! note
-    `convert_to_chunks`를 사용하려면 `langchain` 추가 의존성이 필요합니다:
+    `convert_to_chunks`를 사용하려면 `langchain` 추가 의존성이 필요해요:
     `uv add ureca_document_parser[langchain]`

docs/index.md

@@ -1,14 +1,14 @@
 # ureca_document_parser
 
-**Multi-format document parser and converter** — 한국어 워드프로세서(아래한글) HWP/HWPX 파일을 Markdown으로 변환합니다.
+한국어 워드프로세서(아래한글) HWP/HWPX 파일을 Markdown으로 변환하는 현대적인 문서 파서예요.
 
 ## 주요 기능
 
-- **HWP v5 바이너리 파싱** — `olefile` 기반, 텍스트·표·이미지 추출
-- **HWPX (OOXML) 파싱** — ZIP+XML 구조, 표준 라이브러리만 사용
-- **Markdown 출력** — 헤딩, 리스트, 테이블 등 구조 보존
-- **LangChain 연동** — RAG 파이프라인용 청크 분할 지원
-- **확장 가능한 아키텍처** — Protocol 기반 파서/Writer 등록
+- **HWP v5 바이너리 파싱** — `olefile` 기반으로 텍스트, 표, 이미지를 추출해요
+- **HWPX (OOXML) 파싱** — ZIP+XML 구조를 표준 라이브러리만으로 처리해요
+- **Markdown 출력** — 헤딩, 리스트, 테이블 등 문서 구조를 보존해요
+- **LangChain 연동** — RAG 파이프라인용 청크 분할을 지원해요
+- **확장 가능한 아키텍처** — Protocol 기반으로 새 파서/Writer를 쉽게 등록할 수 있어요
 
 ## 퀵스타트
 

mkdocs.yml

@@ -59,7 +59,7 @@ nav:
   - 시작하기: getting-started.md
   - 가이드:
       - 아키텍처: architecture.md
-      - 포맷 확장: adding-formats.md
+      - 포맷 확장 가이드: adding-formats.md
   - API 레퍼런스:
       - 개요: api/index.md
       - Document 모델: api/models.md