docs: FC 공백 보존 원칙 지침 문서를 추가합니다

XHTML 원본의 공백을 그대로 MDX로 옮기는 원칙과
구체적 사례(convert_li join)를 정리합니다.

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

Author: jk-kim0

confluence-mdx/docs/fc-whitespace-preservation.md

@@ -0,0 +1,128 @@
+# Forward Converter 공백 보존 원칙
+
+## 핵심 원칙
+
+Forward Converter(FC)는 XHTML 원본의 공백, 단락 구조를 **있는 그대로** MDX로 변환해야 한다.
+FC 출력의 형태는 XHTML 원문이 결정한다. XHTML 원문과 무관하게 "이렇게 생겨야 한다"는 고정된 출력 형태는 없다.
+
+### 하지 말아야 할 것
+
+- XHTML에 없는 공백을 추가하지 않는다.
+- XHTML에 있는 공백을 임의로 제거하지 않는다.
+- 빈 `<p>` 요소의 콘텐츠를 필터링하지 않는다 (XHTML에 존재하는 구조이다).
+- FC 출력 형태를 미리 정해놓고 그에 맞추지 않는다.
+
+### 해야 할 것
+
+- XHTML 텍스트 노드의 공백을 그대로 MDX로 옮긴다.
+- `<p>` 요소의 콘텐츠(빈 단락 포함)를 보존한다.
+- FC가 삽입하는 구조적 마커(`<br/>` 등)와 XHTML 원본 공백을 구분한다.
+
+## 구체적 사례: `convert_li`의 `join`
+
+### 문제 상황
+
+`convert_li()`에서 `<li>` 내 여러 `<p>` 요소를 MDX 한 줄로 합칠 때,
+`<p>` 경계를 `<br/>`로 표현하고 `' '.join(li_itself)`로 연결했다.
+
+이 `' '.join()`은 **모든 항목 사이에 공백 하나를 삽입**하는데,
+이 공백은 XHTML 원문에 존재하지 않는다.
+
+### XHTML → FC 출력 추적 예시
+
+#### 예시 1: `<br/>` 뒤 빈 `<p>`
+
+```xml
+<li>
+  <p>경우<br/> </p>
+  <ac:image>...</ac:image>
+  <p> </p>
+</li>
+```
+
+`<p>` 경계에서 `<br/>` 구분자가 삽입되므로 `li_itself` 구성은:
+
+| 인덱스 | 출처 | 값 | 설명 |
+|--------|------|----|------|
+| 0 | 첫 번째 `<p>` | `'경우<br/> '` | XHTML 텍스트 노드의 trailing space 보존 |
+| 1 | `<br/>` 구분자 | `'<br/>'` | FC가 `<p>` 경계를 표현하기 위해 삽입 |
+| 2 | `<p> </p>` | `' '` | 빈 단락의 공백 콘텐츠 보존 |
+
+**`' '.join()` (잘못됨):**
+
+```
+'경우<br/> ' + ' ' + '<br/>' + ' ' + ' '
+→ '경우<br/>  <br/>  '
+```
+
+join이 삽입한 공백(` `)이 XHTML 원본 공백과 합쳐져 이중 공백이 된다.
+
+**`''.join()` (올바름):**
+
+```
+'경우<br/> ' + '<br/>' + ' '
+→ '경우<br/> <br/> '
+```
+
+XHTML 원본의 공백만 존재한다.
+
+#### 예시 2: `<br/>` 없는 `<p>` + 빈 `<p>`
+
+```xml
+<li>
+  <p>클릭합니다</p>
+  <ac:image>...</ac:image>
+  <p></p>
+</li>
+```
+
+| 인덱스 | 출처 | 값 |
+|--------|------|----|
+| 0 | 첫 번째 `<p>` | `'클릭합니다'` |
+| 1 | `<br/>` 구분자 | `'<br/>'` |
+| 2 | `<p></p>` | `''` |
+
+**`' '.join()` (잘못됨):** `'클릭합니다 <br/> '` — `<br/>` 앞뒤 공백은 XHTML에 없음
+
+**`''.join()` (올바름):** `'클릭합니다<br/>'` — XHTML 그대로
+
+#### 예시 3: 연속 `<p>` 텍스트
+
+```xml
+<li>
+  <p>Text A</p>
+  <p>Text B</p>
+</li>
+```
+
+| 인덱스 | 출처 | 값 |
+|--------|------|----|
+| 0 | 첫 번째 `<p>` | `'Text A'` |
+| 1 | `<br/>` 구분자 | `'<br/>'` |
+| 2 | 두 번째 `<p>` | `'Text B'` |
+
+**`' '.join()` (잘못됨):** `'Text A <br/> Text B'` — 경계 공백은 XHTML에 없음
+
+**`''.join()` (올바름):** `'Text A<br/>Text B'` — `<br/>`가 줄바꿈 역할, 추가 공백 불필요
+
+## 수정 방법
+
+```python
+# 변경 전 (XHTML에 없는 공백 삽입)
+itself = ' '.join(li_itself)
+
+# 변경 후 (XHTML 원본 공백만 보존)
+itself = ''.join(li_itself)
+```
+
+한 줄 변경이다. 각 `<p>`의 SingleLineParser 출력에 이미 XHTML 원문의 공백이
+보존되어 있으므로, join 시 추가 공백을 넣지 않으면 된다.
+
+## 일반 원칙: FC 버그 수정 시 판단 기준
+
+FC 출력이 "올바른지" 판단할 때:
+
+1. **XHTML 원문을 확인**한다 — FC 출력을 보기 전에, 입력인 XHTML이 어떤 구조인지 파악
+2. **XHTML의 공백/구조를 그대로 MDX에 반영하는지** 확인한다
+3. FC가 삽입하는 구조적 요소(`<br/>` 구분자 등)는 XHTML 원본 공백과 **분리**해서 처리한다
+4. "출력이 이렇게 생겨야 한다"는 고정관념 없이, XHTML 원문에서 출력을 **도출**한다