마크다운을 HTML로 변환

조각인가 페이지인가, 그리고 무엇이 필요한가

쓸모 있는 출력은 두 가지이며 서로 바꿔 쓸 수 없습니다. 조각은 변환된 마크업(제목, 문단, 목록, 링크)만 담고 문서 틀은 없습니다. 결과를 템플릿이나 CMS 입력란, 다른 페이지 안에 넣을 때 필요한 것이 바로 이것입니다. 완전한 페이지는 doctype, head, 문자 집합 선언, 스타일시트를 더해 단독으로 열리고 제대로 된 모양을 갖춥니다. 완전한 페이지를 CMS에 붙여 넣으면 문서 안에 문서가 들어가고, 조각을 브라우저에서 열면 스타일 없는 텍스트만 보입니다.

변환은 널리 합의된 확장 마크다운 문법을 다룹니다. 제목, 강조, 목록, 링크, 이미지, 인용문, 표, 구문 강조가 되는 코드 블록, 작업 목록, 취소선, 각주까지 지원합니다. 제목에는 텍스트에서 만든 식별자가 붙어 바로 링크할 수 있습니다. 긴 문서를 쓸 만하게 만들어 주는 앵커 링크가 바로 이것입니다.

마크다운 안의 HTML 원문은 그대로 통과되는데, 이는 사양의 일부이며 신중하게 다뤄야 할 부분입니다. 신뢰할 수 없는 곳에서 온 마크다운 파일에 script 태그가 들어 있을 수 있고, 이를 변환하면 그 스크립트를 담은 페이지가 만들어진다는 뜻이기 때문입니다. 모르는 사람이 보낸 마크다운은 변환 후 HTML을 정화하지 않고는 절대 렌더링하지 마세요. 변환은 보안 경계가 아니며, 애초에 그런 용도로 만들어지지도 않았습니다.

두 가지는 일부러 렌더링하지 않고 코드 블록으로 출력합니다. LaTeX 표기의 수식은 조판 라이브러리가, Mermaid 다이어그램은 다이어그램 렌더러가 필요합니다. 둘 다 상당히 무거운 의존성이고, 잘못 렌더링된 수식은 코드로 보이는 수식보다 더 나쁩니다. 완전한 페이지는 글꼴을 따로 불러오지 않고 일반 시스템 글꼴을 사용하므로 오프라인에서도 작동하며, Windows, macOS, Linux에서 조금씩 다르게 보입니다.

다른 작업이 필요할 때

Pandoc은 여기서 빠진 부분은 물론 훨씬 많은 것을 처리합니다. pandoc in.md -o out.html --mathjax --standalone --toc 명령은 수식을 제대로 렌더링하고, 목차를 만들고, 템플릿을 받아 결과물을 내 사이트와 똑같이 맞춰 줍니다. 그 밖에도 40가지 안팎의 형식과 서로 변환할 수 있으니 한 번쯤 설치해 둘 가치가 있습니다.

파일이 아니라 웹사이트가 목적이라면 페이지를 하나씩 변환하지 말고 정적 사이트 생성기를 쓰세요. Hugo, Eleventy, Jekyll, MkDocs는 마크다운 폴더를 탐색, 검색, 일관된 스타일을 갖춘 사이트로 만들고, 원본이 바뀔 때마다 다시 빌드합니다. 문서가 두 개 이상이라면 실제로 필요한 일은 바로 이것입니다.