HTML을 깔끔한 Markdown으로 변환하기

HTML을 Markdown으로 변환하는 방법

1. HTML을 넣습니다. 입력창에 마크업을 붙여넣거나, 로컬 .html 파일을 열거나, 웹페이지의 한 부분을 복사해 붙여넣으세요. 서식 있는 붙여넣기를 켜 두면 변환기가 일반 텍스트 대신 클립보드의 서식 있는 HTML을 가져옵니다.
2. 링크가 상대 경로라면 기준 URL을 설정합니다. 페이지 소스에서 복사한 마크업에는 /docs/setup 같은 링크가 자주 들어 있습니다. 페이지 주소를 입력하면 모든 상대 링크와 이미지가 절대 주소로 바뀝니다.
3. Markdown 스타일을 고릅니다. 기본값(ATX 제목, 대시 글머리 기호, 울타리 코드, 인라인 링크, GFM 켜짐)은 GitHub, GitLab, Obsidian, 대부분의 정적 사이트 생성기와 AI 도구에 맞습니다.
4. 복사하거나 내려받습니다. 결과는 입력하는 대로 갱신됩니다. 클립보드에 복사하거나 첫 번째 제목 이름의 .md 파일로 저장하세요.

요소별로 무엇이 어떻게 변환되나

Markdown은 HTML보다 어휘가 훨씬 적어서, 변환기의 진짜 일은 각 요소를 무엇으로 바꿀지 정하는 것입니다. 이 도구는 다음과 같이 변환합니다.

• 제목 <h1>~<h6>은 #부터 ######이 됩니다. Setext 방식은 문법이 지원하는 H1과 H2에만 밑줄을 긋고, H3 이하는 계속 #을 씁니다.
• 굵게와 기울임(<strong>, <b>, <em>, <i>)은 선택한 구분 기호를 씁니다.
• 링크는 [텍스트](url "제목")이 되며, 참조 링크를 고르면 문서 끝에 모은 번호 참조가 됩니다. 스크립트를 실행하는 링크(javascript:)나 data: 페이로드가 든 링크는 텍스트만 남습니다.
• 이미지는 ![대체 텍스트](src)가 됩니다. 실제 주소를 data-src에 두는 지연 로딩 이미지도 인식합니다. 인라인 data: 이미지는 base64 덩어리가 Markdown 파일을 읽을 수 없게 만들기 때문에 제외됩니다.
• 목록은 여러 단계로 중첩되어 있어도 부모 항목 아래로 들여쓰기됩니다. 번호 목록은 start 번호를 유지하므로 4에서 시작하는 목록은 계속 4에서 시작합니다.
• 인용문은 중첩 인용을 포함해 > 줄이 됩니다.
• 코드: 인라인 <code>는 백틱이 되고, <pre> 블록은 언어가 선언되어 있으면 언어가 붙은 울타리 블록이 됩니다(아래 참고).
• 표는 GFM 파이프 표가 됩니다. 세부 사항과 한계는 다음 절에 있습니다.
• 취소선과 할 일 목록: <del>, <s>, <strike>는 ~~텍스트~~가 되고, 체크박스로 시작하는 목록 항목은 - [ ] 또는 - [x]가 됩니다.
• 완전히 제거되는 것: <script>, <style>, <noscript>, <template>, iframe, embed, SVG, canvas입니다. <div>나 <span> 같은 레이아웃 래퍼는 풀어서 텍스트만 남기며, 바로 이 때문에 Markdown이 원본 HTML보다 작고 읽기 쉬워집니다.

표: Markdown이 담을 수 있는 것과 없는 것

GitHub Flavored Markdown 명세는 표를 머리글 행, 대시로 된 구분 행, 본문 행으로 정의합니다. 명세의 세 가지 규칙이 HTML 표의 변환 방식을 결정합니다.

• 머리글 행이 필수입니다. 스프레드시트나 오래된 CMS 페이지에서 붙여넣은 표처럼 많은 HTML 표에는 <th> 셀이 아예 없습니다. 그대로 두면 파이프 표가 될 수 없으므로 변환기는 기본적으로 첫 행을 머리글로 바꿉니다. 그런 표를 HTML로 두고 싶다면 이 옵션을 해제하세요.
• 셀 안에는 블록 콘텐츠가 들어갈 수 없습니다. 명세는 표에 블록 수준 요소를 넣을 수 없다고 정하므로, 셀 안의 문단과 줄바꿈은 한 줄로 합쳐집니다. 셀 안 목록은 구조를 잃습니다. 표에 풍부한 내용이 들어 있다면 HTML로 두는 것을 고려하세요.
• 세로선 문자는 이스케이프해야 합니다. 셀 안의 |는 새 열을 시작하므로 변환기는 이를 \|로 쓰며, 명세는 코드 스팬 안을 포함해 셀 어디서든 이를 허용합니다.

병합된 셀은 부분적으로 지원합니다. colspan="3"인 셀 뒤에는 열이 어긋나지 않도록 빈 셀 두 개가 붙습니다. 행 병합(rowspan)은 Markdown에 대응이 없어 재현되지 않습니다. <caption>은 표 위의 별도 문단으로 옮겨지고, align 속성의 열 정렬은 구분 행에서 :--, :-:, --:가 됩니다.

코드 블록과 구문 강조

