마크다운 변환 문제 해결: 표, 코드, 이미지 오류 총정리

마크다운을 깔끔하게 작성했습니다. "변환" 버튼을 눌렀습니다. 그런데 결과물이 기대와 전혀 다릅니다 — 표는 엉망이 되고, 코드 블록은 밋밋한 텍스트이며, 이미지는 사라지고, LaTeX 수식은 알 수 없는 문자열로 변해 있습니다.
익숙한 상황이신가요? 마크다운을 Word나 PDF로 변환할 때는 늘 비슷한 몇 가지 방식으로 실패합니다. 이 가이드는 가장 흔한 15가지 문제를 다룹니다 — 각각의 실제 원인과 구체적인 해결법을 함께 정리했습니다.
빠른 참고: 문제 → 해결법
| 문제 | 가장 가능성 높은 원인 | 빠른 해결법 |
|---|---|---|
| 테이블 열이 어긋남 | 파이프 구문 누락 또는 불일치 | 린터로 테이블 검증 |
| 코드 블록 하이라이팅 손실 | 언어 식별자 미지정 | ``` 뒤에 언어 태그 추가 |
| 이미지 미표시 | 경로 오류 또는 미지원 프로토콜 | 절대 URL 사용 또는 base64로 임베드 |
| LaTeX가 텍스트로 출력 | 변환기가 수식 미지원 | KaTeX/MathJax 지원 도구로 전환 |
| Mermaid 다이어그램 누락 | Mermaid 렌더링 엔진 없음 | Mermaid 지원 변환기 사용 |
| 중첩 목록이 평탄화됨 | 탭과 스페이스 혼용 | 4스페이스 들여쓰기로 통일 |
| 각주가 사라짐 | 변환기가 각주 구문 무시 | GFM 각주 지원 여부 확인 |
| 이모지가 네모로 표시 | 폰트에 이모지 글리프 없음 | 이모지 폰트 매핑 지원 변환기 사용 |
테이블 관련 문제
문제 1: Word 출력에서 테이블 열이 어긋나거나 합쳐지는 경우
증상: 마크다운에서 깔끔하게 작성한 테이블이 Word로 변환되면 엉망이 됩니다 — 열이 합쳐지거나, 내용이 넘치거나, 테이블 구조 자체가 사라집니다.
원인:
가장 흔한 원인은 테이블 구문 오류입니다. 마크다운 테이블은 생각보다 엄격합니다. 파이프 문자 하나만 빠지거나 구분선 행이 어긋나도 전체 테이블이 무너집니다.
자주 발생하는 실수 패턴입니다.
<!-- BROKEN: Missing leading pipe -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2
<!-- BROKEN: Separator row doesn't match column count -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |
해결법:
파이프 구문을 일관되게 사용하고, 열 수를 맞춰야 합니다.
| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| Left | Center | Right |
| Cell 1 | Cell 2 | Cell 3 |
꼭 기억해야 할 규칙은 다음과 같습니다.
- 모든 행의 시작과 끝에 파이프
|를 작성합니다 - 구분선 행의 열 수를 헤더와 동일하게 맞춥니다
- 정렬 콜론을 활용합니다 —
:---왼쪽,:---:가운데,---:오른쪽 - 셀 병합은 사용하지 마세요 — 표준 마크다운은 지원하지 않습니다. 셀 병합이 필요하면 변환 후 Word 문서에서 직접 편집해야 합니다

팁: 변환 전에 테이블을 마크다운 린터나 프리뷰 도구에 붙여넣어 보세요. 대부분의 에디터(VS Code, Typora, Obsidian)는 테이블 구문 오류를 바로 보여줍니다.
문제 2: Word 출력에서 테이블 열 너비가 고르지 않은 경우
증상: 마크다운 에디터에서는 보기 좋던 테이블이 Word로 변환하면 한 열이 페이지 너비의 80%를 차지하고 나머지 열은 찌그러집니다.
원인:
대부분의 마크다운-to-Word 변환기는 셀 내용의 길이를 기준으로 열 너비를 계산합니다. 한 셀에 긴 문장이나 URL이 들어 있고 다른 셀은 짧은 값만 있으면 비율이 크게 치우칩니다. HTML과 달리 마크다운에는 열 너비를 지정하는 문법이 없습니다.
해결법:
- 셀 내용을 간결하게 유지합니다. 긴 설명은 각주나 테이블 아래 별도 단락으로 옮기세요
- 긴 URL은 링크 텍스트로 처리합니다: 셀에 URL을 그대로 붙여넣지 말고
[Link text](url)형식을 사용하세요 - MarkFlow로 변환합니다 — 기본적으로 균형 잡힌 열 너비를 적용해서 대부분의 변환기보다 읽기 좋은 Word 테이블을 생성합니다
정확한 열 너비가 필요하다면 변환 후 Word에서 테이블을 편집하세요: 테이블 선택 → 테이블 속성 → 열 탭 → 원하는 너비 설정.
문제 3: 테이블 셀의 특수 문자가 렌더링을 깨뜨리는 경우
증상: 테이블 셀 안의 파이프 문자 |가 열 구조를 깨뜨리거나, HTML 엔티티가 생 텍스트로 렌더링됩니다.
원인:
파이프 문자 |는 마크다운 테이블의 열 구분자입니다. 셀 내용에 파이프가 그대로 들어가면 파서가 이를 열 경계로 판단합니다.
해결법:
백슬래시로 파이프 문자를 이스케이프합니다.
| Command | Description |
|:--------|:------------|
| `echo "a \| b"` | Pipes output through filter |
| `status: pass\|fail` | Shows pass or fail status |
테이블 셀 안의 기타 특수 문자 처리 방법입니다.
- 파이프 문자에는
\|사용 - 앰퍼샌드가 필요하면
&같은 HTML 엔티티 사용 - 인라인 코드 백틱으로 감싸면 마크다운 해석을 방지할 수 있습니다
코드 블록 관련 문제
문제 4: 변환 후 코드 블록의 구문 강조가 사라지는 경우
증상: 아름답게 하이라이팅되던 Python이나 JavaScript 코드가 Word 문서에서는 색상 없는 단색 텍스트가 됩니다.
원인:
두 가지 흔한 원인이 있습니다.
- 언어 식별자 미지정 — 언어를 지정하지 않고 단순 트리플 백틱만 사용한 경우
- 변환기가 하이라이팅 미지원 — 많은 기본적인 변환기는 Word/PDF 내보내기 시 구문 강조를 제거합니다
차이를 확인해 보겠습니다.
<!-- NO highlighting — missing language tag -->
```
function hello() {
console.log("Hello");
}
```
<!-- WITH highlighting — language specified -->
```javascript
function hello() {
console.log("Hello");
}
```
해결법:
여는 트리플 백틱 바로 뒤에 반드시 언어를 지정하세요. 자주 사용하는 언어 식별자 목록입니다.
| 언어 | 식별자 |
|---|---|
| JavaScript | javascript 또는 js |
| Python | python 또는 py |
| TypeScript | typescript 또는 ts |
| Bash/Shell | bash 또는 shell |
| JSON | json |
| SQL | sql |
| HTML | html |
| CSS | css |
| Go | go |
| Rust | rust |

변환기가 그래도 하이라이팅된 출력을 만들지 못한다면, MarkFlow는 Word와 PDF 내보내기 모두에서 구문 강조를 유지합니다 — 코드가 올바른 색상, 폰트, 들여쓰기로 표시됩니다.
문제 5: 인라인 코드 서식이 사라지는 경우
증상: config.yaml이나 npm install처럼 싱글 백틱으로 감싼 텍스트가 변환된 문서에서는 시각적 구분 없이 일반 텍스트로 표시됩니다.
원인:
일부 변환기는 인라인 코드를 일반 텍스트로 처리하고 별도 스타일을 적용하지 않습니다. 백틱 구문은 인식하지만 출력 포맷에 고정폭 폰트나 배경색이 포함되지 않는 것입니다.
해결법:
- 인라인 코드 스타일링을 존중하는 변환기를 사용하세요. MarkFlow는 Word 출력에서 인라인 코드를 고정폭 폰트와 연한 배경색으로 렌더링해 주변 텍스트와 시각적으로 구분되게 합니다
- 인라인 코드 안에 백틱을 중첩하지 마세요. 코드에 백틱이 포함되어 있으면 이중 백틱을 사용하세요:
`code with `backtick`→``code with `backtick` ``처럼 작성합니다 - 강조 목적으로 인라인 코드를 남용하지 마세요 — 강조에는 볼드나 이탤릭을 사용하세요. 백틱은 실제 코드, 명령어, 파일명, 기술 식별자에만 쓰는 것이 좋습니다
문제 6: 코드 들여쓰기와 공백이 잘못된 경우
증상: Word 출력의 코드 블록에서 들여쓰기가 틀어져 있습니다 — 전부 왼쪽 정렬이 되거나, 탭이 불규칙한 간격으로 변환됩니다.
원인:
마크다운 파서와 Word 렌더링 엔진 간에 탭-스페이스 변환 규칙이 다릅니다. 일부 변환기는 앞쪽 공백을 제거하거나 여러 개의 스페이스를 하나로 합치기도 합니다.
해결법:
- 마크다운 코드 블록 안에서는 탭이 아닌 스페이스를 사용하세요. 대부분의 스타일 가이드는 2스페이스나 4스페이스를 권장합니다. 탭은 변환기마다 일관되지 않게 해석됩니다
- 들여쓰기 방식 코드 블록(4스페이스) 대신 펜스 방식 코드 블록(트리플 백틱)을 사용하세요. 펜스 블록이 더 안정적으로 파싱됩니다:
<!-- PREFERRED: Fenced code block -->
```python
def nested():
if True:
for i in range(10):
print(i)
```
<!-- AVOID: Indented code block (4 spaces) -->
def nested():
if True:
for i in range(10):
print(i)
- 변환 후 즉시 출력을 확인하세요. 공백이 잘못되었다면 마크다운이 아니라 변환기 쪽의 문제입니다. 다른 도구를 시도하거나 버그를 리포트하세요
이미지 관련 문제
문제 7: 변환 후 이미지가 표시되지 않는 경우
증상: 변환된 Word 또는 PDF 문서에 깨진 이미지 아이콘, 빈 공간, 또는 실제 이미지 대신 alt 텍스트가 표시됩니다.
원인:
이것은 우리가 가장 많이 듣는 변환 관련 불만이며, 거의 항상 이미지 경로로 귀결됩니다.
- 변환기가 해석하지 못하는 상대 경로 —
은 에디터에서는 파일 위치를 알기 때문에 작동합니다. 변환기는 모를 수 있습니다 - 인증이 필요한 원격 URL — 비공개 GitHub 리포, Google Drive, Notion에 호스팅된 이미지는 변환 시 다운로드되지 않습니다
- 프로토콜 문제 — 일부 변환기는
file://경로나 로컬 절대 경로를 처리하지 못합니다 - 미지원 파일 형식 — 특정 변환기는 SVG, WebP, TIFF를 제대로 처리하지 못합니다
해결법:
| 상황 | 해결법 |
|---|---|
| 상대 경로 사용 중 | 절대 URL로 변환하거나 base64로 임베드 |
| 비공개 서버의 이미지 | 먼저 이미지를 다운로드하고 로컬 경로 사용 |
| SVG 형식 사용 중 | 문서 변환 전에 PNG 또는 WebP로 변환 |
| 매우 큰 이미지(>10MB) | 변환 전에 리사이즈 또는 압축 |
확실한 방법은 공개적으로 접근 가능한 이미지 URL을 사용하는 것입니다.
<!-- Most reliable: absolute URL -->

