마크다운 미리보기

어떤 마크다운인지, 그리고 HTML을 정화하는 이유

마크다운은 하나의 사양이 아니라 여러 방언의 집합이며, 여기서 쓰는 것은 널리 합의된 GitHub 방식(GFM)입니다. 제목, 강조, 목록, 링크, 이미지, 인용문, 표, 구문 강조가 적용된 펜스 코드 블록, 작업 목록, 취소선, 각주, 자동 링크를 지원합니다. 거의 모든 사람이 쓰는 것이고 README에 들어가는 것도 이것입니다. 더 특이한 방언이나 특정 사이트가 추가한 사용자 정의 플러그인(알림 블록, 쇼트코드, 템플릿 문법)은 지원하지 않으므로, 특정 생성기용으로 쓴 문서는 일부 문법이 글자 그대로 보일 수 있습니다.

HTML은 렌더링하되 먼저 정화하며, 이 부분이 알아 둘 가치가 있습니다. 마크다운은 일부러 HTML을 허용하므로, 어디서 온 마크다운 파일이든 script 태그, 인라인 이벤트 핸들러, iframe, javascript: 링크를 담고 있을 수 있습니다. 이를 그대로 렌더링하면, 단지 남의 README를 보려고 붙여 넣었다는 이유만으로 모르는 사람의 코드가 여러분의 세션에서 실행됩니다. 무엇이든 표시하기 전에 실행 가능한 것은 모두 제거하므로, 서식은 살아남고 코드는 남지 않습니다.

이는 이 페이지만의 세부 사항이 아니라 일반적인 교훈입니다. 사용자가 입력한 마크다운을 렌더링하는 시스템(댓글 입력란, 위키, 지원 티켓)은 정화하지 않는 한 사용자가 입력한 HTML을 렌더링하는 것이며, “그냥 마크다운일 뿐”이라는 생각 때문에 이 점을 놓치게 됩니다. 마크다운 변환은 보안 경계가 아닙니다. 보안 경계는 정화 단계입니다.

여기서 보는 것은 특정 사이트가 아니라 내용의 미리보기입니다. GitHub, GitLab, 문서 생성기는 저마다 스타일시트, 제목 앵커, 확장 기능을 적용하므로 같은 파일도 서로 다르게 보입니다. 여기 보이는 구조는 그 모두가 공통으로 따르는 부분입니다. 아무것도 가져오지 않으므로, 웹 주소로 참조한 이미지는 그 서버가 허용할 때만 불러오고, 저장소 안의 파일을 가리키는 상대 경로는 전혀 해석할 수 없습니다.

다른 작업이 필요할 때

실제로 작성 중인 README라면 그것이 게시될 곳에서 미리 보세요. GitHub 자체 편집기는 정확히 같은 렌더링, 확장 기능, 앵커로 미리 보여 주고, GitHub CLI의 gh markdown-preview는 같은 렌더러로 로컬에서 미리 보여 줍니다. 문서라면 생성기 자체(MkDocs, Docusaurus, Hugo)에 실제 스타일과 내비게이션을 보여 주는 실시간 새로고침 미리보기가 있으며, 독자가 보게 될 것도 바로 그것입니다.

확인이 아니라 편집이 목적이라면, Obsidian, Typora, 기본 미리보기가 내장된 VS Code처럼 실시간 미리보기 창이 있는 마크다운 편집기가 매번 페이지에 붙여 넣는 것보다 낫습니다. 입력하는 대로 미리보기가 바뀌고 파일도 제자리에 있기 때문입니다. 이 페이지는 남의 마크다운을 읽거나, 받은 파일을 빠르게 훑어볼 때를 위한 것입니다.