Html To Markdown

인증된 제출자

league/html-to-markdown

제출자 이우진

최신 v5.1.1라이센스 MIT배포 2026년 8월 14일

PHP용 HTML-to-Markdown 변환 헬퍼

GitHub

PHP용 HTML To Markdown

HTML을 Markdown으로 변환해주는 PHP 라이브러리입니다.

요구 사항: PHP 7.2 이상

리드 개발자: @colinodell

최초 제작자: @nickcernis

왜 HTML을 Markdown으로 변환하나요?
설치 및 기본 사용법
변환 옵션
스타일 옵션
줄 바꿈 옵션
자동 링크 옵션
커스텀 Environment 전달
테이블 지원
제한 사항
스타일 참고 사항
의존성
동작 원리
Markdown → HTML 변환이 필요하다면

왜 HTML을 Markdown으로 변환하나요?

일반적으로 다음과 같은 상황에서 HTML을 Markdown으로 변환합니다.

기존 HTML 문서를 사람이 직접 편집해야 할 때
콘텐츠를 HTML로 저장하되 Markdown 형식으로 편집하고 싶을 때
HTML 이메일을 일반 텍스트 이메일로 변환할 때
Markdown을 정말 좋아할 때

설치 및 기본 사용법

Composer로 라이브러리를 설치합니다.

composer require league/html-to-markdown

스크립트 상단에 오토로더를 불러옵니다.

require 'vendor/autoload.php';

그 다음 HtmlConverter 인스턴스를 생성하고 convert() 메서드에 HTML을 전달합니다.

use League\HTMLToMarkdown\HtmlConverter;

$converter = new HtmlConverter();

$html = "<h3>빠르게, Markdown으로!</h3>";
$markdown = $converter->convert($html);

변환 결과는 문자열로 반환됩니다.

echo $markdown; // ==> ### 빠르게, Markdown으로!

라이브러리에 포함된 demo 디렉터리에는 직접 변환을 시험해볼 수 있는 HTML→Markdown 변환 폼이 있습니다.

변환 옵션

CAUTION

기본적으로 이 라이브러리는 <span>, <div>, <iframe>, <script> 등 Markdown에 해당하는 문법이 없는 HTML 태그를 그대로 출력에 보존합니다. 신뢰할 수 없는 사용자 입력을 처리하는 경우, 아래에 설명된 strip_tags 및 remove_nodes 옵션을 반드시 설정하고, HTML Purifier와 같은 별도의 HTML 필터링 라이브러리를 함께 사용하는 것을 강력히 권장합니다.

태그 제거 (`strip_tags`)

Markdown에 해당 문법이 없는 HTML 태그를 제거하되, 태그 안의 내용은 유지하려면 strip_tags를 true로 설정합니다.

$converter = new HtmlConverter(array('strip_tags' => true));

$html = '<span>안녕하세요!</span>';
$markdown = $converter->convert($html); // "안녕하세요!"

옵션을 명시적으로 설정하는 방법도 있습니다.

$converter = new HtmlConverter();
$converter->getConfig()->setOption('strip_tags', true);

$html = '<span>안녕하세요!</span>';
$markdown = $converter->convert($html); // "안녕하세요!"

NOTE

strip_tags는 태그만 제거하고 태그 안의 텍스트 내용은 그대로 유지합니다.

태그와 내용 함께 제거 (`remove_nodes`)

태그와 그 안의 내용을 모두 제거하려면 remove_nodes에 공백으로 구분된 태그 목록을 전달합니다.

$converter = new HtmlConverter(array('remove_nodes' => 'span div'));

$html = '<span>안녕!</span><div>반가워!</div>';
$markdown = $converter->convert($html); // "" (빈 문자열)

주석 보존 (`preserve_comments`)

기본적으로 HTML 주석은 모두 제거됩니다. 주석을 유지하려면 preserve_comments를 true로 설정합니다.

$converter = new HtmlConverter(array('preserve_comments' => true));

$html = '<span>내용</span><!-- 주석 -->';
$markdown = $converter->convert($html); // "내용<!-- 주석 -->"

특정 주석만 선택적으로 보존하려면 문자열 배열을 전달합니다.

$converter = new HtmlConverter(array('preserve_comments' => array('보존할 주석')));

$html = '<span>내용</span><!-- 제거될 주석 --><!-- 보존할 주석 -->';
$markdown = $converter->convert($html); // "내용<!-- 보존할 주석 -->"

플레이스홀더 링크 제거 (`strip_placeholder_links`)

기본적으로 href가 없는 플레이스홀더 링크는 보존됩니다. 이를 제거하려면 strip_placeholder_links를 true로 설정합니다.

$converter = new HtmlConverter(array('strip_placeholder_links' => true));

$html = '<a>GitHub</a>';
$markdown = $converter->convert($html); // "GitHub"

스타일 옵션

기본적으로 굵은 글씨(bold)는 **asterisk** 문법으로, 기울임꼴(italic)은 _underscore_ 문법으로 변환됩니다. bold_style과 italic_style 옵션으로 이를 변경할 수 있습니다.

$converter = new HtmlConverter();
$converter->getConfig()->setOption('italic_style', '*');
$converter->getConfig()->setOption('bold_style', '__');

