`. Block elements are normally spreads over several lines and are separated by blank lines.
+The most basic block element is a paragraph (``).
+Inline elements are elements that are added inside of block elements i.e. inside of text.
+
+This markdown parser allows you to extend the markdown language by changing existing elements behavior and also adding
+new block and inline elements. You do this by extending from the parser class and adding/overriding class methods and
+properties. For the different element types there are different ways to extend them as you will see in the following sections.
+
+### Adding block elements
+
+The markdown is parsed line by line to identify each non-empty line as one of the block element types.
+To identify a line as the beginning of a block element it calls all protected class methods who's name begins with `identify`.
+An identify function returns true if it has identified the block element it is responsible for or false if not.
+In the following example we will implement support for [fenced code blocks][] which are part of the github flavored markdown.
+
+[fenced code blocks]: https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks
+ "Fenced code block feature of github flavored markdown"
+
+```php
+ [],
+ ];
+ $line = rtrim($lines[$current]);
+
+ // detect language and fence length (can be more than 3 backticks)
+ $fence = substr($line, 0, $pos = strrpos($line, '`') + 1);
+ $language = substr($line, $pos);
+ if (!empty($language)) {
+ $block['language'] = $language;
+ }
+
+ // consume all lines until ```
+ for($i = $current + 1, $count = count($lines); $i < $count; $i++) {
+ if (rtrim($line = $lines[$i]) !== $fence) {
+ $block['content'][] = $line;
+ } else {
+ // stop consuming when code block is over
+ break;
+ }
+ }
+ return [$block, $i];
+ }
+ ```
+
+2. "rendering" the element. After all blocks have been consumed, they are being rendered using the
+ `render{elementName}()`-method where `elementName` refers to the name of the element in the abstract syntax tree:
+
+ ```php
+ protected function renderFencedCode($block)
+ {
+ $class = isset($block['language']) ? ' class="language-' . $block['language'] . '"' : '';
+ return "
" . htmlspecialchars(implode("\n", $block['content']) . "\n", ENT_NOQUOTES, 'UTF-8') . '
';
+ }
+ ```
+
+ You may also add code highlighting here. In general it would also be possible to render ouput in a different language than
+ HTML for example LaTeX.
+
+
+### Adding inline elements
+
+Adding inline elements is different from block elements as they are parsed using markers in the text.
+An inline element is identified by a marker that marks the beginning of an inline element (e.g. `[` will mark a possible
+beginning of a link or `` ` `` will mark inline code).
+
+Parsing methods for inline elements are also protected and identified by the prefix `parse`. Additionally a `@marker` annotation
+in PHPDoc is needed to register the parse function for one or multiple markers.
+The method will then be called when a marker is found in the text. As an argument it takes the text starting at the position of the marker.
+The parser method will return an array containing the element of the abstract sytnax tree and an offset of text it has
+parsed from the input markdown. All text up to this offset will be removed from the markdown before the next marker will be searched.
+
+As an example, we will add support for the [strikethrough][] feature of github flavored markdown:
+
+[strikethrough]: https://help.github.com/articles/github-flavored-markdown#strikethrough "Strikethrough feature of github flavored markdown"
+
+```php
+parseInline($matches[1])],
+ // return the offset of the parsed text
+ strlen($matches[0])
+ ];
+ }
+ // in case we did not find a closing ~~ we just return the marker and skip 2 characters
+ return [['text', '~~'], 2];
+ }
+
+ // rendering is the same as for block elements, we turn the abstract syntax array into a string.
+ protected function renderStrike($element)
+ {
+ return '' . $this->renderAbsy($element[1]) . '';
+ }
+}
+```
+
+### Composing your own Markdown flavor
+
+TBD
+
+
+Acknowledgements
+----------------
+
+I'd like to thank [@erusev][] for creating [Parsedown][] which heavily influenced this work and provided
+the idea of the line based parsing approach.
+
+[@erusev]: https://github.com/erusev "Emanuil Rusev"
+
+FAQ
+---
+
+### Why another markdown parser?
+
+While reviewing PHP markdown parsers for choosing one to use bundled with the [Yii framework 2.0][]
+I found that most of the implementations use regex to replace patterns instead
+of doing real parsing. This way extending them with new language elements is quite hard
+as you have to come up with a complex regex, that matches your addition but does not mess
+with other elements. Such additions are very common as you see on github which supports referencing
+issues, users and commits in the comments.
+A [real parser][] should use context aware methods that walk trough the text and
+parse the tokens as they find them. The only implentation that I have found that uses
+this approach is [Parsedown][] which also shows that this implementation is [much faster][benchmark]
+than the regex way. Parsedown however is an implementation that focuses on speed and implements
+its own flavor (mainly github flavored markdown) in one class and at the time of this writing was
+not easily extensible.
+
+Given the situation above I decided to start my own implementation using the parsing approach
+from Parsedown and making it extensible creating a class for each markdown flavor that extend each
+other in the way that also the markdown languages extend each other.
+This allows you to choose between markdown language flavors and also provides a way to compose your
+own flavor picking the best things from all.
+I chose this approach as it is easier to implement and also more intuitive approach compared
+to using callbacks to inject functionallity into the parser.
+
+
+### Where do I report bugs or rendering issues?
+
+Just [open an issue][] on github, post your markdown code and describe the problem. You may also attach screenshots of the rendered HTML result to describe your problem.
+
+
+### How can I contribute to this library?
+
+Check the [CONTRIBUTING.md](CONTRIBUTING.md) file for more info.
+
+
+### Am I free to use this?
+
+This library is open source and licensed under the [MIT License][]. This means that you can do whatever you want
+with it as long as you mention my name and include the [license file][license]. Check the [license][] for details.
+
+[MIT License]: http://opensource.org/licenses/MIT
+
+
+Contact
+-------
+
+Feel free to contact me using [email](mailto:mail@cebe.cc) or [twitter](https://twitter.com/cebe_cc).
+
+
+[PHP]: http://php.net/ "PHP is a popular general-purpose scripting language that is especially suited to web development."
+[Markdown]: http://en.wikipedia.org/wiki/Markdown "Markdown on Wikipedia"
+[composer]: https://getcomposer.org/ "The PHP package manager"
+[Parsedown]: http://parsedown.org/ "The Parsedown PHP Markdown parser"
+[benchmark]: https://github.com/kzykhys/Markbench#readme "kzykhys/Markbench on github"
+[Yii framework 2.0]: https://github.com/yiisoft/yii2
+[real parser]: http://en.wikipedia.org/wiki/Parsing#Types_of_parser
+[open an issue]: https://github.com/cebe/markdown/issues/new
+[license]: https://github.com/cebe/markdown/blob/master/LICENSE