울타리 코드 블록은 ```python처럼 여는 울타리 뒤에 정보 문자열을 둘 수 있고, 렌더러는 이를 코드 색칠에 씁니다. 변환기는 강조 도구가 언어를 두는 곳에서 언어를 찾습니다. language-*와 lang-* 클래스(Prism, highlight.js, 대부분의 Markdown 렌더러), GitHub의 highlight-source-* 래퍼, data-lang 또는 data-language 속성입니다. 안쪽에 <code> 요소가 없는 <pre>도 이스케이프된 본문이 아니라 코드 블록으로 취급합니다.

코드 텍스트는 그대로 가져오므로, 강조 도구의 마크업(색이 입혀진 <span> 요소들)은 코드를 건드리지 않고 사라집니다. 코드 자체에 백틱 세 개가 연속으로 들어 있으면 울타리를 그보다 길게 만듭니다. 명세가 닫는 울타리를 여는 울타리 이상의 길이로 요구하기 때문이며, 덕분에 Markdown에 대한 Markdown 문서도 온전히 유지됩니다.

옵션 설명

ATX 제목과 Setext 제목

ATX 제목(# 제목)은 여섯 단계 모두에 쓸 수 있고 거의 모든 도구가 기대하는 방식입니다. Setext 제목은 글자 밑에 ===나 ---를 긋습니다. 일부 스타일 가이드는 H1과 H2에 이 방식을 선호하지만 H3 이하는 표현할 수 없습니다.

인라인 링크와 참조 링크

인라인 링크는 각 URL을 텍스트 바로 옆에 두므로 짧은 문서와 AI 프롬프트에 알맞습니다. 참조 링크는 URL을 맨 아래 번호 목록으로 옮겨 긴 문단을 일반 텍스트 편집기에서도 읽기 쉽게 하며 문서 저장소에서 흔히 쓰입니다.

Markdown 문자 이스케이프

2024. 좋은 해나 file_name_here 같은 텍스트는 목록이나 기울임으로 잘못 읽힐 수 있어서 변환기가 이런 문자를 역슬래시로 이스케이프합니다. 렌더링될 모든 글에는 이것이 맞습니다. 출력을 AI 모델과의 대화, 검색 색인, 일반 텍스트 메모에 넣을 때는 이스케이프를 해제하면 더 깔끔합니다.

기준 URL

상대 URL은 원래 페이지에서만 의미가 있습니다. 기준 URL을 설정하면 https://example.com/blog/post의 ../images/chart.png가 브라우저와 같은 규칙으로 해석되어 https://example.com/images/chart.png가 됩니다.

웹페이지 전체 변환하기

이 변환기는 URL을 가져오지 않습니다. 브라우저의 페이지는 다른 사이트가 허용하지 않으면 그 사이트의 HTML을 읽을 수 없고, 많은 최신 페이지가 로드 뒤에 자바스크립트로 내용을 조립하기 때문에 서버에서 가져오면 빈 껍데기가 오는 경우가 많습니다. 렌더링된 페이지에서 복사하면 두 문제를 모두 피할 수 있습니다. 글을 선택하고 복사해 여기에 붙여넣으세요. 눈에 보이는 텍스트가 링크와 서식과 함께 들어오고, 선택하지 않은 탐색 메뉴, 쿠키 배너, 광고는 들어오지 않습니다. 페이지의 모든 링크를 뽑으려면 링크 추출기(영문)를 쓰세요.

자주 겪는 문제와 해결법

• 표가 출력에서 HTML로 나타납니다. GFM이 꺼져 있거나, 머리글 승격이 꺼져 있는데 표에 머리글 행이 없는 경우입니다. 해당 옵션을 다시 켜세요.
• 링크가 엉뚱한 곳을 가리킵니다. 상대 경로였기 때문입니다. 페이지 주소를 기준 URL로 입력하세요.
• 줄바꿈이 이상합니다. <br>는 끝 공백 두 칸과 줄바꿈, 즉 CommonMark의 강제 줄바꿈이 됩니다. 일부 편집기는 저장할 때 끝 공백을 지우므로 다시 부드러운 줄바꿈으로 돌아갑니다.
• 텍스트가 빠졌습니다. 자바스크립트 중심 사이트에서 «페이지 소스 보기»로 가져온 HTML이라면 내용이 마크업에 아예 없을 수 있습니다. 렌더링된 페이지에서 복사하세요.
• 전부 한 문단으로 나옵니다. 원본이 문단에 <p> 대신 <div>를 썼기 때문입니다. Markdown은 의미 있는 요소만 알기 때문에 꾸민 div로 만든 페이지는 이어진 텍스트로 변환됩니다.

왜 HTML을 Markdown으로 바꾸나요?

Markdown은 의미를 담은 요소(제목, 강조, 링크, 목록, 표, 인용, 코드)를 남기고 레이아웃 마크업과 인라인 스타일을 버립니다. 그래서 편집하기, 버전 관리에서 검토하기, Obsidian 같은 지식 베이스나 문서 사이트로 옮기기, class 속성에 컨텍스트를 낭비하지 않고 AI 모델에 넘기기가 더 쉽습니다. 개발자는 CMS 콘텐츠를 정적 사이트로 옮기는 데, 작가는 초고를 편집기 사이에서 옮기는 데, 연구자는 자료의 깨끗한 사본을 남기는 데 씁니다. 변환이 아니라 자료를 모으는 중이라면 Marqly가 하나의 검색 가능한 라이브러리에서 리서치 링크를 정리해 주고, 개발자 워크플로 페이지에서는 저장한 문서와 스니펫을 계속 찾을 수 있게 하는 방법을 볼 수 있습니다.

설계부터 비공개

이 변환기는 오픈소스 Turndown 라이브러리와 GitHub 방식 Markdown 플러그인에, 이 페이지 고유의 표·코드·링크 처리를 더해 모두 페이지에 포함한 것입니다. 한 번 불러오면 오프라인에서도 동작하며, 붙여넣은 텍스트, 파일, 설정은 기기를 떠나지 않습니다. 변환 전후에 분량을 빠르게 확인하려면 읽는 시간 계산기도 단어와 글자 수를 로컬에서 셉니다.