블로그로 돌아가기
Blog Article2026-04-03

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

DA
Daipeng (sosojustdo)
38 min read

마크다운 변환 문제 해결 가이드

마크다운을 깔끔하게 작성했습니다. "변환" 버튼을 눌렀습니다. 그런데 결과물이 기대와 전혀 다릅니다 — 표는 엉망이 되고, 코드 블록은 밋밋한 텍스트이며, 이미지는 사라지고, 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 |

테이블 셀 안의 기타 특수 문자 처리 방법입니다.

  • 파이프 문자에는 \| 사용
  • 앰퍼샌드가 필요하면 &amp; 같은 HTML 엔티티 사용
  • 인라인 코드 백틱으로 감싸면 마크다운 해석을 방지할 수 있습니다

코드 블록 관련 문제

문제 4: 변환 후 코드 블록의 구문 강조가 사라지는 경우

증상: 아름답게 하이라이팅되던 Python이나 JavaScript 코드가 Word 문서에서는 색상 없는 단색 텍스트가 됩니다.

원인:

두 가지 흔한 원인이 있습니다.

  1. 언어 식별자 미지정 — 언어를 지정하지 않고 단순 트리플 백틱만 사용한 경우
  2. 변환기가 하이라이팅 미지원 — 많은 기본적인 변환기는 Word/PDF 내보내기 시 구문 강조를 제거합니다

차이를 확인해 보겠습니다.

<!-- NO highlighting — missing language tag -->
```
function hello() {
  console.log("Hello");
}
```

<!-- WITH highlighting — language specified -->
```javascript
function hello() {
  console.log("Hello");
}
```

해결법:

여는 트리플 백틱 바로 뒤에 반드시 언어를 지정하세요. 자주 사용하는 언어 식별자 목록입니다.

언어식별자
JavaScriptjavascript 또는 js
Pythonpython 또는 py
TypeScripttypescript 또는 ts
Bash/Shellbash 또는 shell
JSONjson
SQLsql
HTMLhtml
CSScss
Gogo
Rustrust

코드 블록 비교: 왼쪽은 언어 태그 없는 단색 코드, 오른쪽은 색상과 적절한 서식이 적용된 구문 강조 JavaScript

변환기가 그래도 하이라이팅된 출력을 만들지 못한다면, MarkFlowWordPDF 내보내기 모두에서 구문 강조를 유지합니다 — 코드가 올바른 색상, 폰트, 들여쓰기로 표시됩니다.


문제 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 텍스트가 표시됩니다.

원인:

이것은 우리가 가장 많이 듣는 변환 관련 불만이며, 거의 항상 이미지 경로로 귀결됩니다.

  1. 변환기가 해석하지 못하는 상대 경로![Alt](./images/photo.png)은 에디터에서는 파일 위치를 알기 때문에 작동합니다. 변환기는 모를 수 있습니다
  2. 인증이 필요한 원격 URL — 비공개 GitHub 리포, Google Drive, Notion에 호스팅된 이미지는 변환 시 다운로드되지 않습니다
  3. 프로토콜 문제 — 일부 변환기는 file:// 경로나 로컬 절대 경로를 처리하지 못합니다
  4. 미지원 파일 형식 — 특정 변환기는 SVG, WebP, TIFF를 제대로 처리하지 못합니다

해결법:

상황해결법
상대 경로 사용 중절대 URL로 변환하거나 base64로 임베드
비공개 서버의 이미지먼저 이미지를 다운로드하고 로컬 경로 사용
SVG 형식 사용 중문서 변환 전에 PNG 또는 WebP로 변환
매우 큰 이미지(>10MB)변환 전에 리사이즈 또는 압축

확실한 방법은 공개적으로 접근 가능한 이미지 URL을 사용하는 것입니다.

<!-- Most reliable: absolute URL -->
![Architecture diagram](https://your-domain.com/images/diagram.png)

<!-- Also reliable: base64 embedding (for small images) -->
![Icon](data:image/png;base64,iVBORw0KGgo...)

흔한 이미지 경로 실패 사례: 상대 경로 못 찾음, 비공개 URL 403 반환, 미지원 SVG 형식, 파일 크기 초과 타임아웃

MarkFlow 사용 시: .md 파일을 이미지 폴더와 함께 드래그 앤 드롭하면 MarkFlow가 상대 경로를 자동으로 해석합니다. 이미지 URL이 포함된 마크다운을 붙여넣으면 이미지가 Word 출력에 임베드됩니다.


문제 8: Word 출력에서 이미지가 너무 크거나 너무 작은 경우

증상: 마크다운 프리뷰에서는 적절해 보이던 이미지가 변환된 Word 문서에서는 지나치게 작거나 거대해져서 페이지 레이아웃이 깨집니다.

원인:

마크다운에는 이미지 크기 지정을 위한 네이티브 문법이 없습니다. ![alt](url) 형식은 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 렌더링 비교: 왼쪽은 Word에서 생 LaTeX 소스가 일반 텍스트로 표시, 오른쪽은 분수와 적분이 올바르게 렌더링된 수식

렌더링 실패를 유발하는 흔한 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로 내보냅니다
  • Pandocmermaid-filter 플러그인 필요(npm install -g mermaid-filter)

Mermaid 다이어그램 비교: 왼쪽은 Word에서 일반 코드 블록으로 표시된 생 Mermaid 코드, 오른쪽은 컬러 노드와 방향 화살표로 렌더링된 플로차트

Mermaid를 지원하지 않는 변환기의 우회 방법:

  1. Mermaid Live Editor에서 다이어그램을 렌더링합니다
  2. PNG 또는 SVG로 내보냅니다
  3. 마크다운의 Mermaid 코드 블록을 이미지 참조로 교체합니다
  4. 평소처럼 변환합니다

수동 작업이 한 단계 추가되지만, 어떤 변환기의 출력에서든 다이어그램이 확실하게 표시됩니다.


서식과 구조 관련 문제

문제 12: Word 출력에서 제목 수준이 잘못된 경우

증상: Word의 제목 계층 구조가 마크다운과 일치하지 않습니다. H2 제목이 H1로 나타나거나, 모든 제목이 같은 크기로 렌더링됩니다.

원인:

두 가지 흔한 원인이 있습니다.

  1. 마크다운에 H1 제목이 여러 개 있습니다. 문서에는 H1(제목)이 하나만 있어야 합니다. 일부 변환기는 여러 개의 H1을 감지하면 제목을 병합하거나 재배치합니다
  2. 변환기가 마크다운 제목을 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개
  • 코드 블록: 항상 펜스 방식(들여쓰기 방식 아님), 항상 언어 태그 포함
  • 이미지: 일관된 경로 형식(전부 상대 또는 전부 절대)
  • 테이블: 모든 행에 앞뒤 파이프

테스트용 문서 유지하기

사용하는 모든 요소(테이블, 코드 블록, 수식, 다이어그램, 중첩 목록, 각주, 이모지)의 예시를 하나씩 담은 마크다운 파일을 유지하세요. 도구를 업데이트할 때마다 이 파일을 변환기에 통과시켜 보세요. 실제 문서에 영향이 가기 전에 회귀를 발견할 수 있습니다.


어떤 변환기를 언제 써야 할까

도구마다 처리하는 문제 유형이 다릅니다.

필요한 것최선의 선택이유
설정 없이 모든 게 작동MarkFlowGFM, 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 Conversion#Troubleshooting#Markdown to Word#Markdown to PDF#Formatting Issues#LaTeX#Mermaid

이 도구가 유용한가요? 널리 공유해주세요.