핵심 정리

<details>
  <summary>자세히 보기</summary>

  Markdown 문단을 함께 쓸 수 있습니다.
</details>

문장 안에서는 <kbd>Ctrl</kbd> + <kbd>K</kbd>처럼 inline HTML을 쓸 수 있습니다.

렌더링 경계

Markdown은 raw HTML을 그대로 HTML 출력에 넘길 수 있다

CommonMark는 HTML처럼 보이는 태그를 raw HTML로 처리할 수 있습니다. block HTML은 태그가 한 줄 단위로 독립해 있을 때 주로 발생하고, inline HTML은 문장 안에 태그가 섞인 경우에 해당합니다. 이 기능 덕분에 Markdown 문법만으로 부족한 접기 섹션, 키보드 표시, 작은 semantic tag를 보완할 수 있습니다.

<aside>
  이 내용은 보조 설명입니다.
</aside>

문장 안의 <mark>중요 표현</mark>입니다.

다만 raw HTML은 렌더러가 HTML 출력을 허용한다는 전제가 필요합니다. PDF 변환기, 정적 사이트 빌더, 보안 설정이 강한 렌더러에서는 HTML이 제거되거나 escape될 수 있습니다.

block HTML 안의 Markdown 해석은 위치와 빈 줄에 민감하다

HTML tag를 줄 단위로 두면 그 영역이 raw HTML block으로 처리되어 내부 Markdown이 기대와 다르게 해석될 수 있습니다. 어떤 경우에는 HTML block이 빈 줄에서 끝나고 그 다음부터 Markdown이 다시 해석됩니다. 복잡한 구조일수록 렌더러별 차이가 커집니다.

<div>
*강조가 적용되지 않을 수 있습니다.*
</div>

<div>

*빈 줄 뒤라 Markdown으로 해석될 수 있습니다.*

</div>

기술 문서에서는 raw HTML로 레이아웃을 많이 만들기보다, Markdown 본문은 Markdown으로 유지하고 꼭 필요한 작은 HTML만 쓰는 편이 유지보수에 유리합니다.

GitHub는 위험한 raw HTML을 필터링한다

GitHub Flavored Markdown은 raw HTML을 일부 허용하지만, 보안상 위험한 태그는 필터링합니다. 예를 들어 script, iframe, style, title, textarea 같은 태그는 HTML 출력에서 안전하게 처리되지 않습니다. 같은 Markdown이라도 GitHub에서 보이는 결과와 자체 렌더러에서 보이는 결과가 다를 수 있습니다.

<!-- GitHub에서는 필터링될 수 있는 태그 -->
<script>alert('x')</script>
<iframe src="https://example.com"></iframe>

보안이 중요한 문서 시스템에서는 raw HTML 허용 목록을 명확히 두고, 사용자 입력 Markdown은 반드시 sanitization 단계를 거쳐야 합니다.

선택 기준

주의사항