Class MarkdownDocument

Description

A class that represents a document written the markdown markup language, allowing it to be converted into an HTML document.

Simple typical usage has the form (full examples linked below):

  1. $md MarkdownDocument::createFromString($markdown_str);
  2. $md->compile();
  3. echo $md->getHtml();

Unless otherwise noted, all the methods:

  • Return FALSE if there is a wrong number of arguments or if the type of the argument is unexpected and PHP does not provide an automatic conversion to the required type.
  • Throw LogicException if the method is an instance method and, except for MarkdownDocument::initFromStream() and MarkdownDocument::initFromString(), is used without the document having been initialized. This can only happen in subclasses whose constructor doesn't call either MarkdownDocument::initFromStream() or MarkdownDocument::initFromString() (or calls to them fail but the constructor doesn't abort the object construction with an exception).
  • Throw LogicException if the method is called from within a callback provided to MarkdownDocument::setUrlCallback() or MarkdownDocument::setAttributeCallback().
  • Throw LogicException if the method requires the Markdown document to be compiled, but it isn't (or not to be compiled, but it is).

The methods that take a stream can instead take a URL from which such stream can be opened, but beware that if the method is to write a result, the stream will be opened with mode 'w', most likely discarding the previous contents of the file.

Explaining the Markdown syntax is beyond the scope of this documentation. For that purpose, you can consult the syntax of the original Markdown. Discount also implements several extensions, which you can deactivate with great granularity by using the flags described in this document.

Located in /MarkdownDocument.php (line 68)


	
			
Class Constant Summary
 AUTOLINK = 16384
 CDATA = 128
 EMBED = 35
 EXTRA_FOOTNOTE = 2097152
 NOALPHALIST = 524288
 NODIVQUOTE = 262144
 NODLIST = 1048576
 NOHEADER = 65536
 NOHTML = 8
 NOIMAGE = 2
 NOLINKS = 1
 NOPANTS = 4
 NORELAXED = 512
 NOTABLES = 1024
 NO_EXT = 64
 ONE_COMPAT = 8192
 SAFELINK = 32768
 STRICT = 16
 TABSTOP = 131072
 TAGTEXT = 32
 TOC = 4096
Method Summary
 static MarkdownDocument createFromStream (mixed $markdown_stream, [integer $flags = 0])
 static MarkdownDocument createFromString (mixed $markdown_doc, [integer $flags = 0])
 static string transformFragment (string $markdown_fragment, [integer $flags = 0])
 static boolean writeFragment (string $markdown_fragment, mixed $out_stream, [integer $flags = 0])
 MarkdownDocument __construct ()
 boolean compile (integer $flags)
 boolean dumpTree (mixed $out_stream, [string $title = ""])
 string getAuthor ()
 string getCss ()
 string getDate ()
 string getHtml ()
 string getTitle ()
 string getToc ()
 boolean initFromStream (mixed $markdown_stream, [integer $flags = 0])
 boolean initFromString (mixed $markdown_doc, [integer $flags = 0])
 boolean isCompiled ()
 boolean setAttributesCallback (callback $callback)
 boolean setReferencePrefix (string $prefix)
 boolean setUrlCallback (callback $callback)
 boolean writeCss (mixed $markdown_outstream)
 boolean writeHtml (mixed $markdown_outstream)
 boolean writeToc (mixed $markdown_outstream)
 boolean writeXhtmlPage (mixed $markdown_outstream)
Methods
static createFromStream (line 452)

Creates a MarkdownDocument from a stream.

This is one of the two public methods available for creating an object of this type, which is required as an initial step for full markdown processing.

MarkdownDocument createFromStream (mixed $markdown_stream, [integer $flags = 0])
  • mixed $markdown_stream: Either a stream resource opened with reading permissions or a URL from which such a stream can be opened.
  • integer $flags: Data input type flags. Only the flags MarkdownDocument::NOHEADER and MarkdownDocument::TABSTOP are allowed.
static createFromString (line 472)

Creates a MarkdownDocument from a string.

This is one of the two public methods available for creating an object of this type, which is required as an initial step for full markdown processing.

MarkdownDocument createFromString (mixed $markdown_doc, [integer $flags = 0])
static transformFragment (line 498)

