1 HTML To Markdown for PHP
2 ========================
4 [![Join the chat at https://gitter.im/thephpleague/html-to-markdown](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/thephpleague/html-to-markdown?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
6 [![Latest Version](https://img.shields.io/packagist/v/league/html-to-markdown.svg?style=flat-square)](https://packagist.org/packages/league/html-to-markdown)
7 [![Software License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
8 [![Build Status](https://img.shields.io/travis/thephpleague/html-to-markdown/master.svg?style=flat-square)](https://travis-ci.org/thephpleague/html-to-markdown)
9 [![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/thephpleague/html-to-markdown.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/html-to-markdown/code-structure)
10 [![Quality Score](https://img.shields.io/scrutinizer/g/thephpleague/html-to-markdown.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/html-to-markdown)
11 [![Total Downloads](https://img.shields.io/packagist/dt/league/html-to-markdown.svg?style=flat-square)](https://packagist.org/packages/league/html-to-markdown)
13 Library which converts HTML to [Markdown](http://daringfireball.net/projects/markdown/) for your sanity and convenience.
16 **Requires**: PHP 5.3+
18 **Lead Developer**: [@colinodell](http://twitter.com/colinodell)
20 **Original Author**: [@nickcernis](http://twitter.com/nickcernis)
23 ### Why convert HTML to Markdown?
25 *"What alchemy is this?"* you mutter. *"I can see why you'd convert [Markdown to HTML](https://github.com/thephpleague/commonmark),"* you continue, already labouring the question somewhat, *"but why go the other way?"*
27 Typically you would convert HTML to Markdown if:
29 1. You have an existing HTML document that needs to be edited by people with good taste.
30 2. You want to store new content in HTML format but edit it as Markdown.
31 3. You want to convert HTML email to plain text email.
32 4. You know a guy who's been converting HTML to Markdown for years, and now he can speak Elvish. You'd quite like to be able to speak Elvish.
33 5. You just really like Markdown.
37 Require the library by issuing this command:
40 composer require league/html-to-markdown
43 Add `require 'vendor/autoload.php';` to the top of your script.
45 Next, create a new HtmlConverter instance, passing in your valid HTML code to its `convert()` function:
48 use League\HTMLToMarkdown\HtmlConverter;
50 $converter = new HtmlConverter();
52 $html = "<h3>Quick, to the Batpoles!</h3>";
53 $markdown = $converter->convert($html);
56 The `$markdown` variable now contains the Markdown version of your HTML as a string:
59 echo $markdown; // ==> ### Quick, to the Batpoles!
62 The included `demo` directory contains an HTML->Markdown conversion form to try out.
64 ### Conversion options
66 By default, HTML To Markdown preserves HTML tags without Markdown equivalents, like `<span>` and `<div>`.
68 To strip HTML tags that don't have a Markdown equivalent while preserving the content inside them, set `strip_tags` to true, like this:
71 $converter = new HtmlConverter(array('strip_tags' => true));
73 $html = '<span>Turnips!</span>';
74 $markdown = $converter->convert($html); // $markdown now contains "Turnips!"
77 Or more explicitly, like this:
80 $converter = new HtmlConverter();
81 $converter->getConfig()->setOption('strip_tags', true);
83 $html = '<span>Turnips!</span>';
84 $markdown = $converter->convert($html); // $markdown now contains "Turnips!"
87 Note that only the tags themselves are stripped, not the content they hold.
89 To strip tags and their content, pass a space-separated list of tags in `remove_nodes`, like this:
92 $converter = new HtmlConverter(array('remove_nodes' => 'span div'));
94 $html = '<span>Turnips!</span><div>Monkeys!</div>';
95 $markdown = $converter->convert($html); // $markdown now contains ""
100 Bold and italic tags are converted using the asterisk syntax by default. Change this to the underlined syntax using the `bold_style` and `italic_style` options.
103 $converter = new HtmlConverter();
104 $converter->getConfig()->setOption('italic_style', '_');
105 $converter->getConfig()->setOption('bold_style', '__');
107 $html = '<em>Italic</em> and a <strong>bold</strong>';
108 $markdown = $converter->convert($html); // $markdown now contains "_Italic_ and a __bold__"
111 ### Line break options
113 By default, `br` tags are converted to two spaces followed by a newline character as per [traditional Markdown](https://daringfireball.net/projects/markdown/syntax#p). Set `hard_break` to `true` to omit the two spaces, as per GitHub Flavored Markdown (GFM).
116 $converter = new HtmlConverter();
117 $html = '<p>test<br>line break</p>';
119 $converter->getConfig()->setOption('hard_break', true);
120 $markdown = $converter->convert($html); // $markdown now contains "test\nline break"
122 $converter->getConfig()->setOption('hard_break', false); // default
123 $markdown = $converter->convert($html); // $markdown now contains "test \nline break"
126 ### Passing custom Environment object
128 You can pass current `Environment` object to customize i.e. which converters should be used.
131 $environment = new Environment(array(
132 // your configuration here
134 $environment->addConverter(new HeaderConverter()); // optionally - add converter manually
136 $converter = new HtmlConverter($environment);
138 $html = '<h3>Header</h3>
141 $markdown = $converter->convert($html); // $markdown now contains "### Header" and "<img src="" />"
146 - Markdown Extra, MultiMarkdown and other variants aren't supported – just Markdown.
150 - Nested lists and lists containing multiple paragraphs aren't converted correctly.
151 - Lists inside blockquotes aren't converted correctly.
152 - Any reported [open issues here](https://github.com/thephpleague/html-to-markdown/issues?state=open).
154 [Report your issue or request a feature here.](https://github.com/thephpleague/html-to-markdown/issues/new) Issues with patches or failing tests are especially welcome.
158 - Setext (underlined) headers are the default for H1 and H2. If you prefer the ATX style for H1 and H2 (# Header 1 and ## Header 2), set `header_style` to 'atx' in the options array when you instantiate the object:
160 `$converter = new HtmlConverter(array('header_style'=>'atx'));`
162 Headers of H3 priority and lower always use atx style.
164 - Links and images are referenced inline. Footnote references (where image src and anchor href attributes are listed in the footnotes) are not used.
165 - Blockquotes aren't line wrapped – it makes the converted Markdown easier to edit.
169 HTML To Markdown requires PHP's [xml](http://www.php.net/manual/en/xml.installation.php), [lib-xml](http://www.php.net/manual/en/libxml.installation.php), and [dom](http://www.php.net/manual/en/dom.installation.php) extensions, all of which are enabled by default on most distributions.
171 Errors such as "Fatal error: Class 'DOMDocument' not found" on distributions such as CentOS that disable PHP's xml extension can be resolved by installing php-xml.
175 Many thanks to all [contributors](https://github.com/thephpleague/html-to-markdown/graphs/contributors) so far. Further improvements and feature suggestions are very welcome.
179 HTML To Markdown creates a DOMDocument from the supplied HTML, walks through the tree, and converts each node to a text node containing the equivalent markdown, starting from the most deeply nested node and working inwards towards the root node.
183 - Support for nested lists and lists inside blockquotes.
184 - Offer an option to preserve tags as HTML if they contain attributes that can't be represented with Markdown (e.g. `style`).
186 ### Trying to convert Markdown to HTML?
188 Use one of these great libraries:
190 - [league/commonmark](https://github.com/thephpleague/commonmark) (recommended)
191 - [cebe/markdown](https://github.com/cebe/markdown)
192 - [PHP Markdown](https://michelf.ca/projects/php-markdown/)
193 - [Parsedown](https://github.com/erusev/parsedown)
195 No guarantees about the Elvish, though.