본문 바로가기
← 패키지 목록

Html To Markdown

인증된 제출자

league/html-to-markdown

제출자 이우진
최신 v5.2.3라이센스 MIT배포 2026년 10월 23일

PHP용 HTML-to-Markdown 변환 도우미

PHP용 HTML to Markdown

Latest Version Software License Build Status Coverage Status Quality Score Total Downloads

HTML을 Markdown으로 변환해 주는 라이브러리입니다. 여러분의 정신 건강과 편의를 위해 만들어졌습니다.

요구 사항: PHP 7.2 이상

리드 개발자: @colinodell

원저자: @nickcernis

왜 HTML을 Markdown으로 변환할까요?

"이게 무슨 연금술이지?" 하고 중얼거리실 수도 있습니다. "Markdown을 HTML로 바꾸는 건 이해가 가지만," 이미 질문을 질질 끌고 있다는 걸 알면서도 말을 이어 가겠지요. "왜 굳이 반대로 하는 거지?"

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

  1. 기존 HTML 문서를 안목 있는 사람들이 편집해야 할 때
  2. 새 콘텐츠를 HTML 형식으로 저장하되, 편집은 Markdown으로 하고 싶을 때
  3. HTML 이메일을 일반 텍스트 이메일로 바꾸고 싶을 때
  4. 몇 년째 HTML을 Markdown으로 변환해 온 지인이 있는데, 이제 엘프어를 할 줄 알게 되었습니다. 여러분도 엘프어를 할 수 있다면 좋겠지요.
  5. 그냥 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에 대응되는 문법이 없는 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 ""

기본적으로 모든 주석은 결과에서 제거됩니다. 주석을 보존하려면 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) 태그는 별표 문법으로, 기울임(italic) 태그는 밑줄 문법으로 변환됩니다. 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 태그는 가능한 한 가장 간단한 링크 문법으로 변환됩니다. 즉, 링크 텍스트나 title이 없으면 전체 [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 속성을 각주에 모아 두는 각주 참조 방식은 사용하지 않습니다.

  • 인용문(blockquote)은 줄바꿈 처리를 하지 않습니다. 변환된 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로 변환하고 싶으신가요?

다음과 같은 훌륭한 라이브러리를 사용해 보세요.

다만 엘프어에 대해서는 보장할 수 없습니다.