Reads markdown from a string and transforms it to HTML without creating any block elements.

In this form (inline markdown), the transformations made are much more limited than with the combination of MarkdownDocument::createFromString(), MarkdownDocument::compile() and MarkdownDocument::getHtml(). No paragraph tags are added and no tables, block quotes, code blocks, pandoc headers or reference-style links/images or lists are processed.

Arbitrary HTML is still allowed, unless the MarkdownDocument::NOHTML flag is given.

string transformFragment (string $markdown_fragment, [integer $flags = 0])
  • string $markdown_fragment: The markdown fragment to convert.
  • integer $flags: Compile flags appropriate for inline markdown (several features are disabled in inline markdown, so many flags have no effect).
static writeFragment (line 528)

Reads markdown from a string, transforms it to HTML without creating any block elements and writes the result to a stream.

In this form (inline markdown), the transformations made are much more limited than with the combination of MarkdownDocument::createFromString(), MarkdownDocument::compile() and MarkdownDocument::writeHtml(). No paragraph tags are added and no tables, block quotes, code blocks, pandoc headers or reference-style links/images or lists are processed.

Arbitrary HTML is still allowed, unless the MarkdownDocument::NOHTML flag is given.

  • return: TRUE if all the data is successfully written; if there is an error when writing to the stream, FALSE is returned and a warning is raised. The usual error handling for MarkdownDocument objects still apply.
  • see: MarkdownDocument::transformFragment()
  • since: 0.1.0
  • access: public
boolean writeFragment (string $markdown_fragment, mixed $out_stream, [integer $flags = 0])
  • string $markdown_fragment: The markdown fragment to convert.
  • mixed $out_stream: A resource stream that can be written to or a URL with which a stream with writing permissions can be opened.
  • integer $flags: Compile flags appropriate for inline markdown (several features are disabled in inline markdown, so many flags have no effect).
Constructor __construct (line 550)

A no-op protected constructor.

This method prevents instantiation of the MarkdownDocument class with new, forcing the usage of MarkdownDocument::createFromString() or MarkdownDocument::createFromStream().

It is protected to, nevertheless, allow subclassing in a straightforward manner by overriding this constructor. The overriding constructor need not call this method, as it is a no-op. It should, however, call either the MarkdownDocument::initFromString() or MarkdownDocument::initFromStream().

MarkdownDocument __construct ()
compile (line 609)

Compiles this document, preparing the HTML data to be retrieved.

  • return: TRUE unless one of the usual error conditions for the MarkdownDocument class is triggered.
  • throws: LogicException if the object has already been compiled.
  • since: 0.1.0
  • access: public
boolean compile (integer $flags)
dumpTree (line 636)

Write an outline view of the document.

  • return: Returns TRUE, except for the situations covered in the class summary.
  • since: 0.1.0
  • access: public
  • example: dumpTree() in action.
boolean dumpTree (mixed $out_stream, [string $title = ""])
  • mixed $out_stream: A resource stream opened with write permissions or a URL that can be opened to yield such a stream, for writing the output.
  • string $title: A string to be prefixed to the tree.
getAuthor (line 675)

The author or authors found in the pandoc-style hader.

Note that discount does not currently support multi-line authors.

The document need not have been compiled.

string getAuthor ()
getCss (line 808)

Give all the <style> elements found in the markdown document. These elements will not be included in the result returned by MarkdownDocument::getHtml().

This function returns an empty string if the flag MarkdownDocument::NOHTML was specified.

The markdown document must have already been compiled.

string getCss ()
getDate (line 692)

The date found in the pandoc-style header.

The document need not have been compiled.

string getDate ()
getHtml (line 719)

Generate and return the body HTML data that results from processing this document.

This includes all the data present in the given markup with the exception of the pandoc-style headers and the style blocks. The unprocessed headers will, however, show up if MarkdownDocument::NOHEADER is given, and the escaped style blocks will show up if MarkdownDocument::NOHTML is given.

The document should already have been compiled.

If defined, this method calls the callbacks specified through MarkdownDocument::setUrlCallback() and MarkdownDocument::setAttributesCallback() for each link generated. If any of these callbacks throws an exception, this method throws another exception on top of it on the first time.

