Markdown이 항상 정답은 아닙니다: AI 결과물은 언제 HTML로 받아야 할까?
Claude·ChatGPT·Codex의 결과를 Markdown과 HTML 중 어떤 형식으로 받아야 하는지, 편집·공유·시각화 목적별로 판단하는 기준입니다.
계속 편집하고 변경 이력을 남길 원본은 Markdown, 사람이 읽고 판단할 최종 검토본은 HTML로 받는 것이 실용적입니다. 둘 중 하나를 영원히 고르는 문제가 아니라, Markdown을 원본으로 유지하고 필요한 순간에 HTML을 생성하는 흐름이 가장 관리하기 쉽습니다.
Markdown과 HTML은 경쟁자가 아니라 다른 층입니다
CommonMark는 문단, 제목, 목록, 인용, 코드처럼 Markdown의 핵심 문법을 명확하게 정의합니다. 일반 텍스트라 가볍고 Git diff가 읽기 쉬우며, 다른 AI에게 다시 입력하기도 편합니다.
HTML은 브라우저가 표현하는 문서 구조입니다. MDN의 HTML 문서에서 설명하는 시맨틱 요소, 표, 이미지, 링크와 스타일을 활용하면 요약 카드, 차트, 목차, 반응형 레이아웃까지 한 파일에 담을 수 있습니다.
Anthropic의 The unreasonable effectiveness of HTML도 Claude Code 팀이 긴 결과물을 더 읽기 쉽고 풍부하게 전달하기 위해 HTML을 사용하는 사례를 보여줍니다. 이것은 Markdown을 버리라는 주장이 아니라, 최종 표현 형식의 선택지를 넓히는 사례로 보는 편이 정확합니다.
6가지 상황으로 고르는 기준
| 상황 | 먼저 고를 형식 | 이유 |
|---|---|---|
| PR 설명, 이슈, 기술 스펙 | Markdown | 도구가 바로 렌더링하고 줄 단위 diff가 남음 |
| 비개발자용 보고서와 대시보드 | HTML | 브라우저 링크로 같은 레이아웃을 전달 |
| 저장소에서 오래 관리할 문서 | Markdown | 변경 이력과 리뷰가 쉬움 |
| 차트·시각 비교·간단한 상호작용 | HTML | CSS, 인라인 SVG, 작은 스크립트 활용 |
| 다른 AI나 스크립트의 중간 입력 | Markdown | 태그가 적고 구조를 다시 쓰기 쉬움 |
| 외부 파트너에게 보내는 검토본 | HTML | 상대의 편집기와 Markdown 뷰어에 덜 의존 |
경계가 애매하면 한 가지만 묻습니다.
이 파일을 다음에 여는 사람은 편집기를 열까, 브라우저를 열까?
편집기에서 계속 고칠 파일은 Markdown, 브라우저에서 읽고 결정할 파일은 HTML 쪽에 가깝습니다.
같은 분석을 Markdown으로 받는 프롬프트
Markdown은 원본과 근거를 관리하는 데 집중합니다.
지난 분기 결제 실패 원인 분석을 Markdown 파일로 작성해줘.
- 파일명: payment-failure-analysis.md
- 첫 부분에 결론과 다음 행동을 각각 3개 이내로 요약.
- H2와 H3로 구조화하고, 표는 GFM 표 문법 사용.
- 수치는 데이터 출처와 기준일을 함께 표시.
- 확인하지 못한 내용은 "미확인", 추정은 "가정"으로 표시.
- 이미지와 장식은 넣지 말고 필요한 차트는
[차트: 무엇을 비교할지] 자리표시자로 남길 것.
- 마지막에 "출처", "가정", "열린 질문" 섹션 추가.
- API 키, 개인정보, 고객 데이터는 포함하지 말 것.
목적: 저장소에 커밋하고 diff로 변경 이력을 관리한다.Markdown 표와 체크박스는 렌더러 확장에 따라 다르게 보일 수 있습니다. 최종 공유 전에 실제로 사용할 뷰어에서 확인합니다.
같은 분석을 HTML로 받는 프롬프트
HTML은 내용을 새로 쓰는 단계가 아니라, 검토 경험을 만드는 단계로 사용합니다.
payment-failure-analysis.md의 내용과 수치를 바꾸지 말고,
공유용 단일 HTML 파일 payment-failure-analysis.html로 변환해줘.
- <!doctype html>부터 </html>까지 완전한 문서 하나.
- CSS는 <style>, 필요한 작은 JavaScript는 <script>에 인라인.
- 외부 CDN, 웹폰트, 상대 경로 이미지, 빌드 도구 금지.
- 문서 위에 핵심 요약, 기준일, "임시 검토용" 표시.
- 목차는 페이지 내부 앵커 링크로 구성.
- 표에는 caption과 th scope를 포함.
- 차트는 외부 라이브러리 없이 접근 가능한 인라인 SVG로 생성.
- 360px 모바일 너비와 인쇄 스타일을 지원.
- 시스템 폰트를 쓰고 전체 파일을 1MB 이하로 유지.
- API 키, 토큰, 개인정보, 고객 데이터와 내부 URL을 넣지 말 것.
목적: 코드를 읽지 않는 이해관계자에게 링크로 검토를 요청한다.“내용과 수치를 바꾸지 말 것”이 중요합니다. 형식 전환 과정에서 모델이 문장을 매끄럽게 고치며 의미나 숫자까지 바꾸지 않도록 경계를 둡니다.
두 형식을 함께 유지하는 가장 단순한 워크플로
- AI에게 먼저 Markdown 원본을 받습니다.
.md를 저장소나 문서 도구에서 검토합니다.- 공유할 때 Markdown을 입력으로 단일 HTML을 생성합니다.
- HTML은 재생성 가능한 산출물로 취급합니다.
- 수정 요청은 Markdown에 반영하고 HTML을 다시 만듭니다.
원칙은 한 문장입니다.
편집은 Markdown에서, 전달은 HTML에서.
HTML을 직접 고치기 시작하면 원본과 검토본의 숫자가 어긋날 수 있습니다. 두 파일을 모두 커밋해야 한다면 생성 과정을 자동화하고, 그렇지 않다면 HTML은 임시 산출물 디렉터리에 둡니다.
두 형식을 모두 링크로 공유하는 방법
완성된 .md나 .html은
HTML2WEB의 HTML-to-URL 도구에 올리거나 본문을
붙여넣을 수 있습니다. 로그인 없는 무료 경로는 1MB까지 지원하고
만료는 30분·1시간·24시간 중에서 고릅니다. 기본은 1시간이고 공유
결과물에는 기본 noindex가 적용됩니다.
개발자는 Markdown 원본 링크, 비개발자는 HTML 검토 링크를 받도록 나눌 수도 있습니다. 다만 둘 모두 임시 공유물이므로 지속적인 문서 운영을 대신하지는 않습니다.
실제로 깨지는 지점
Markdown 표가 기호로 보입니다
표, 체크박스, 각주는 Markdown 구현의 확장 기능일 수 있습니다. 받는 곳이 같은 확장을 지원하는지 확인하거나 HTML 검토본으로 전환합니다.
HTML이 조각만 나옵니다
<section> 하나만 받았다면 완전한 문서가 아닙니다. doctype, html,
head, body까지 포함해 다시 요청합니다.
HTML 외부 자산이 사라집니다
별도 CSS, JavaScript, 로컬 이미지는 단일 파일과 함께 게시되지 않습니다. 첫 검토본은 한 파일 안에서 동작하게 만듭니다.
Base64 이미지로 1MB를 넘습니다
큰 이미지를 본문에 직접 넣는 대신 표, CSS, 인라인 SVG로 바꿉니다. 시각 자료가 핵심이고 용량을 줄일 수 없다면 정식 호스팅이 더 맞습니다.
HTML을 손으로 고쳐 원본과 달라집니다
HTML을 수정하지 말고 Markdown을 고친 뒤 다시 생성합니다. 생성일과 데이터 기준일을 문서 상단에 표시하면 오래된 검토본도 구분하기 쉽습니다.
보안 경계는 형식과 무관합니다
Markdown도 HTML도 내용을 그대로 담습니다. HTML 주석, JavaScript 상수, 접힌 영역에 넣은 값도 페이지 소스에서 볼 수 있습니다.
비밀번호는 보조 경계이며 noindex는 접근 통제가 아닙니다. API 키,
토큰, 개인정보, 고객 데이터는 형식과 관계없이 게시 전에 제거합니다.
자주 묻는 질문
AI에게 항상 Markdown부터 받아야 하나요?
계속 편집하거나 근거를 추적할 작업이라면 유리합니다. 한 번 보고 버릴 시각적 목업이라면 HTML부터 받아도 됩니다.
HTML을 Git에 커밋하면 안 되나요?
금지는 아니지만 생성된 HTML diff는 읽기 어려울 수 있습니다. 원본을 Markdown이나 구조화 데이터로 관리하고 HTML은 자동 생성하는 방식을 먼저 고려하세요.
PDF와 HTML 중에서는 무엇이 낫나요?
인쇄·보존·고정 레이아웃은 PDF, 모바일 브라우저 열람과 상호작용은 HTML이 잘 맞습니다. 장기 보존 문서는 조직의 문서 정책을 따릅니다.
Markdown도 HTML2WEB에서 읽기 좋게 보이나요?
네. Markdown을 안전한 브라우저 문서로 렌더링해 임시 링크로 공유할 수 있습니다. 차트와 복잡한 레이아웃이 필요할 때만 HTML을 선택하세요.