Html To Markdown

인증된 제출자

league/html-to-markdown

제출자 이우진

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

HTML을 Markdown으로 변환하는 PHP 헬퍼

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 Purifier 같은 라이브러리로 추가 HTML 필터링을 적용하는 것도 고려하세요.

Markdown에 대응하는 문법이 없는 태그만 제거하고 내부 내용은 남기려면 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 ""

기본적으로 모든 주석은 제거됩니다. 주석을 남기려면 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 표는 원래 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 확장이 필요합니다. 대부분의 배포판에서는 이 확장들이 기본적으로 활성화되어 있습니다.

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

기여자

지금까지 함께해 주신 모든 기여자께 감사드립니다. 개선 사항과 기능 제안도 언제든 환영합니다.

동작 원리

HTML To Markdown은 입력 HTML로 DOMDocument를 만든 다음 DOM 트리를 순회합니다. 가장 깊이 중첩된 노드부터 루트 방향으로 처리하면서 각 노드를 해당 Markdown 문법이 담긴 텍스트 노드로 바꿉니다.

앞으로 할 일

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

Markdown을 HTML로 변환하려면?

다음 라이브러리를 사용해 보세요.

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