[Summary view] [Print] [Text view]

   1  PHP Markdown
   2  ============
   3  
   4  PHP Markdown Lib 1.4.1 - 4 May 2013
   5  
   6  by Michel Fortin  
   7  <http://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](<http://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]: http://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  <[email protected]>
 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  Version History
 164  ---------------
 165  
 166  PHP Markdown Lib 1.4.1 (4 May 2014)
 167  
 168  *    The HTML block parser will now treat `<figure>` as a block-level element
 169      (as it should) and no longer wrap it in `<p>` or parse it's content with 
 170      the as Markdown syntax (although with Extra you can use `markdown="1"`
 171      if you wish to use the Markdown syntax inside it).
 172  
 173  *    The content of `<style>` elements will now be left alone, its content
 174      won't be interpreted as Markdown.
 175  
 176  *    Corrected an bug where some inline links with spaces in them would not
 177      work even when surounded with angle brackets:
 178      
 179          [link](<s p a c e s>)
 180  
 181  *    Fixed an issue where email addresses with quotes in them would not always
 182      have the quotes escaped in the link attribute, causing broken links (and
 183      invalid HTML).
 184  
 185  *    Fixed the case were a link definition following a footnote definition would
 186      be swallowed by the footnote unless it was separated by a blank line.
 187  
 188  
 189  PHP Markdown Lib 1.4.0 (29 Nov 2013)
 190  
 191  *    Added support for the `tel:` URL scheme in automatic links.
 192  
 193          <tel:+1-111-111-1111>
 194      
 195      It gets converted to this (note the `tel:` prefix becomes invisible):
 196      
 197          <a href="tel:+1-111-111-1111">+1-111-111-1111</a>
 198  
 199  *    Added backtick fenced code blocks to MarkdownExtra, originally from
 200      Github-Flavored Markdown.
 201  
 202  *    Added an interface called MarkdownInterface implemented by both
 203      the Markdown and MarkdownExtra parsers. You can use the interface if
 204      you want to create a mockup parser object for unit testing.
 205  
 206  *    For those of you who cannot use class autoloading, you can now
 207      include `Michelf/Markdown.inc.php` or `Michelf/MarkdownExtra.inc.php` (note 
 208      the     `.inc.php` extension) to automatically include other files required
 209      by the parser.
 210  
 211  
 212  PHP Markdown Lib 1.3 (11 Apr 2013)
 213  
 214  This is the first release of PHP Markdown Lib. This package requires PHP 
 215  version 5.3 or later and is designed to work with PSR-0 autoloading and, 
 216  optionally with Composer. Here is a list of the changes since 
 217  PHP Markdown Extra 1.2.6:
 218  
 219  *    Plugin interface for WordPress and other systems is no longer present in
 220      the Lib package. The classic package is still available if you need it:
 221      <http://michelf.ca/projects/php-markdown/classic/>
 222  
 223  *    Added `public` and `protected` protection attributes, plus a section about
 224      what is "public API" and what isn't in the Readme file.
 225  
 226  *    Changed HTML output for footnotes: now instead of adding `rel` and `rev`
 227      attributes, footnotes links have the class name `footnote-ref` and
 228      backlinks `footnote-backref`.
 229  
 230  *    Fixed some regular expressions to make PCRE not shout warnings about POSIX
 231      collation classes (dependent on your version of PCRE).
 232  
 233  *    Added optional class and id attributes to images and links using the same
 234      syntax as for headers:
 235  
 236          [link](url){#id .class}  
 237          ![img](url){#id .class}
 238      
 239      It work too for reference-style links and images. In this case you need
 240      to put those attributes at the reference definition:
 241  
 242          [link][linkref] or [linkref]  
 243          ![img][linkref]
 244          
 245          [linkref]: url "optional title" {#id .class}
 246  
 247  *    Fixed a PHP notice message triggered when some table column separator 
 248      markers are missing on the separator line below column headers.
 249  
 250  *    Fixed a small mistake that could cause the parser to retain an invalid
 251      state related to parsing links across multiple runs. This was never 
 252      observed (that I know of), but it's still worth fixing.
 253  
 254  
 255  Copyright and License
 256  ---------------------
 257  
 258  PHP Markdown Lib
 259  Copyright (c) 2004-2014 Michel Fortin
 260  <http://michelf.ca/>  
 261  All rights reserved.
 262  
 263  Based on Markdown  
 264  Copyright (c) 2003-2005 John Gruber   
 265  <http://daringfireball.net/>   
 266  All rights reserved.
 267  
 268  Redistribution and use in source and binary forms, with or without
 269  modification, are permitted provided that the following conditions are
 270  met:
 271  
 272  *   Redistributions of source code must retain the above copyright 
 273      notice, this list of conditions and the following disclaimer.
 274  
 275  *   Redistributions in binary form must reproduce the above copyright
 276      notice, this list of conditions and the following disclaimer in the
 277      documentation and/or other materials provided with the 
 278      distribution.
 279  
 280  *   Neither the name "Markdown" nor the names of its contributors may
 281      be used to endorse or promote products derived from this software
 282      without specific prior written permission.
 283  
 284  This software is provided by the copyright holders and contributors "as
 285  is" and any express or implied warranties, including, but not limited
 286  to, the implied warranties of merchantability and fitness for a
 287  particular purpose are disclaimed. In no event shall the copyright owner
 288  or contributors be liable for any direct, indirect, incidental, special,
 289  exemplary, or consequential damages (including, but not limited to,
 290  procurement of substitute goods or services; loss of use, data, or
 291  profits; or business interruption) however caused and on any theory of
 292  liability, whether in contract, strict liability, or tort (including
 293  negligence or otherwise) arising in any way out of the use of this
 294  software, even if advised of the possibility of such damage.