Html To Markdown

인증된 제출자

league/html-to-markdown

제출자 이우진

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

PHP용 HTML→Markdown 변환 도우미입니다.

GitHub

PHP용 HTML To Markdown

HTML을 Markdown으로 변환해 작업을 더 편하게 해주는 라이브러리입니다.

요구사항: PHP 7.2+

리드 개발자: @colinodell

최초 작성자: @nickcernis

HTML을 Markdown으로 변환하는 이유

*"무슨 마법 같은 일인가요?"*라는 생각이 들 수 있습니다. "Markdown을 HTML로 변환하는 이유는 알겠는데, 반대 방향으로 변환할 이유가 있을까요?"

보통 다음과 같은 경우에 HTML을 Markdown으로 변환합니다:

기존 HTML 문서를 읽기 좋은 형식으로 편집하고 싶을 때.
새 콘텐츠를 HTML로 저장하되 Markdown으로 편집하고 싶을 때.
HTML 이메일을 일반 텍스트 이메일로 바꾸고 싶을 때.
HTML을 Markdown으로 수년간 변환한 사람이 이제 엘프어를 구사한다는 이야기를 듣고, 나도 엘프어를 배우고 싶을 때.
그저 Markdown이 정말 마음에 들 때.

사용 방법

다음 명령으로 라이브러리를 설치하세요:

composer require league/html-to-markdown

스크립트 맨 위에 require 'vendor/autoload.php';를 추가하세요.

그다음 HtmlConverter 인스턴스를 만들고 유효한 HTML 코드를 convert() 함수에 전달합니다:

use League\HTMLToMarkdown\HtmlConverter;

$converter = new HtmlConverter();

$html = "<h3>Quick, to the Batpoles!</h3>";
$markdown = $converter->convert($html);

이제 $markdown 변수에 HTML을 Markdown으로 변환한 문자열이 담깁니다:

echo $markdown; // ==> ### Quick, to the Batpoles!

함께 제공되는 demo 디렉터리에는 HTML→Markdown 변환을 직접 확인할 수 있는 폼이 있습니다.

변환 옵션

CAUTION

기본적으로 이 라이브러리는 <span>, <div>, <iframe>, <script>처럼 Markdown에 대응하는 표현이 없는 HTML 태그를 보존합니다. 신뢰할 수 없는 사용자 입력을 파싱한다면 아래의 strip_tags 및/또는 remove_nodes 옵션 설정을 고려하세요. 추가 HTML 필터링을 위해 HTML Purifier 같은 라이브러리 사용도 함께 고려해야 합니다.

Markdown에 대응하는 표현이 없는 HTML 태그를 제거하되 내부 내용은 남기려면 strip_tags를 true로 설정합니다:

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

$html = '<span>Turnips!</span>';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!"

다음처럼 명시적으로 설정할 수도 있습니다:

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

$html = '<span>Turnips!</span>';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!"

태그 자체만 제거되며 태그 안의 내용은 남는다는 점에 유의하세요.

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

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

$html = '<span>Turnips!</span><div>Monkeys!</div>';
$markdown = $converter->convert($html); // $markdown now contains ""

기본적으로 모든 HTML 주석은 제거됩니다. 주석을 보존하려면 preserve_comments 옵션을 사용합니다:

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

$html = '<span>Turnips!</span><!-- Monkeys! -->';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!<!-- Monkeys! -->"

특정 주석만 보존하려면 preserve_comments에 문자열 배열을 지정합니다:

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

$html = '<span>Turnips!</span><!-- Monkeys! --><!-- Eggs! -->';
$markdown = $converter->convert($html); // $markdown now contains "Turnips!<!-- Eggs! -->"

기본적으로 대상 주소가 없는 링크도 보존됩니다. 이런 링크를 제거하려면 strip_placeholder_links 옵션을 사용합니다:

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

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

스타일 옵션

기본적으로 굵은 글씨 태그는 별표 문법으로, 기울임꼴 태그는 밑줄 문법으로 변환됩니다. bold_style과 italic_style 옵션으로 변경할 수 있습니다.

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

$html = '<em>Italic</em> and a <strong>bold</strong>';
$markdown = $converter->convert($html); // $markdown now contains "*Italic* and a __bold__"

줄바꿈 옵션

기본적으로 br 태그는 전통적인 Markdown 문법에 따라 공백 두 개와 줄바꿈 문자로 변환됩니다. GitHub Flavored Markdown(GFM) 방식으로 공백 두 개를 생략하려면 hard_break를 true로 설정하세요.

$converter = new HtmlConverter();
$html = '<p>test<br>line break</p>';

$converter->getConfig()->setOption('hard_break', true);
$markdown = $converter->convert($html); // $markdown now contains "test\nline break"

$converter->getConfig()->setOption('hard_break', false); // default
$markdown = $converter->convert($html); // $markdown now contains "test  \nline break"

자동 링크 옵션

기본적으로 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); // $markdown now contains "<https://thephpleague.com>"

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

사용자 정의 Environment 객체 전달

현재 Environment 객체를 전달해 사용할 변환기 등을 조정할 수 있습니다.

$environment = new Environment(array(
    // your configuration here
));
$environment->addConverter(new HeaderConverter()); // optionally - add converter manually

$converter = new HtmlConverter($environment);

$html = '<h3>Header</h3>
<img src="" />
';
$markdown = $converter->convert($html); // $markdown now contains "### Header" and "<img src="" />"

표 지원

표는 원래 Markdown 문법에 포함되지 않으므로 기본적으로 변환 지원이 활성화되어 있지 않습니다. 표를 사용하려면 변환기를 명시적으로 추가하세요:

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

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

$html = "<table><tr><th>A</th></tr><tr><td>a</td></tr></table>";
$markdown = $converter->convert($html);

제한 사항

Markdown Extra, MultiMarkdown 등 변형 문법은 지원하지 않으며 Markdown만 지원합니다.

스타일 참고 사항

H1과 H2 제목은 기본적으로 Setext(밑줄) 스타일을 사용합니다. H1과 H2에 ATX 스타일(# Header 1, ## Header 2)을 사용하려면 객체 생성 시 옵션 배열에서 header_style을 'atx'로 설정하세요:

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

H3 이하 제목은 항상 atx 스타일을 사용합니다.
링크와 이미지는 인라인으로 참조합니다. 이미지 src와 앵커 href 속성을 각주에 나열하는 각주 참조 방식은 사용하지 않습니다.
인용문에는 자동 줄바꿈을 적용하지 않아 변환된 Markdown을 더 쉽게 편집할 수 있습니다.

의존성

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

CentOS처럼 PHP의 xml 확장을 비활성화하는 배포판에서 "Fatal error: Class 'DOMDocument' not found" 같은 오류가 발생하면 php-xml을 설치해 해결할 수 있습니다.

기여자

지금까지 참여한 모든 기여자에게 감사드립니다. 추가 개선과 기능 제안도 환영합니다.

동작 방식

HTML To Markdown은 전달된 HTML로 DOMDocument를 만들고 트리를 순회합니다. 가장 깊이 중첩된 노드부터 루트 노드 방향으로 이동하면서 각 노드를 대응하는 Markdown이 담긴 텍스트 노드로 변환합니다.

향후 작업

중첩 목록과 인용문 안의 목록 지원.
Markdown으로 표현할 수 없는 속성(예: style)을 가진 태그를 HTML로 보존하는 옵션 제공.

Markdown을 HTML로 변환하려면?

다음 라이브러리 중 하나를 사용하세요:

다만 엘프어를 배우게 된다는 보장은 없습니다.