마크다운 HTML 변환 규칙과 CSS 스타일링 정리


기술 블로그 글이나 문서를 쓸 때 HTML 태그를 직접 치는 대신 가독성이 좋은 마크다운(Markdown) 문법을 쓰는 경우가 많습니다. 문제는 웹 브라우저가 마크다운 문법을 그대로 그려주지 못한다는 점입니다.
화면에 보여주려면 마크다운 텍스트를 HTML 태그로 바꿔주는 변환 과정이 한 번 필요합니다. 이 글에서는 마크다운이 어떤 규칙으로 HTML로 바뀌는지, 변환된 HTML을 어떻게 CSS로 꾸미는지 정리합니다.
마크다운 문법이 HTML 태그로 바뀌는 규칙
마크다운 변환기는 원문에서 마크다운 특유의 기호 패턴을 찾아 대응하는 HTML 태그로 바꿉니다. 자주 쓰는 문법과 실제로 바뀌는 태그는 다음과 같습니다.
| 마크다운 문법 | 변환되는 HTML |
|---|---|
# ~ ###### (제목) | <h1> ~ <h6> |
**굵게** | <strong>굵게</strong> |
*기울임* | <em>기울임</em> |
[텍스트](주소) | <a href="주소">텍스트</a> |
| 백틱으로 감싼 텍스트 | <code>텍스트</code> |
변환기마다 세부 규칙은 조금씩 다릅니다. 예를 들어 굵게 표시(**)로 감싼 구간이 한글 조사 바로 앞에 붙으면, 즉 닫는 기호 뒤에 공백이나 문장부호 없이 글자가 바로 이어지면 일부 변환기는 강조로 인식하지 못하고 별표를 그대로 남깁니다.
강조가 먹지 않을 때는 닫는 ** 뒤에 공백을 하나 넣어보면 대부분 해결됩니다.
변환된 HTML을 CSS로 꾸미는 방법
마크다운을 변환만 하면 HTML 기본 스타일 그대로라 여백이 없고 밋밋하게 보입니다. 가독성을 높이려면 변환 결과를 감싸는 컨테이너에 타이포그래피 CSS를 따로 입혀야 합니다. 자주 쓰는 예시는 다음과 같습니다.
/* 마크다운 렌더링 결과물을 감싸는 최상위 컨테이너 */
.markdown-body {
line-height: 1.6;
color: #24292e;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica;
}
/* 제목 아래 은은한 구분선 추가 */
.markdown-body h2 {
padding-bottom: 0.3em;
border-bottom: 1px solid #eaecef;
}
/* 코드 영역 가독성 보정 */
.markdown-body code {
padding: 0.2em 0.4em;
background-color: rgba(27, 31, 35, 0.05);
border-radius: 3px;
font-family: SFMono-Regular, Consolas, monospace;
}
매번 터미널에서 변환 스크립트를 돌릴 필요 없이 마크다운 HTML 변환기를 쓰면 왼쪽에 입력한 마크다운이 오른쪽에 미리보기 화면과 HTML 코드로 바로 나타납니다. 반대로 HTML 코드를 붙여넣어 마크다운으로 되돌리는 것도 가능합니다.
직접 변환해보고 싶다면. 아래에서 마크다운을 입력하면 HTML 코드와 미리보기를 함께 확인할 수 있습니다.
텍스트나 마크다운 기호를 왼쪽 패널에 자유롭게 작성하여 실시간 HTML 원시 마크업 태그 및 스타일 렌더링 Preview를 직접 확인하고 획득해 보세요.
자주 막히는 지점
| 상황 | 원인 |
|---|---|
굵게 표시(**)가 안 먹힘 | 닫는 기호 바로 뒤에 공백·문장부호 없이 글자가 이어짐 |
| 코드 블록 안 마크다운이 그대로 변환됨 | 코드 펜스(```)가 제대로 안 닫힘 |
| 백틱이 포함된 텍스트가 깨짐 | 백틱 개수가 안 맞아 코드 구간 인식이 어긋남 |
| 이미지가 안 보임 | 에서 주소가 상대경로인데 실제 파일 위치와 다름 |
정리
마크다운은 웹 브라우저가 직접 읽지 못하는 문법이라 HTML로 바꾸는 변환 과정이 항상 한 번 필요합니다. 제목·강조·링크·코드 같은 기본 문법은 변환기마다 규칙이 비슷하지만, 강조 기호가 한글 조사 앞에서 안 먹히는 것처럼 세부 동작이 갈리는 지점도 있습니다. 변환된 HTML은 기본 스타일이 없으므로 타이포그래피 CSS를 따로 입혀야 보기 좋게 나옵니다.
텍스트나 마크다운 기호를 왼쪽 패널에 자유롭게 작성하여 실시간 HTML 원시 마크업 태그 및 스타일 렌더링 Preview를 직접 확인하고 획득해 보세요.
자주 묻는 질문
마크다운과 HTML 중 어느 쪽을 먼저 써야 하나요?
글을 쓰는 단계에서는 마크다운이 편합니다. 태그를 직접 치지 않아도 되고 텍스트 파일 자체로도 읽기 쉽습니다. 웹에 배포할 때만 HTML로 변환하면 됩니다.
변환기마다 결과가 조금씩 다른 이유는 무엇인가요?
마크다운은 CommonMark 같은 표준 규격이 있지만 변환기마다 확장 문법이나 예외 처리 방식이 조금씩 다릅니다. 같은 원문이라도 변환기를 바꾸면 결과 HTML이 미세하게 달라질 수 있습니다.