왜 Markdown을 HTML로 변환하는가
Markdown은 작성자 친화적인 경량 마크업 언어이지만 브라우저는 HTML만 인식합니다. Markdown으로 작성한 콘텐츠를 웹페이지에 표시하려면 HTML로 변환해야 합니다.
흔한 시나리오:
- 블로그 글 발행
- 문서 사이트 렌더링
- README 표시
- 리치 텍스트 편집기가 HTML 출력
Markdown과 HTML 구문 대응
제목
Markdown:
# 1급 제목
## 2급 제목
### 3급 제목
HTML:
<h1>1급 제목</h1>
<h2>2급 제목</h2>
<h3>3급 제목</h3>
단락
Markdown: 빈 행으로 구분된 텍스트 단락.
HTML: <p>단락</p>
강조
Markdown:
**굵게**
*기울임*
~~취소선~~
HTML:
<strong>굵게</strong>
<em>기울임</em>
<del>취소선</del>
링크
Markdown:
[링크 텍스트](https://example.com)
HTML:
<a href="https://example.com">링크 텍스트</a>
이미지
Markdown:
HTML:
<img src="image.png" alt="대체 텍스트">
목록
Markdown 순서 없는 목록:
- 항목1
- 항목2
HTML:
<ul>
<li>항목1</li>
<li>항목2</li>
</ul>
Markdown 순서 있는 목록:
1. 첫 항목
2. 둘째 항목
HTML:
<ol>
<li>첫 항목</li>
<li>둘째 항목</li>
</ol>
코드
Markdown 인라인 코드:
이것은 `code` 인라인 코드입니다
HTML: 이것은 <code>code</code> 인라인 코드입니다
Markdown 코드 블록:
코드 블록
HTML:
<pre><code>코드 블록</code></pre>
언어 하이라이트 포함:
const x = 1;
변환 후 구문 하이라이트 마크업 포함(하이라이트 라이브러리 필요).
인용
Markdown:
> 이것은 인용입니다
HTML:
<blockquote>이것은 인용입니다</blockquote>
구분선
Markdown:
---
HTML:
<hr>
표
Markdown:
| 이름 | 나이 |
| ---- | ---- |
| Tom | 25 |
HTML:
<table>
<thead>
<tr><th>이름</th><th>나이</th></tr>
</thead>
<tbody>
<tr><td>Tom</td><td>25</td></tr>
</tbody>
</table>
확장 구문
표준 Markdown(CommonMark)은 다음 기능을 포함하지 않지만 대부분의 파서가 지원합니다:
작업 목록
- [x] 완료
- [ ] 미완료
HTML:
<ul>
<li><input type="checkbox" checked disabled> 완료</li>
<li><input type="checkbox" disabled> 미완료</li>
</ul>
각주
본문[^1]
[^1]: 각주 내용
취소선
~~삭제~~
자동 링크
정의 목록, 목차, 수식 등
일부 파서가 지원하지만 호환성이 다릅니다.
변환 주의사항
스타일 손실
Markdown to HTML 변환은 태그만 생성하고 스타일은 포함하지 않습니다. 표시 효과는 CSS에 의존합니다:
- 제목 크기, 간격
- 목록 들여쓰기, 기호
- 코드 블록 배경, 글꼴
- 표 테두리
변환 후 CSS를 설정해야 보기 좋습니다.
XSS 보안
Markdown은 HTML 포함을 허용합니다. 사용자가 입력한 Markdown을 HTML로 변환하면 포함된 <script> 등 태그가 보존되어 XSS가 발생할 수 있습니다.
안전한 방법:
- 순수 Markdown 사용(HTML 포함 비활성화)
- HTML 변환 후 sanitize 라이브러리로 위험 태그 필터링
- 신뢰할 수 있는 출처의 Markdown만 허용
이스케이프 문자
Markdown의 특수 문자(, #, _, )는 이스케이프해야 합니다. Markdown에서 \*를 쓰면 별표가 표시되며 HTML 변환 후 `가 됩니다(태그가 아님).
이미지 경로
Markdown의 상대 경로 이미지는 HTML 변환 후에도 경로가 유지됩니다. 디렉터리를 바꿔 표시할 때는 경로를 조정하세요.
앵커 링크
Markdown 제목은 자동으로 앵커(id)를 생성합니다. 파서마다 생성 규칙이 다르므로 앵커 링크 시 주의하세요.
변환 도구
온라인 변환
Markdown을 붙여 넣으면 도구가 HTML을 출력합니다. 일회성 변환에 적합합니다.
- Markdown 내용 붙여 넣기
- 도구가 파싱 변환
- HTML 코드 출력
- 복사하여 사용
브라우저에서 변환되며 콘텐츠는 업로드되지 않습니다.
편집기 통합
VS Code, Typora 등 편집기에 Markdown to HTML 미리보기가 내장되어 있습니다.
프로그램 변환
JavaScript는 marked, markdown-it 라이브러리를 사용합니다. Python은 markdown, mistune 라이브러리를 사용합니다.
변환 팁
Markdown 스타일 통일
Markdown 방언(CommonMark, GFM, MDX)마다 변환 결과가 다를 수 있습니다. 팀에서 한 가지 방언으로 통일하세요.
미리보기 검증
변환 후 브라우저에서 미리보기로 확인:
- 제목 계층이 올바른가
- 목록 중첩이 정상인가
- 코드 블록이 하이라이트되는가
- 표가 정렬되는가
- 이미지가 표시되는가
- 링크가 클릭 가능한가
CSS 세트 준비
Markdown 렌더링 CSS를 준비하고 변환된 HTML에 적용하면 보기 좋게 표시됩니다.
원본 Markdown 보존
HTML은 렌더링 결과이고 Markdown은 원본 파일입니다. Markdown을 보존하면 후속 편집이 편리하며 HTML은 매번 다시 생성합니다.
자주 묻는 질문
변환 후 스타일이 맞지 않음
HTML에 CSS가 없습니다. Markdown 렌더링 스타일시트를 추가하세요.
코드 블록이 하이라이트되지 않음
구문 하이라이트 라이브러리(highlight.js, Prism 등)가 필요합니다. 변환 도구에 하이라이트가 통합되어 있는지 확인하세요.
표 어긋남
Markdown 표 구문이 엄격하지 않습니다(열 수 불일치). 변환 전에 표 형식을 확인하세요.
특수 문자 표시 이상
Markdown의 < > & 등 문자는 HTML에서 특수한 의미를 가집니다. < > &로 이스케이프해야 합니다.
요약
Markdown to HTML의 핵심은 구문 대응 매핑입니다. 스타일 세트, XSS 보안, 특수 문자 이스케이프에 주의하세요. DocsAll Markdown to HTML 도구는 브라우저에서 실행되며 콘텐츠가 외부로 전송되지 않습니다.