string getHtml ()
getTitle (line 656)

The title found in the pandoc-style header.

Note that discount does not currently support multi-line titles.

The document need not have been compiled.

string getTitle ()
getToc (line 791)

Returns the table of contents HTML data.

This method must be called after the document has been compiled with MarkdownDocument::TOC.

string getToc ()
initFromStream (line 573)

Initialize the native part of the object using an input stream.

This method reads markdown data from the passed stream and initializes the native discount data structure. It should be called in the constructor of subclasses; if not, it should at least be called before any of the MarkdownDocument methods be called. Alternatively, MarkdownDocument::initFromString() can be called instead.

boolean initFromStream (mixed $markdown_stream, [integer $flags = 0])
  • mixed $markdown_stream: Either a stream resource opened with reading permissions or a URL from which such a stream can be opened.
  • integer $flags: Data input type flags. Only the flags MarkdownDocument::NOHEADER and MarkdownDocument::TABSTOP are allowed.
initFromString (line 595)

Initialize the native part of the object using a string.

This method reads markdown data from the passed string and initializes the native discount data structure. It should be called in the constructor of subclasses; if not, it should at least be called before any of the MarkdownDocument methods be called. Alternatively, MarkdownDocument::initFromStream() can be called instead.

boolean initFromString (mixed $markdown_doc, [integer $flags = 0])
isCompiled (line 622)

Tells whether this document has already been compiled.

This method will return TRUE if MarkdownDocument::compile() has already been successfully called and FALSE otherwise.

boolean isCompiled ()
setAttributesCallback (line 907)

Sets a callback to add attributes to A elements in generated links.

The callback refers to a function that will receive one argument, a string with the URL that would be included with a generated link and returns either a string with the attributes and their values, to be appended to the generated A element or NULL, which has the same effect as an empty string and causes no extra attributes to be appended.

Links that were written as literal HTML in the input will not cause the callback to be called!

The object need not have been compiled before this function is called.

The actual URL conversion and calling of the callback happens when MarkdownDocument::getHtml() or MarkdownDocument::writeHtml() are called.

boolean setAttributesCallback (callback $callback)
  • callback $callback: Callback function to add attributes to links. Receives a string and should return either a string or NULL. This parameter can be NULL to remove the callback.
setReferencePrefix (line 931)

This function allows customizing the prefix used in footnote references.

More specifically, it changes the name attributes of the anchors from fn:N and fnref:N to {$prefix}:N and {$prefix}ref:N. This allows, for instance, for displaying several articles rendered individually in the same page without clashes in the footnote links.

This function can only be called if the document has not yet been compiled.

Usage of footnotes requires the MarkdownDocument::EXTRA_FOOTNOTE compile flag.

boolean setReferencePrefix (string $prefix)
  • string $prefix: The prefix to use.
setUrlCallback (line 877)

Sets a callback to replace the URLs in generated links.

The callback refers to a function that will receive one argument, a string with the URL that would be included with a generated link and returns either a replacement URL that will be used instead or NULL, to use the original URLs.

Links that were written as literal HTML in the input will not be passed to the callback!

The object need not have been compiled before this function is called.

The actual URL conversion and calling of the callback happens when MarkdownDocument::getHtml() or MarkdownDocument::writeHtml() are called.

boolean setUrlCallback (callback $callback)
  • callback $callback: Callback function to replace URLs. Receives a string and should return either a string or NULL. This parameter can be NULL to remove the callback.
writeCss (line 850)

Writes all the <style> elements found in the markdown document. These elements will not be included in the result returned by MarkdownDocument::getHtml() or written by MarkdownDocument::writeHtml().

This function returns an empty string if the flag MarkdownDocument::NOHTML was specified.

The markdown document must have already been compiled.

  • return: TRUE on normal conditions or FALSE and raises a warning if there was an I/O error when writing to the given stream (or to a successfully opened stream, if a URL was provided instead). The usual error handling described in the class synopsis also applies.
  • see: MarkdownDocument::getCss()
  • since: 0.1.0
  • access: public
