Html To Markdown
인증된 제출자league/html-to-markdown
PHP용 HTML-to-Markdown 변환 도우미
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에 대응되는 문법이 없는 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로 변환하고 싶으신가요?
다음과 같은 훌륭한 라이브러리를 사용해 보세요.
다만 엘프어에 대해서는 보장할 수 없습니다.