<!-- Also reliable: base64 embedding (for small images) -->


MarkFlow 사용 시: .md 파일을 이미지 폴더와 함께 드래그 앤 드롭하면 MarkFlow가 상대 경로를 자동으로 해석합니다. 이미지 URL이 포함된 마크다운을 붙여넣으면 이미지가 Word 출력에 임베드됩니다.
문제 8: Word 출력에서 이미지가 너무 크거나 너무 작은 경우
증상: 마크다운 프리뷰에서는 적절해 보이던 이미지가 변환된 Word 문서에서는 지나치게 작거나 거대해져서 페이지 레이아웃이 깨집니다.
원인:
마크다운에는 이미지 크기 지정을 위한 네이티브 문법이 없습니다.  형식은 width나 height 파라미터를 받지 않습니다. 대부분의 변환기는 원본 픽셀 크기 그대로 이미지를 삽입하므로, Word 페이지 너비와 맞지 않을 수 있습니다.
해결법:
일부 마크다운 변형(flavor)은 HTML로 이미지 크기 지정을 지원합니다.
<!-- Control image size with HTML -->
<img src="./diagram.png" alt="System architecture" width="600" />
다만 모든 마크다운-to-Word 변환기가 HTML 태그를 처리하지는 않습니다. 선택지는 다음과 같습니다.
- 원본 이미지를 약 600~800px 너비로 리사이즈한 후 마크다운에 추가하세요 — 대부분의 Word 페이지 레이아웃에 맞습니다
- 변환기가 인라인 HTML을 지원한다면 width 속성이 있는 HTML img 태그를 사용하세요
- 변환 후 Word에서 리사이즈하세요: 이미지 우클릭 → 크기 및 위치 → 원하는 백분율로 너비 설정
Word 출력 권장 이미지 크기:
- 페이지 전체 너비 이미지: 600~800px 너비
- 인라인 다이어그램: 400~500px 너비
- 아이콘이나 뱃지: 100~200px 너비
문제 9: Base64 임베딩 이미지 변환이 실패하는 경우
증상: 마크다운에 base64 데이터 URI로 임베드한 이미지가 프리뷰에서는 작동하지만, 변환된 문서에서는 깨진 이미지로 표시되거나 완전히 제거됩니다.
원인:
Base64로 인코딩된 이미지는 파일 크기를 크게 늘립니다(바이너리보다 약 33% 큼). 일부 변환기는 인라인 데이터 URI에 크기 제한을 두거나, 아예 data:image/...;base64,... 형식을 파싱하지 않습니다.
해결법:
- Base64 이미지는 작게 유지하세요 — 100KB 이하(원본 바이너리 기준 약 75KB). 아이콘과 작은 로고는 잘 작동하지만, 스크린샷이나 사진은 보통 그렇지 않습니다
- 큰 이미지에는 실제 이미지 파일을 사용하세요. 호스팅하거나
.md파일과 함께 포함시키세요 - 변환기 문서에서 데이터 URI 지원 여부를 확인하세요. MarkFlow는 Word와 PDF 출력 모두에서 base64 임베딩 이미지를 처리하지만, 이미지당 약 2MB의 실용적 크기 한계가 있습니다
LaTeX 수식과 Mermaid 다이어그램 문제
문제 10: LaTeX 수식이 일반 텍스트로 렌더링되는 경우
증상: 제대로 렌더링된 수식 대신, Word 문서에 생 LaTeX 소스가 표시됩니다: $E = mc^2$나 $$\int_{0}^{1} x^2 dx$$가 리터럴 텍스트로 나타납니다.
원인:
LaTeX 수식 지원은 표준 마크다운이나 GFM에 포함되어 있지 않습니다. 특정 렌더링 엔진(KaTeX 또는 MathJax)이 필요한 확장 기능입니다. 적절한 플래그 없는 Pandoc, 확장 없는 VS Code, Dillinger 등 대부분의 기본적인 마크다운 변환기는 LaTeX 구문을 처리하지 못합니다.
해결법:
먼저 구문이 올바른지 확인하세요.
<!-- Inline math: single dollar signs -->
The formula $E = mc^2$ describes mass-energy equivalence.
<!-- Block math: double dollar signs -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
그다음 LaTeX을 지원하는 변환기를 사용하세요.
| 도구 | LaTeX 지원 | 비고 |
|---|---|---|
| MarkFlow | 지원 | KaTeX 렌더링, 인라인/블록 모두 |
| Pandoc | 지원 | --mathjax 또는 LaTeX 엔진 필요 |
| Typora | 지원 | KaTeX/MathJax 내장 |
| VS Code | 부분 지원 | KaTeX CSS 확장 필요 |
| Dillinger | 미지원 | — |