$html = '<em>기울임</em>과 <strong>굵은 글씨</strong>';
$markdown = $converter->convert($html); // "*기울임*과 __굵은 글씨__"

줄 바꿈 옵션

기본적으로 <br> 태그는 전통적인 Markdown 방식에 따라 공백 두 칸 + 줄 바꿈 문자로 변환됩니다. GitHub Flavored Markdown(GFM)처럼 공백 없이 줄 바꿈만 삽입하려면 hard_break를 true로 설정합니다.

$converter = new HtmlConverter();
$html = '<p>첫 번째 줄<br>두 번째 줄</p>';

$converter->getConfig()->setOption('hard_break', true);
$markdown = $converter->convert($html); // "첫 번째 줄\n두 번째 줄"

$converter->getConfig()->setOption('hard_break', false); // 기본값
$markdown = $converter->convert($html); // "첫 번째 줄  \n두 번째 줄"

자동 링크 옵션

기본적으로 <a> 태그는 가능한 한 간결한 링크 문법으로 변환됩니다. 링크 텍스트와 URL이 동일한 경우 <url> 형식을 사용합니다. 항상 [텍스트](url) 형식을 사용하려면 use_autolinks를 false로 설정합니다.

$converter = new HtmlConverter();
$html = '<p><a href="https://thephpleague.com">https://thephpleague.com</a></p>';

$converter->getConfig()->setOption('use_autolinks', true);
$markdown = $converter->convert($html); // "<https://thephpleague.com>"

$converter->getConfig()->setOption('use_autolinks', false); // 기본값
$markdown = $converter->convert($html); // "[https://thephpleague.com](https://thephpleague.com)"

커스텀 Environment 전달

Environment 객체를 직접 생성하여 HtmlConverter에 전달하면 사용할 컨버터를 세밀하게 제어할 수 있습니다.

$environment = new Environment(array(
    // 여기에 설정 옵션을 추가합니다
));
$environment->addConverter(new HeaderConverter()); // 컨버터를 직접 추가

$converter = new HtmlConverter($environment);

$html = '<h3>제목</h3>
<img src="" />
';
$markdown = $converter->convert($html); // "### 제목"과 '<img src="" />'가 포함됩니다

테이블 지원

Markdown 테이블은 표준 Markdown 문법에 포함되지 않으므로 기본적으로 비활성화되어 있습니다. 테이블 변환이 필요하다면 TableConverter를 명시적으로 추가하세요.

use League\HTMLToMarkdown\HtmlConverter;
use League\HTMLToMarkdown\Converter\TableConverter;

$converter = new HtmlConverter();
$converter->getEnvironment()->addConverter(new TableConverter());

$html = "<table><tr><th>항목</th></tr><tr><td>값</td></tr></table>";
$markdown = $converter->convert($html);

제한 사항

Markdown Extra, MultiMarkdown 등의 확장 문법은 지원하지 않으며, 기본 Markdown만 지원합니다.

스타일 참고 사항

H1과 H2 제목은 기본적으로 Setext 방식(밑줄 스타일)으로 변환됩니다. ATX 방식(# 제목 1, ## 제목 2)을 선호한다면 인스턴스 생성 시 header_style 옵션을 'atx'로 설정하세요.

$converter = new HtmlConverter(array('header_style' => 'atx'));

H3 이하의 제목은 항상 ATX 방식으로 변환됩니다.
링크와 이미지는 인라인 방식으로 참조됩니다. 각주(footnote) 방식의 참조는 지원하지 않습니다.
블록 인용문(blockquote)은 줄 바꿈 없이 변환됩니다. 이렇게 하면 변환된 Markdown을 편집하기가 더 쉽습니다.

의존성

HTML To Markdown는 PHP의 xml, lib-xml, dom 확장 모듈을 필요로 합니다. 대부분의 PHP 배포판에서는 이 확장 모듈들이 기본으로 활성화되어 있습니다.

CentOS 등 일부 배포판에서 PHP의 xml 확장이 비활성화된 경우 "Fatal error: Class 'DOMDocument' not found" 오류가 발생할 수 있습니다. 이때는 php-xml 패키지를 설치하면 해결됩니다.

# CentOS / RHEL 계열sudo yum install php-xml# Ubuntu / Debian 계열sudo apt-get install php-xml

동작 원리

HTML To Markdown는 입력받은 HTML로부터 DOMDocument를 생성한 뒤 DOM 트리를 순회하면서, 가장 깊이 중첩된 노드부터 루트 노드 방향으로 거슬러 올라가며 각 노드를 동등한 Markdown 텍스트 노드로 변환합니다.

기여자

지금까지 기여해주신 모든 기여자분들께 감사드립니다. 추가적인 개선 사항이나 기능 제안은 언제든 환영합니다.

개선 예정 사항 (To-do)

중첩 목록 및 블록 인용문 안의 목록 지원
style 속성처럼 Markdown으로 표현할 수 없는 속성이 있는 태그를 HTML로 보존하는 옵션 제공

Markdown → HTML 변환이 필요하다면?

반대로 Markdown을 HTML로 변환해야 한다면 아래 라이브러리를 활용하세요.