boolean writeCss (mixed $markdown_outstream)
  • mixed $markdown_outstream: A stream resource where the style elements can be written or a URL that can be opened for writing.
writeHtml (line 753)

Writes the HTML contents of the body of the processed markup document.

This includes all the data present in the given markup with the exception of the pandoc-style headers and the style blocks. The unprocessed headers will, however, show up if MarkdownDocument::NOHEADER is given, and the escaped style blocks will show up if MarkdownDocument::NOHTML is given.

The document should already have been compiled.

If defined, this method calls the callbacks specified through MarkdownDocument::setUrlCallback() and MarkdownDocument::setAttributesCallback() for each link generated. If any of these callbacks throws an exception, this method throws another exception on top of it on the first time.

boolean writeHtml (mixed $markdown_outstream)
  • mixed $markdown_outstream: A resource stream opened with write permissions or a URL that can be opened to yield such a stream, for writing the output.
writeToc (line 827)

Writes the table of contents HTML data into a file.

This method must be called after the document has been compiled with MarkdownDocument::TOC.

  • return: TRUE if the table of contents was built and successfully written; FALSE if MarkdownDocument::TOC was not given or if writing failed, in the last case, a warning is also raised. The usual handling of the errror conditions described in the introduction to the MarkdownDocument class still apply.
  • see: MarkdownDocument::TOC
  • since: 0.1.0
  • access: public
boolean writeToc (mixed $markdown_outstream)
  • mixed $markdown_outstream: A stream resource where the HTML table of contents can be written or a URL that can be opened for writing.
writeXhtmlPage (line 777)

Writes a complete XHTML page.

The style blocks found in the markdown data are put in the HEAD element, the TITLE element is built from the title extracted from the pandoc-style header and the BODY is composed by what MarkdownDocument::writeHtml() would return.

The document should already have been compiled.

boolean writeXhtmlPage (mixed $markdown_outstream)
  • mixed $markdown_outstream: A resource stream opened with write permissions or a URL that can be opened to yield such a stream.
Class Constants
AUTOLINK = 16384 (line 306)

A compile flag that turns every found URL into a link.

In general, for a URL to linkified, it needs < and > around it. This flag drops that requirement and linkifies all the recognized URLs.

CDATA = 128 (line 187)

A compile flag that, for MarkdownDocument::writeFragment() and MarkdownDocument::writeHtml(), causes any <, >, &, " and ' characters in the final output to be converted to their corresponding XML entities.

EMBED = 35 (line 419)

A combination of the compile flags MarkdownDocument::NOLINKS, MarkdownDocument::NOIMAGE and MarkdownDocument::TAGTEXT.

Effectively, the same effect as MarkdownDocument::TAGTEXT.

It's unclear why discount includes this flag since the effects of MarkdownDocument::NOLINKS and MarkdownDocument::NOIMAGE are included in those of MarkdownDocument::TAGTEXT.

EXTRA_FOOTNOTE = 2097152 (line 432)

Compile flag that enables the use of PHP Markdown Extra-style footnotes.

NOALPHALIST = 524288 (line 386)

Compile flag that deactivates alphabetically ordered lists. These lists are a discount extension.

NODIVQUOTE = 262144 (line 375)

Compile flag that deactivates turning certain special block quotes into DIV elements with a certain class.

In discount, blockquotes whose first line has the form > %classname% will be transformed into a DIV element with the indicated class instead of a BLOCKQUOTE element. This is a discount extension that can be deactivated with this class.

NODLIST = 1048576 (line 400)

Compile flag that deactivates definition lists, either discount-style or Markdown-extra style.

NOHEADER = 65536 (line 345)

An input flag that deactivates parsing of pandoc-style headers.

Note that Markdown does not currently support multi-line headers.

NOHTML = 8 (line 118)

A compile flag that disables all literal HTML present in the input by encoding all the tags.

NOIMAGE = 2 (line 94)

