[Summary view] [Print] [Text view]

   1  PHP Markdown
   2  ============
   3  
   4  PHP Markdown Lib 1.5.0 - 1 Mar 2015
   5  
   6  by Michel Fortin  
   7  <https://michelf.ca/>
   8  
   9  based on Markdown by John Gruber  
  10  <http://daringfireball.net/>
  11  
  12  
  13  Introduction
  14  ------------
  15  
  16  This is a library package that includes the PHP Markdown parser and its 
  17  sibling PHP Markdown Extra with additional features.
  18  
  19  Markdown is a text-to-HTML conversion tool for web writers. Markdown
  20  allows you to write using an easy-to-read, easy-to-write plain text
  21  format, then convert it to structurally valid XHTML (or HTML).
  22  
  23  "Markdown" is actually two things: a plain text markup syntax, and a 
  24  software tool, originally written in Perl, that converts the plain text 
  25  markup to HTML. PHP Markdown is a port to PHP of the original Markdown 
  26  program by John Gruber.
  27  
  28  *    [Full documentation of the Markdown syntax](<http://daringfireball.net/projects/markdown/>)  
  29      — Daring Fireball (John Gruber)
  30  *    [Markdown Extra syntax additions](<https://michelf.ca/projects/php-markdown/extra/>)  
  31      — Michel Fortin
  32  
  33  
  34  Requirement
  35  -----------
  36  
  37  This library package requires PHP 5.3 or later.
  38  
  39  Note: The older plugin/library hybrid package for PHP Markdown and
  40  PHP Markdown Extra is still maintained and will work with PHP 4.0.5 and later.
  41  
  42  Before PHP 5.3.7, pcre.backtrack_limit defaults to 100 000, which is too small
  43  in many situations. You might need to set it to higher values. Later PHP 
  44  releases defaults to 1 000 000, which is usually fine.
  45  
  46  
  47  Usage
  48  -----
  49  
  50  This library package is meant to be used with class autoloading. For autoloading 
  51  to work, your project needs have setup a PSR-0-compatible autoloader. See the 
  52  included Readme.php file for a minimal autoloader setup. (If you cannot use 
  53  autoloading, see below.)
  54  
  55  With class autoloading in place, putting the 'Michelf' folder in your 
  56  include path should be enough for this to work:
  57  
  58      use \Michelf\Markdown;
  59      $my_html = Markdown::defaultTransform($my_text);
  60  
  61  Markdown Extra syntax is also available the same way:
  62  
  63      use \Michelf\MarkdownExtra;
  64      $my_html = MarkdownExtra::defaultTransform($my_text);
  65  
  66  If you wish to use PHP Markdown with another text filter function 
  67  built to parse HTML, you should filter the text *after* the `transform`
  68  function call. This is an example with [PHP SmartyPants][psp]:
  69  
  70      use \Michelf\Markdown, \Michelf\SmartyPants;
  71      $my_html = Markdown::defaultTransform($my_text);
  72      $my_html = SmartyPants::defaultTransform($my_html);
  73  
  74  All these examples are using the static `defaultTransform` static function 
  75  found inside the parser class. If you want to customize the parser 
  76  configuration, you can also instantiate it directly and change some 
  77  configuration variables:
  78  
  79      use \Michelf\MarkdownExtra;
  80      $parser = new MarkdownExtra;
  81      $parser->fn_id_prefix = "post22-";
  82      $my_html = $parser->transform($my_text);
  83  
  84  To learn more, see the full list of [configuration variables].
  85  
  86   [configuration variables]: https://michelf.ca/projects/php-markdown/configuration/
  87  
  88  
  89  ### Usage without an autoloader
  90  
  91  If you cannot use class autoloading, you can still use `include` or `require` 
  92  to access the parser. To load the `\Michelf\Markdown` parser, do it this way:
  93  
  94      require_once 'Michelf/Markdown.inc.php';
  95  
  96  Or, if you need the `\Michelf\MarkdownExtra` parser:
  97  
  98      require_once 'Michelf/MarkdownExtra.inc.php';
  99  
 100  While the plain `.php` files depend on autoloading to work correctly, using the
 101  `.inc.php` files instead will eagerly load the dependencies that would be 
 102  loaded on demand if you were using autoloading.
 103  
 104  
 105  Public API and Versioning Policy
 106  ---------------------------------
 107  
 108  Version numbers are of the form *major*.*minor*.*patch*.
 109  
 110  The public API of PHP Markdown consist of the two parser classes `Markdown`
 111  and `MarkdownExtra`, their constructors, the `transform` and `defaultTransform`
 112  functions and their configuration variables. The public API is stable for
 113  a given major version number. It might get additions when the minor version
 114  number increments.
 115  
 116  **Protected members are not considered public API.** This is unconventional 
 117  and deserves an explanation. Incrementing the major version number every time 
 118  the underlying implementation of something changes is going to give
 119  nonessential version numbers for the vast majority of people who just use the
 120  parser.  Protected members are meant to create parser subclasses that behave in
 121  different ways. Very few people create parser subclasses. I don't want to 
 122  discourage it by making everything private, but at the same time I can't 
 123  guarantee any stable hook between versions if you use protected members.
 124  
 125  **Syntax changes** will increment the minor number for new features, and the 
 126  patch number for small corrections. A *new feature* is something that needs a 
 127  change in the syntax documentation. Note that since PHP Markdown Lib includes
 128  two parsers, a syntax change for either of them will increment the minor 
 129  number. Also note that there is nothing perfectly backward-compatible with the
 130  Markdown syntax: all inputs are always valid, so new features always replace
 131  something that was previously legal, although generally nonsensical to do.
 132  
 133  
 134  Bugs
 135  ----
 136  
 137  To file bug reports please send email to:
 138  <michel.fortin@michelf.ca>
 139  
 140  Please include with your report: (1) the example input; (2) the output you
 141  expected; (3) the output PHP Markdown actually produced.
 142  
 143  If you have a problem where Markdown gives you an empty result, first check 
 144  that the backtrack limit is not too low by running `php --info | grep pcre`.
 145  See Installation and Requirement above for details.
 146  
 147  
 148  Development and Testing
 149  -----------------------
 150  
 151  Pull requests for fixing bugs are welcome. Proposed new features are
 152  going meticulously reviewed -- taking into account backward compatibility, 
 153  potential side effects, and future extensibility -- before deciding on
 154  acceptance or rejection.
 155  
 156  If you make a pull request that includes changes to the parser please add 
 157  tests for what is being changed to [MDTest][] and make a pull request there 
 158  too.
 159  
 160   [MDTest]: https://github.com/michelf/mdtest/
 161  
 162  
 163  Donations
 164  ---------
 165  
 166  If you wish to make a donation that will help me devote more time to 
 167  PHP Markdown, please visit [michelf.ca/donate] or send Bitcoin to
 168  [1HiuX34czvVPPdhXbUAsAu7pZcesniDCGH].
 169  
 170   [michelf.ca/donate]: https://michelf.ca/donate/#!Thanks%20for%20PHP%20Markdown
 171   [1HiuX34czvVPPdhXbUAsAu7pZcesniDCGH]: bitcoin:1HiuX34czvVPPdhXbUAsAu7pZcesniDCGH
 172  
 173  
 174  Version History
 175  ---------------
 176  
 177  PHP Markdown Lib 1.5.0 (1 Mar 2015)
 178  
 179  *    Added the ability start ordered lists with a number different from 1 and
 180      and have that reflected in the HTML output. This can be enabled with
 181      the `enhanced_ordered_lists` configuration variable for the Markdown 
 182      parser; it is enabled by default for Markdown Extra.
 183      Credits to Matt Gorle for providing the implementation.
 184  
 185  *    Added the ability to insert custom HTML attributes with simple values 
 186      everywhere an extra attribute block is allowed (links, images, headers).
 187      The value must be unquoted, cannot contains spaces and is limited to 
 188      alphanumeric ASCII characters.
 189      Credits to Peter Droogmans for providing the implementation.
 190  
 191  *    Added a `header_id_func` configuration variable which takes a function
 192      that can generate an `id` attribute value from the header text.
 193      Credits to Evert Pot for providing the implementation.
 194  
 195  *    Added a `url_filter_func` configuration variable which takes a function
 196      that can rewrite any link or image URL to something different.
 197  
 198  
 199  PHP Markdown Lib 1.4.1 (4 May 2014)
 200  
 201  *    The HTML block parser will now treat `<figure>` as a block-level element
 202      (as it should) and no longer wrap it in `<p>` or parse it's content with 
 203      the as Markdown syntax (although with Extra you can use `markdown="1"`
 204      if you wish to use the Markdown syntax inside it).
 205  
 206  *    The content of `<style>` elements will now be left alone, its content
 207      won't be interpreted as Markdown.
 208  
 209  *    Corrected an bug where some inline links with spaces in them would not
 210      work even when surounded with angle brackets:
 211      
 212          [link](<s p a c e s>)
 213  
 214  *    Fixed an issue where email addresses with quotes in them would not always
 215      have the quotes escaped in the link attribute, causing broken links (and
 216      invalid HTML).
 217  
 218  *    Fixed the case were a link definition following a footnote definition would
 219      be swallowed by the footnote unless it was separated by a blank line.
 220  
 221  
 222  PHP Markdown Lib 1.4.0 (29 Nov 2013)
 223  
 224  *    Added support for the `tel:` URL scheme in automatic links.
 225  
 226          <tel:+1-111-111-1111>
 227      
 228      It gets converted to this (note the `tel:` prefix becomes invisible):
 229      
 230          <a href="tel:+1-111-111-1111">+1-111-111-1111</a>
 231  
 232  *    Added backtick fenced code blocks to MarkdownExtra, originally from
 233      Github-Flavored Markdown.
 234  
 235  *    Added an interface called MarkdownInterface implemented by both
 236      the Markdown and MarkdownExtra parsers. You can use the interface if
 237      you want to create a mockup parser object for unit testing.
 238  
 239  *    For those of you who cannot use class autoloading, you can now
 240      include `Michelf/Markdown.inc.php` or `Michelf/MarkdownExtra.inc.php` (note 
 241      the     `.inc.php` extension) to automatically include other files required
 242      by the parser.
 243  
 244  
 245  PHP Markdown Lib 1.3 (11 Apr 2013)
 246  
 247  This is the first release of PHP Markdown Lib. This package requires PHP 
 248  version 5.3 or later and is designed to work with PSR-0 autoloading and, 
 249  optionally with Composer. Here is a list of the changes since 
 250  PHP Markdown Extra 1.2.6:
 251  
 252  *    Plugin interface for WordPress and other systems is no longer present in
 253      the Lib package. The classic package is still available if you need it:
 254      <https://michelf.ca/projects/php-markdown/classic/>
 255  
 256  *    Added `public` and `protected` protection attributes, plus a section about
 257      what is "public API" and what isn't in the Readme file.
 258  
 259  *    Changed HTML output for footnotes: now instead of adding `rel` and `rev`
 260      attributes, footnotes links have the class name `footnote-ref` and
 261      backlinks `footnote-backref`.
 262  
 263  *    Fixed some regular expressions to make PCRE not shout warnings about POSIX
 264      collation classes (dependent on your version of PCRE).
 265  
 266  *    Added optional class and id attributes to images and links using the same
 267      syntax as for headers:
 268  
 269          [link](url){#id .class}  
 270          ![img](url){#id .class}
 271      
 272      It work too for reference-style links and images. In this case you need
 273      to put those attributes at the reference definition:
 274  
 275          [link][linkref] or [linkref]  
 276          ![img][linkref]
 277          
 278          [linkref]: url "optional title" {#id .class}
 279  
 280  *    Fixed a PHP notice message triggered when some table column separator 
 281      markers are missing on the separator line below column headers.
 282  
 283  *    Fixed a small mistake that could cause the parser to retain an invalid
 284      state related to parsing links across multiple runs. This was never 
 285      observed (that I know of), but it's still worth fixing.
 286  
 287  
 288  Copyright and License
 289  ---------------------
 290  
 291  PHP Markdown Lib
 292  Copyright (c) 2004-2015 Michel Fortin
 293  <https://michelf.ca/>  
 294  All rights reserved.
 295  
 296  Based on Markdown  
 297  Copyright (c) 2003-2005 John Gruber   
 298  <http://daringfireball.net/>   
 299  All rights reserved.
 300  
 301  Redistribution and use in source and binary forms, with or without
 302  modification, are permitted provided that the following conditions are
 303  met:
 304  
 305  *   Redistributions of source code must retain the above copyright 
 306      notice, this list of conditions and the following disclaimer.
 307  
 308  *   Redistributions in binary form must reproduce the above copyright
 309      notice, this list of conditions and the following disclaimer in the
 310      documentation and/or other materials provided with the 
 311      distribution.
 312  
 313  *   Neither the name "Markdown" nor the names of its contributors may
 314      be used to endorse or promote products derived from this software
 315      without specific prior written permission.
 316  
 317  This software is provided by the copyright holders and contributors "as
 318  is" and any express or implied warranties, including, but not limited
 319  to, the implied warranties of merchantability and fitness for a
 320  particular purpose are disclaimed. In no event shall the copyright owner
 321  or contributors be liable for any direct, indirect, incidental, special,
 322  exemplary, or consequential damages (including, but not limited to,
 323  procurement of substitute goods or services; loss of use, data, or
 324  profits; or business interruption) however caused and on any theory of
 325  liability, whether in contract, strict liability, or tort (including
 326  negligence or otherwise) arising in any way out of the use of this
 327  software, even if advised of the possibility of such damage.