마크다운 팁: 없는 기능을 구현하는 우회 방법 모음
마크다운 팁이란 밑줄 텍스트부터 클릭 가능한 동영상 썸네일까지, Markdown 기본 사양에 없는 기능을 HTML 스니펫과 창의적인 문법 트릭으로 구현하는 우회 방법입니다. 거의 모든 팁은 렌더러가 인라인 HTML을 허용해야 한다는 한 가지 조건에 달려 있습니다. CommonMark는 기본적으로 원시 HTML을 그대로 통과시키므로 VS Code, Obsidian, Typora, 그리고 이 사이트의 에디터에서는 이 우회 방법들이 정상적으로 표시됩니다. 새니타이징을 거치는 플랫폼은 다르게 동작합니다. GitHub는 고정된 태그 허용 목록으로 출력을 필터링하고 모든 style 속성을 삭제하며, Reddit과 Discord는 HTML을 완전히 무시합니다. 아래 각 섹션에서 문법과 함께 해당 문법을 유지하거나 제거하는 렌더러를 정리했습니다.
마크다운 밑줄 긋기
Markdown에는 밑줄 문법이 없으므로 텍스트를 HTML <ins> 태그나 <u> 태그로 감쌉니다. <ins> 태그는 삽입된 텍스트를 나타내며 모든 주요 브라우저에서 밑줄로 렌더링됩니다. GitHub의 새니타이저는 <ins>는 유지하고 <u>는 제거하므로, README에서는 <ins>가 호환성 높은 선택입니다.
Submit the form <ins>before 30 June</ins> to qualify.
Obsidian과 Typora는 두 태그를 모두 렌더링합니다. Bear와 Simplenote는 HTML 대신 자체 밑줄 단축키를 제공합니다. Reddit에서는 파서가 HTML을 버리기 때문에 태그가 일반 텍스트로 그대로 표시됩니다.
문단 들여쓰기
Markdown은 행 앞의 공백을 무시하고 4칸 들여쓰기는 코드 블록으로 변환하므로, 문단 들여쓰기에는 줄바꿈 없는 공백 엔티티를 사용합니다. 각 엔티티는 출력에서 눈에 보이는 공백 하나로 남습니다. 네 개를 이어 쓰면 전통적인 탭 간격을 흉내 낼 수 있습니다.
The opening line of this paragraph sits four spaces in.
엔티티는 태그가 아니라 문자 참조이기 때문에 GitHub를 포함한 거의 모든 렌더러를 통과합니다. 한계는 규모가 커질 때 드러납니다. 들여쓴 문단이 수십 개인 문서는 소스 상태에서 읽기 어려워지므로, iA Writer처럼 템플릿을 제어할 수 있는 에디터가 들여쓰기를 더 깔끔하게 처리합니다.
마크다운 가운데 정렬
한 줄을 가운데 정렬하려면 <center> 태그를 쓰거나, 인라인 CSS가 살아남는 환경에서는 <p style="text-align:center">를 사용합니다. <center> 태그는 1999년 HTML 4.01에서 사용 중단되었지만, 브라우저는 여전히 이를 해석하고 대부분의 Markdown 렌더러도 그대로 통과시킵니다.
<center>Chapter 7</center>
<p style="text-align:center">Chapter 7</p>
GitHub는 style 속성을 삭제하므로 두 번째 형식은 GitHub에서 동작하지 않습니다. README 작성자들이 로고와 배지를 가운데 정렬할 때 <div align="center">를 쓰는 이유는 align 속성이 GitHub의 새니타이저를 통과하기 때문입니다. Typora와 VS Code 미리보기는 CSS 버전을 작성한 그대로 렌더링합니다.
마크다운 글자 색 바꾸기
Markdown에는 글자 색을 지정하는 기능이 없습니다. CSS가 허용되는 곳에서는 <span style="color:#0969da">를, 옛 태그를 아직 받아들이는 렌더러에서는 <font color="red"> 태그를 사용합니다.
<span style="color:#0969da">This sentence renders in blue.</span>
<font color="red">This sentence renders in red.</font>
<font> 태그는 1999년에 사용 중단되었고 최신 새니타이저는 이를 가차 없이 제거합니다. GitHub는 style 속성과 color 속성을 모두 제거하므로 README에서는 어느 형식으로도 글자 색이 적용되지 않습니다. GitHub에서 흔히 쓰는 대안은 언어를 diff로 지정한 코드 블록입니다. +로 시작하는 줄은 초록색, -로 시작하는 줄은 빨간색으로 표시됩니다. Obsidian과 Typora는 <span> 버전을 해석하며, 원시 HTML을 통과시키는 Hugo와 Jekyll 사이트에서도 동작합니다.
마크다운 주석 숨기기
독자에게 보이지 않아야 할 메모는 링크 참조 트릭인 [comment]: # 또는 표준 HTML 주석으로 숨깁니다. 두 방법 모두 텍스트를 소스 파일에는 남기고 렌더링된 페이지에서는 제거합니다.
[everything in this line disappears from the output]: #
<!-- This note also stays hidden. -->
대괄호 트릭은 Markdown의 핵심 기능인 링크 참조 정의를 응용한 것이어서 HTML이 차단된 곳에서도 동작합니다. 위아래에 빈 줄을 넣지 않으면 인접한 문단이 정의에 합쳐질 수 있습니다. HTML 주석은 읽기 쉽지만 생성된 페이지 소스에 남아 누구나 볼 수 있습니다. GitHub는 두 방법을 모두 지원합니다.
경고문과 콜아웃 박스
콜아웃 박스는 인용구 안에 이모지와 굵은 라벨을 넣어 만들거나, 2023년에 도입된 GitHub의 알림(alert) 문법을 사용합니다.
> [!WARNING]
> This command overwrites all 14 archived backups.
> 💡 **Tip:** Blockquote callouts work in any renderer.
GitHub는 NOTE, TIP, IMPORTANT, WARNING, CAUTION의 5가지 알림 유형을 지원합니다. github.com에서는 각 유형이 고유한 아이콘과 강조 색상으로 렌더링되지만, 다른 곳에서는 이 문법이 일반 인용구로 표시됩니다. Obsidian에는 2022년 버전 0.14에서 추가된 > [!note]라는 별도의 콜아웃 형식이 있고, Material 테마를 쓰는 MkDocs는 !!! note 줄을 사용합니다. 어디서나 무난하게 보이는 방식은 이모지 인용구뿐입니다.
이미지 크기 조절
Markdown 이미지 문법 대신 <img> 태그를 쓰고 width와 height 속성을 픽셀 단위로 지정합니다.
<img src="diagram.png" alt="Deployment diagram" width="480" height="270">
GitHub는 style="width:50%"는 제거하지만 width와 height 속성은 유지하므로, README에서는 픽셀 값이 확실한 방법입니다. 크기를 고정해 두면 페이지 로딩 중 레이아웃 이동도 방지됩니다. HTML을 지원하지 않는 렌더러에서는 태그가 텍스트로 그대로 표시되므로, Reddit 같은 플랫폼에서는 기본  형식을 유지해야 합니다.
이미지 캡션 달기
캡션은 <figure>와 <figcaption> 태그로 달거나, 이미지 바로 아래에 기울임꼴 한 줄을 배치합니다.
<figure>
<img src="harbor.jpg" alt="Fishing boats at dawn">
<figcaption>Hobart's harbor, photographed in March 2025.</figcaption>
</figure>
*Hobart's harbor, photographed in March 2025.*
<figure>와 <figcaption>은 모두 GitHub 허용 목록에 있으므로 시맨틱 버전은 README에서 동작합니다. 기울임꼴 줄은 HTML을 지원하지 않는 렌더러를 위한 대체 방법입니다. 스크린 리더는 이를 캡션이 아닌 본문으로 읽어 주는데, 이것이 호환성과 맞바꾸는 대가입니다.
새 탭에서 열리는 링크
Markdown 링크는 새 탭에서 열 수 없으므로, target="_blank"를 넣은 원시 HTML 앵커로 작성합니다.
<a href="https://example.com/report" target="_blank" rel="noopener">2026 annual report</a>
rel="noopener"를 추가하면 새로 열린 페이지가 원래 창을 스크립트로 조작할 수 없게 됩니다. 이 팁이 통하는 범위는 좁습니다. GitHub는 새니타이징 과정에서 target 속성을 제거하므로 README의 모든 링크는 같은 탭에서 열립니다. 이 트릭은 HTML을 그대로 통과시키는 Hugo, Jekyll 같은 정적 사이트 생성기에서 동작하며, 새 탭 동작이 정말 중요한 곳도 바로 그런 환경입니다.
기호와 특수 문자
Markdown 파일은 일반 Unicode 텍스트이므로 기호를 직접 입력하면 됩니다. 키보드로 입력하기 어려운 기호에는 HTML 엔티티를 사용합니다. 문자 참조 페이지에서 © 또는 →를 복사해 파일에 붙여 넣으면 그대로 렌더링됩니다.
| 기호 | HTML 엔티티 |
|---|---|
| © 저작권 | © |
| ® 등록 상표 | ® |
| ™ 상표 | ™ |
| → 오른쪽 화살표 | → |
| ° 도 | ° |
| € 유로 | € |
엔티티는 GitHub를 포함한 거의 모든 렌더러에서 변환됩니다. 유일한 함정은 코드 블록입니다. 펜스 코드 안에서는 엔티티 디코딩이 비활성화되어 ©가 그대로 출력됩니다.
목차 만들기
목차는 제목 앵커 ID를 가리키는 링크를 글머리 기호 목록으로 만들어 구성합니다. GitHub, GitLab을 비롯한 대부분의 렌더러는 모든 제목에 ID를 생성합니다. 텍스트는 소문자로 바뀌고 공백은 하이픈이 되며 대부분의 문장 부호는 제거됩니다.
- [Underline Text](#underline-text)
- [Resize Images](#resize-images)
- [Embed Videos](#embed-videos)
"Resize Images"라는 제목에는 #resize-images 앵커가 붙습니다. GitHub는 2021년부터 README 헤더에 자동 목차 버튼을 표시해 왔으므로, 수동 목록이 제 몫을 하는 곳은 다른 플랫폼의 긴 문서입니다. 제목 이름을 바꾸면 링크가 조용히 깨지므로, 제목을 수정할 때마다 앵커를 다시 확인해야 합니다.
동영상 삽입하기
Markdown으로는 동영상 플레이어를 삽입할 수 없으므로, 클릭 가능한 썸네일 이미지를 동영상에 연결합니다. YouTube는 모든 동영상의 썸네일을 예측 가능한 URL로 제공하므로 이 패턴은 간단합니다.
[](https://www.youtube.com/watch?v=VIDEO-ID)
VIDEO-ID를 동영상 URL의 11자 코드로 바꿉니다. 썸네일은 표준 Markdown이 동작하는 곳이라면 어디서든 렌더링되고, 클릭하면 YouTube에서 동영상이 열립니다. 플랫폼이 허용한다면 두 가지 상위 방법이 있습니다. GitHub는 2021년 5월부터 이슈, 풀 리퀘스트, 디스커션, Markdown 파일에서 .mp4와 .mov 직접 업로드를 지원해 왔고, HTML을 완전히 지원하는 렌더러는 붙여 넣은 YouTube <iframe> 임베드도 허용합니다.
자주 묻는 질문
마크다운 팁이 GitHub에서도 동작합니까?
일부는 동작합니다. GitHub는 <ins>, <img>의 width 속성, <figure>, HTML 주석, 엔티티, 그리고 자체 알림 문법은 유지하지만, 모든 style 속성과 target 속성은 제거합니다. 새니타이저 허용 목록은 예고 없이 바뀔 수 있으므로, 어떤 팁이든 의존하기 전에 초안 Gist에서 테스트해야 합니다.
렌더링된 페이지에서 HTML이 사라진 이유는 무엇입니까?
Reddit과 Discord처럼 렌더러가 인라인 HTML을 완전히 차단했거나, 새니타이징 과정에서 사용한 특정 태그나 속성이 제거된 경우입니다. 플랫폼 문서에서 허용 목록을 확인한 뒤, 제거된 요소를 허용되는 요소로 바꾸면 됩니다. 예를 들어 style 속성 대신 <div align="center">를 사용합니다.
[comment]: #와 <!-- --> 중 어느 주석이 더 좋습니까?
메모가 완전히 사라져야 할 때는 [comment]: #를, 소스 가독성이 더 중요할 때는 <!-- -->를 사용합니다. 대괄호 형식은 Markdown 파서가 소비해 출력에 전혀 남지 않지만, 표준 HTML 주석은 페이지 소스를 보는 누구에게나 그대로 노출됩니다.