A compile flag that disables processing the markdown elements that would otherwise create HTML images (like in ![alt text](http://www.example.com/myimg.jpg "title")); additionally, it escapes any IMG element it finds.

NOLINKS = 1 (line 82)

A compile flag that disables processing the markdown elements that would otherwise create HTML links (like in [text](http://www.example.com)); additionally, it escapes any A (anchor) element it finds.

NOPANTS = 4 (line 108)

A compile flag that deactivates smartypants substitutions such as turning (tm) into &trade;, don't into don&rsquo;t, among others (see the example).

NORELAXED = 512 (line 224)

A compile flag that forces discount to substitute with EM elements all the pairs of underscores it finds. In normal circumstances, discount will ignore underscores that are surrounded by alphanumeric characters.

For instance, this flag forces emphasis in c d for the input string ab_c d_2, which would otherwise not happen.

The "relaxed" parsing of underscores is a discount extension borrowed from Markdown extra; this flag forces compliant behavior.

NOSTRIKETHROUGH = 2048 (line 256)

A compile flag that deactivates the conversion of striken-through text, as in ~~text~~, to be converted to <del>text</del>.

This conversion is a discount extension.

The DEL element can still be introduced with literal HTML (but see MarkdownDocument::NOHTML).

NOSUPERSCRIPT = 256 (line 203)

A compile flag that deactivates the conversion of superscripts expressed with ^</kdb>, as in <kbd>A^B</kdd> or <kbd>A^(BC) (a discount extension).

SUP tags can still be included literally (but see MarkdownDocument::NOHTML).

NOTABLES = 1024 (line 240)

A compile flag that disables the parsing of tables. Tables are a discount extension borrowed by Markdown Extra.

Tables can still be written with literal HTML (but see MarkdownDocument::NOHTML).

NO_EXT = 64 (line 173)

A compile flag that disables the use of pseudo-protocols for links.

Pseudo-protocols are link protocols that result in HTML elements other than anchors being generated. They are a discount extension. See the example for more details.

ONE_COMPAT = 8192 (line 292)

A compile flag that applies some compatibility quirks in order to force discount passing some compatibility tests.

Particularly, it makes:

  1. the first line of every block has trailing whitespace trimmed off;
  2. require second [] for links/images instead of using label as key in the absence of it;
  3. more lax algorithm if content of []() link/image starts with <.

SAFELINK = 32768 (line 328)

A compile flag that limits generated links to certain protocols.

The allowed protocols are http, https, news and ftp. Links starting with /, but not relative links, are also allowed.

Pseudo-protocols are also deactivated, there is no need to include MarkdownDocument::NO_EXT.

Links with arbitrary destinations are still allowed with literal HTML, but see MarkdownDocument::NOHTML.

STRICT = 16 (line 139)

A compile flags that has the effects of approximating the behavior of discount to that of the original Markdown, by disabling several extensions.

In particular, it has the effect of combining MarkdownDocument::NOSUPERSCRIPT, MarkdownDocument::NORELAXED, MarkdownDocument::NOSTRIKETHROUGH, MarkdownDocument::NODLIST, MarkdownDocument::NOALPHALIST, MarkdownDocument::NODIVQUOTE and, MarkdownDocument::NOTABLES,

TABSTOP = 131072 (line 357)

An input flag to treat tab stops as 4 spaces � has no effect unless the extension was compiled with a different tab stop.

The default tab stop is 4 spaces, so this flag usually has no effect.

  • var: Input flag to force tab stops to be 4 spaces longs, even when discount was compiled otherwise.
  • since: 0.1.0
TAGTEXT = 32 (line 157)

A compile flag that aims to process attribute-safe fragments.

This flag disables [] expansion for images or links, (including literal HTML for them) smarty pants, ticks, autolink (even with MarkdownDocument::AUTOLINK), emphasis; it also transforms > into &gt; and " into &quote;. Its purpose is to transform text that could go into tag attributes. Best used with MarkdownDocument::transformFragment() or MarkdownDocument::writeFragment(), as many substitutions done by MarkdownDocument::compile() + MarkdownDocument::getHtml() are not covered.

TOC = 4096 (line 272)

A compile flag that forces a table of contents to be generated and the headings to have attributed an id.

The generated table of contents can then be retrieved with MarkdownDocument::getToc() or written with MarkdownDocument::writeToc().

Documentation generated on Wed, 25 Jan 2012 15:21:01 +0100 by phpDocumentor 1.4.4