vendor/league/html-to-markdown/README.md

   1 HTML To Markdown for PHP
   2 ========================
   3
   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)
   5
   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)
  12
  13 Library which converts HTML to [Markdown](http://daringfireball.net/projects/markdown/) for your sanity and convenience.
  14
  15
  16 **Requires**: PHP 5.3+
  17
  18 **Lead Developer**: [@colinodell](http://twitter.com/colinodell)
  19
  20 **Original Author**: [@nickcernis](http://twitter.com/nickcernis)
  21
  22
  23 ### Why convert HTML to Markdown?
  24
  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?"*
  26
  27 Typically you would convert HTML to Markdown if:
  28
  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.
  34
  35 ### How to use it
  36
  37 Require the library by issuing this command:
  38
  39 ```bash
  40 composer require league/html-to-markdown
  41 ```
  42
  43 Add `require 'vendor/autoload.php';` to the top of your script.
  44
  45 Next, create a new HtmlConverter instance, passing in your valid HTML code to its `convert()` function:
  46
  47 ```php
  48 use League\HTMLToMarkdown\HtmlConverter;
  49
  50 $converter = new HtmlConverter();
  51
  52 $html = "<h3>Quick, to the Batpoles!</h3>";
  53 $markdown = $converter->convert($html);
  54 ```
  55
  56 The `$markdown` variable now contains the Markdown version of your HTML as a string:
  57
  58 ```php
  59 echo $markdown; // ==> ### Quick, to the Batpoles!
  60 ```
  61
  62 The included `demo` directory contains an HTML->Markdown conversion form to try out.
  63
  64 ### Conversion options
  65
  66 By default, HTML To Markdown preserves HTML tags without Markdown equivalents, like `<span>` and `<div>`.
  67
  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:
  69
  70 ```php
  71 $converter = new HtmlConverter(array('strip_tags' => true));
  72
  73 $html = '<span>Turnips!</span>';
  74 $markdown = $converter->convert($html); // $markdown now contains "Turnips!"
  75 ```
  76
  77 Or more explicitly, like this:
  78
  79 ```php
  80 $converter = new HtmlConverter();
  81 $converter->getConfig()->setOption('strip_tags', true);
  82
  83 $html = '<span>Turnips!</span>';
  84 $markdown = $converter->convert($html); // $markdown now contains "Turnips!"
  85 ```
  86
  87 Note that only the tags themselves are stripped, not the content they hold.
  88
  89 To strip tags and their content, pass a space-separated list of tags in `remove_nodes`, like this:
  90
  91 ```php
  92 $converter = new HtmlConverter(array('remove_nodes' => 'span div'));
  93
  94 $html = '<span>Turnips!</span><div>Monkeys!</div>';
  95 $markdown = $converter->convert($html); // $markdown now contains ""
  96 ```
  97
  98 ### Style options
  99
 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.
 101
 102 ```php
 103 $converter = new HtmlConverter();
 104 $converter->getConfig()->setOption('italic_style', '_');
 105 $converter->getConfig()->setOption('bold_style', '__');
 106
 107 $html = '<em>Italic</em> and a <strong>bold</strong>';
 108 $markdown = $converter->convert($html); // $markdown now contains "_Italic_ and a __bold__"
 109 ```
 110
 111 ### Line break options
 112
 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).
 114
 115 ```php
 116 $converter = new HtmlConverter();
 117 $html = '<p>test<br>line break</p>';
 118
 119 $converter->getConfig()->setOption('hard_break', true);
 120 $markdown = $converter->convert($html); // $markdown now contains "test\nline break"
 121
 122 $converter->getConfig()->setOption('hard_break', false); // default
 123 $markdown = $converter->convert($html); // $markdown now contains "test  \nline break"
 124 ```
 125
 126 ### Passing custom Environment object
 127
 128 You can pass current `Environment` object to customize i.e. which converters should be used.
 129
 130 ```php
 131 $environment = new Environment(array(
 132     // your configuration here
 133 ));
 134 $environment->addConverter(new HeaderConverter()); // optionally - add converter manually
 135
 136 $converter = new HtmlConverter($environment);
 137
 138 $html = '<h3>Header</h3>
 139 <img src="" />
 140 ';
 141 $markdown = $converter->convert($html); // $markdown now contains "### Header" and "<img src="" />"
 142 ```
 143
 144 ### Limitations
 145
 146 - Markdown Extra, MultiMarkdown and other variants aren't supported – just Markdown.
 147
 148 ### Known issues
 149
 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).
 153
 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.
 155
 156 ### Style notes
 157
 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:
 159
 160     `$converter = new HtmlConverter(array('header_style'=>'atx'));`
 161
 162      Headers of H3 priority and lower always use atx style.
 163
 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.
 166
 167 ### Dependencies
 168
 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.
 170
 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.
 172
 173 ### Contributors
 174
 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.
 176
 177 ### How it works
 178
 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.
 180
 181 ### To-do
 182
 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`).
 185
 186 ### Trying to convert Markdown to HTML?
 187
 188 Use one of these great libraries:
 189
 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)
 194
 195 No guarantees about the Elvish, though.
 196