렌더링 실패를 유발하는 흔한 LaTeX 실수:
<!-- WRONG: Space after opening $ -->
$ E = mc^2 $
<!-- CORRECT: No space after opening $ -->
$E = mc^2$
<!-- WRONG: Missing closing delimiter -->
$$\int_{0}^{1} x^2 dx
<!-- CORRECT: Matching delimiters -->
$$\int_{0}^{1} x^2 dx$$
학술 논문과 기술 문서의 경우, MarkFlow는 Word 출력에서 LaTeX을 실제 수식 이미지로 렌더링합니다 — 따라서 수식 편집기를 지원하지 않는 Word 버전에서도 수식이 올바르게 표시됩니다.
문제 11: Mermaid 다이어그램이 출력에 표시되지 않는 경우
증상: 렌더링된 플로차트나 시퀀스 다이어그램 대신, Word/PDF 출력에 생 Mermaid 코드가 일반 코드 블록으로 표시됩니다.
원인:
Mermaid는 JavaScript 기반 렌더링 엔진입니다. 시각적 다이어그램을 생성하려면 브라우저나 Node.js 환경이 필요합니다. 대부분의 마크다운-to-Word 변환기는 마크다운을 순수 텍스트로만 처리하고 JavaScript를 실행하지 않기 때문에, Mermaid 블록을 평범한 코드로 취급합니다.
해결법:
먼저 Mermaid 구문을 확인하세요.
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
```
Mermaid를 Word/PDF로 렌더링하는 도구:
- MarkFlow — Mermaid 다이어그램을 Word 출력에 임베드된 이미지로 렌더링합니다. 플로차트, 시퀀스 다이어그램, 간트 차트 등을 지원합니다
- Typora — 프리뷰에서 Mermaid를 렌더링하고 PDF로 내보냅니다
- Pandoc —
mermaid-filter플러그인 필요(npm install -g mermaid-filter)

Mermaid를 지원하지 않는 변환기의 우회 방법:
- Mermaid Live Editor에서 다이어그램을 렌더링합니다
- PNG 또는 SVG로 내보냅니다
- 마크다운의 Mermaid 코드 블록을 이미지 참조로 교체합니다
- 평소처럼 변환합니다
수동 작업이 한 단계 추가되지만, 어떤 변환기의 출력에서든 다이어그램이 확실하게 표시됩니다.
서식과 구조 관련 문제
문제 12: Word 출력에서 제목 수준이 잘못된 경우
증상: Word의 제목 계층 구조가 마크다운과 일치하지 않습니다. H2 제목이 H1로 나타나거나, 모든 제목이 같은 크기로 렌더링됩니다.
원인:
두 가지 흔한 원인이 있습니다.
- 마크다운에 H1 제목이 여러 개 있습니다. 문서에는 H1(제목)이 하나만 있어야 합니다. 일부 변환기는 여러 개의 H1을 감지하면 제목을 병합하거나 재배치합니다
- 변환기가 마크다운 제목을 Word 스타일에 다르게 매핑합니다. 일부 도구는 수준에 관계없이 첫 번째 제목을 문서 제목으로 처리합니다
해결법:
올바른 제목 계층을 따르세요.
# Document Title (H1 — use exactly once)
## Section Title (H2 — main sections)
### Subsection (H3 — within sections)
#### Detail (H4 — rarely needed)
- 수준을 건너뛰지 마세요 — H2에서 바로 H4로 가지 마세요
- H1은 문서 상단에 한 번만 사용하거나, 변환기가 제목 메타데이터에서 추가하도록 하세요
- Word 출력의 스타일 패널을 확인하세요 — 제목이 "제목 1", "제목 2" 등으로 표시되어야 합니다. "본문"으로 나오면 변환기가 올바르게 매핑하지 못한 것입니다
문제 13: 중첩 목록의 들여쓰기가 사라지는 경우
증상: 세심하게 중첩한 글머리 기호 목록이나 번호 목록이 Word 출력에서 완전히 평탄해집니다 — 모든 항목이 같은 레벨이 됩니다.
원인:
들여쓰기의 불일치가 원인입니다. 마크다운은 중첩 수준을 감지하기 위해 일관된 간격이 필요합니다. 탭과 스페이스를 섞거나, 어디는 2스페이스 어디는 3스페이스를 쓰면 파서가 혼란을 겪습니다.
해결법:
중첩 레벨마다 4스페이스(또는 탭 1개)를 일관되게 사용하세요.
- First level item
- Second level item
- Third level item
- Back to second level
- Back to first level
1. First item
1. Sub-item one
2. Sub-item two
2. Second item
- Mixed bullet under number
흔한 실수:
<!-- BROKEN: Inconsistent indentation (2 spaces then 3) -->
- Item A
- Sub A (2 spaces)
- Sub B (3 spaces — parser gets confused)
<!-- FIXED: Consistent 4-space indentation -->
- Item A
- Sub A
- Sub B
변환기가 그래도 목록을 평탄화한다면 변환기를 바꿔보세요. MarkFlow는 순서 있는/없는 혼합 목록을 포함해 중첩 목록의 들여쓰기를 Word 출력에서 유지합니다.
문제 14: 각주가 사라지거나 깨지는 경우
증상: [^1] 같은 각주 참조가 변환된 문서에 리터럴 텍스트로 표시되고, 마크다운 하단의 각주 내용이 사라지거나 일반 단락으로 렌더링됩니다.
원인:
각주는 GFM 확장 기능이며, 원래 마크다운 사양에는 포함되어 있지 않습니다. 기본 마크다운만 지원하는 변환기는 각주 구문을 처리하지 않습니다.
해결법:
올바른 각주 구문은 다음과 같습니다.
This claim needs a source[^1]. Another point here[^note].
[^1]: Smith, J. (2025). "Research Paper Title." Journal Name.
[^note]: This is a longer footnote with multiple sentences.
Indent continuation lines with 4 spaces.
다음을 확인하세요.
- 참조
[^id]와 정의[^id]:가 같은 식별자를 사용하는지 - 각주 정의가 문서 끝에 배치되어 있는지(최소한 모든 참조보다 뒤에)
- 변환기가 GFM 각주를 지원하는지 — MarkFlow, Pandoc, Typora 모두 올바르게 처리합니다
문제 15: 이모지 문자가 빈 네모로 표시되는 경우
증상: ✅, 🚀, ⚠️ 같은 이모지가 Word 출력에서 빈 사각형이나 물음표로 표시됩니다.
원인:
Word 문서가 이모지 글리프를 포함하지 않는 폰트를 사용합니다. 변환기가 마크다운 텍스트를 Word에 매핑할 때 표준 폰트(Calibri나 Times New Roman 등)를 적용하는데, 이 폰트에는 유니코드 이모지 문자가 없을 수 있습니다.
해결법:
- 변환 후: Word에서 이모지 문자를 선택하고 폰트를 "Segoe UI Emoji"(Windows) 또는 "Apple Color Emoji"(macOS)로 변경하세요
- 변환 전: 이모지 렌더링이 중요하다면 텍스트 대체어나 이미지로 바꾸는 것을 고려하세요
- 이모지 폰트를 처리하는 변환기 사용: MarkFlow는 Word 출력에서 이모지 문자를 적절한 시스템 폰트로 매핑하므로, Windows와 macOS 모두에서 올바르게 렌더링됩니다
| 접근법 | 장점 | 단점 |
|---|---|---|
| 마크다운에 유니코드 이모지 | 간단하고 표준적 | 폰트에 따라 렌더링이 달라짐 |
HTML 이모지(:white_check_mark:) | 호환성이 더 좋음 | 모든 변환기가 숏코드를 파싱하지는 않음 |
| 이미지로 대체 | 확실하게 표시됨 | 추가 작업, 파일 크기 증가 |
예방법: 변환 문제가 발생하기 전에 막는 방법
대부분의 변환 문제는 예방할 수 있습니다. 다음 습관을 마크다운 작성 워크플로에 적용하세요.
변환 전에 검증하기
마크다운 린터로 구문 문제가 변환 문제로 번지기 전에 잡아내세요.
# Install markdownlint CLI
npm install -g markdownlint-cli
# Lint your file
markdownlint document.md
VS Code 사용자: 실시간 검증을 위해 "markdownlint" 확장을 설치하세요.
출력과 일치하는 프리뷰 사용하기
에디터의 프리뷰와 변환기의 출력은 서로 다른 렌더링 엔진을 사용합니다. VS Code에서 괜찮아 보여도 Word에서는 깨질 수 있습니다. 최종 내보내기 전에 항상 테스트 변환을 해보세요.
마크다운 스타일 통일하기
규칙을 정하고 일관되게 지키세요.
- 들여쓰기: 중첩에 4스페이스
- 줄바꿈: 블록 사이에 빈 줄 1개
- 코드 블록: 항상 펜스 방식(들여쓰기 방식 아님), 항상 언어 태그 포함
- 이미지: 일관된 경로 형식(전부 상대 또는 전부 절대)
- 테이블: 모든 행에 앞뒤 파이프
테스트용 문서 유지하기
사용하는 모든 요소(테이블, 코드 블록, 수식, 다이어그램, 중첩 목록, 각주, 이모지)의 예시를 하나씩 담은 마크다운 파일을 유지하세요. 도구를 업데이트할 때마다 이 파일을 변환기에 통과시켜 보세요. 실제 문서에 영향이 가기 전에 회귀를 발견할 수 있습니다.
어떤 변환기를 언제 써야 할까
도구마다 처리하는 문제 유형이 다릅니다.
| 필요한 것 | 최선의 선택 | 이유 |
|---|---|---|
| 설정 없이 모든 게 작동 | MarkFlow | GFM, LaTeX, Mermaid, 이모지, 코드 하이라이팅을 설정 없이 처리 |
| 복잡한 수식이 포함된 학술 논문 | Pandoc + LaTeX 엔진 | 최고 품질의 수식 렌더링 |
| Word 스타일에 대한 최대한의 제어 | Pandoc + 커스텀 reference.docx | 템플릿 기반 접근 |
| 간단한 문서 빠르게 변환 | 아무 브라우저 기반 도구 | 대부분의 변환기가 기본 마크다운은 무난히 처리 |
| CI/CD에서 배치 처리 | Pandoc 또는 markdown-pdf | 스크립트화, 자동화 가능 |
변환 도구에 대한 자세한 비교는 Markdown to PDF 변환기 비교를 참고하세요.
자주 묻는 질문
Q: 마크다운 테이블을 Word로 변환하면 왜 깨지나요? A: 가장 흔한 원인은 파이프 구문의 불일치입니다 — 앞뒤 파이프 누락이나 구분선 행의 열 수 불일치가 대표적입니다. 변환 전에 마크다운 프리뷰에서 테이블 구문을 검증하세요.
Q: Word로 변환할 때 코드 블록의 구문 강조를 어떻게 유지하나요?
A: 여는 트리플 백틱 바로 뒤에 항상 언어를 지정하세요(예: ```python). 그다음 MarkFlow처럼 Word 출력에서 하이라이팅을 유지하는 변환기를 사용하세요.
Q: 마크다운을 Word로 변환한 후 이미지가 누락되는 이유는 무엇인가요?
A: 변환기가 이미지 경로를 해석하지 못합니다. 원격 이미지에는 절대 URL을 사용하거나, .md 파일을 이미지 폴더와 함께 업로드할 때 상대 경로를 처리하는 MarkFlow 같은 도구를 사용하세요.
Q: LaTeX 수식을 서식 손실 없이 Word로 변환할 수 있나요? A: 네, 다만 LaTeX을 지원하는 변환기가 필요합니다. MarkFlow, Pandoc(수식 플래그 사용), Typora 모두 LaTeX을 올바르게 렌더링합니다. 기본 변환기는 생 LaTeX 소스를 일반 텍스트로 출력합니다.
Q: 변환된 문서에서 Mermaid 다이어그램이 코드로 표시되는 이유는 무엇인가요? A: 대부분의 변환기는 Mermaid가 필요로 하는 JavaScript를 실행하지 않기 때문입니다. 자동 Mermaid 렌더링에는 MarkFlow를 사용하거나, Mermaid Live Editor로 다이어그램을 이미지로 미리 렌더링하세요.
Q: Word 출력에서 중첩 목록 들여쓰기를 어떻게 고치나요? A: 마크다운에서 중첩 레벨마다 정확히 4스페이스를 사용하세요. 탭과 스페이스를 섞지 마세요. 문제가 계속되면 다른 변환기를 시도해 보세요 — 일부 변환기는 중첩 목록을 더 잘 처리합니다.
관련 리소스
- Markdown to Word 변환기 — 테이블, 코드, 수식을 포함한 완전한 서식 지원 변환
- Markdown to PDF 변환기 — 마크다운에서 인쇄용 PDF 생성
- Markdown to HTML 변환기 — 깔끔한 시맨틱 HTML 출력
- 마크다운 작성법 — 변환 문제를 피하기 위한 구문 마스터하기
- ChatGPT 마크다운 출력 가이드 — AI 도구에서 잘 구조화된 마크다운 얻기
- 최고의 Markdown to PDF 변환기 — 상세 도구 비교
이 도구가 유용한가요? 널리 공유해주세요.