PHP Markdown: Configuration

PHP Markdown Lib includes two parsers: Markdown and MarkdownExtra. This is a list of the settings that can be can tweaked on each of them.

Note: these configuration options apply to PHP Markdown Lib. Options for the classic version can differ slightly. For the classic version, classes are named Markdown_Parser and MarkdownExtra_Parser.


Configure the Parser

Most of the time, the default configuration should be good enough. In those times you can just call the defaultTransform function on the parser class:

use \Michelf\Markdown;
$html = Markdown::defaultTransform($text);

If you need some things to be different, instantiate your own parser and set a few variables:

use \Michelf\Markdown;
$parser = new Markdown;
$parser->empty_element_suffix = ">";
$html = $parser->transform($text);

Configuration variables on the MarkdownExtra parser work the same way.

Markdown Configuration

empty_element_suffix = " />"

This is the string used to close tags for HTML elements with no content such as <br> and <hr>. The default value creates XML-style empty element tags which are also valid in HTML 5.

tab_width = 4

This is the width of a tab character on input. Changing this will affect how many spaces a tab character represents.

Note: Keep in mind that when the Markdown syntax spec says “four spaces or one tab”, it actually means “four spaces after tabs are expanded to spaces”. So setting tab_width to 8 will make the parser treat a tab character as two levels of indentation.

no_markup = false

Setting this variable to true will prevent HTML tags in the input from being passed to the output.

Important: This is not a protection against malicious javascript being injected in a document. See why in Markdown and XSS.

no_entities = false

Setting this variable to true will prevent HTML entities (such as &lt;) from being passed verbatim in the output as it is the standard with Markdown. Instead, the HTML output will be &amp;tl; and once shown in shown the browser it will match perfectly what was written.

predef_urls = array()

You can predefine reference links by setting predef_urls to a list of urls where the key is the name of the reference. For instance:

$parser->predef_urls = array('ref' => 'https://michelf.ca/');

will make this Markdown input to create a link:

This is [my website][ref].
predef_titles = array()

Use predef_titles to set the title of the link references passed in predef_urls. As for predef_urls, the key is the reference name.

url_filter_func = null

This variable makes it possible to transform URLs for links and images in the document by specifying a function:

$parser->url_filter_func = function ($url) {
    return tolower($url);
};

This can be used to fix unsecure URLs, transform local URLs into complete ones, etc.

header_id_func = null

Headers can have their id attribute auto-generated by setting this configuration variable to a function:

$parser->header_id_func = function ($header) {
    return preg_replace('/[^a-z0-9]/', '-', strtolower($text));
};
code_block_content_func = null

The content of code blocks can be transformed to HTML with a custom function. A simple version of this function will only change the special characters to HTML entities:

$parser->code_block_content_func = function ($code, $language) {
    return htmlspecialchars($code);
};

A more advanced version could use the $language parameter and perform syntax coloring. The result returned by this function is automatically wrapped in a <pre><code>.

enhanced_ordered_list = false

Setting this to true allows ordered list to start with a number different from 1.

(Note: this is set to true by default for Markdown Extra.)

Markdown Extra Configuration

In addition to all the configuration variables in the Markdown parser, the MarkdownExtra parser has the following extra settings.

fn_id_prefix = ""

A prefix for the id attributes generated by footnotes. This is useful if you have multiple Markdown documents displayed inside one HTML document to avoid footnote ids to clash each other.

fn_link_title = ""
fn_backlink_title = ""

An optional title attribute for footnotes links and backlinks. Browsers usually show this as a tooltip when the mouse is over the link.

fn_link_class = "footnote-ref"
fn_backlink_class = "footnote-backref"

The class attribute to use for footnotes links and backlinks.

fn_backlink_html = "&#8617;&#xFE0E;"

HTML content for a footnote backlink. The &#xFE0E; suffix in the default value is there to avoid the curled arrow being rendered as an emoji on mobile devices, but it might cause an unrecognized character to appear on older browsers.

code_class_prefix = ""

An optional prefix for the class names associated with fenced code blocks. This will be prepended to the class name if you write your fenced code block this way:

~~~~ .html
<br>
~~~~

Note however that it has no effect if you add a class name using the more generic extra syntax that uses braces:

~~~~ {.html .flashy}
<br>
~~~~
code_attr_on_pre = false

When set to false (the default), attributes for code blocks will go on the <code> tag; setting this to true will put attributes on the <pre> tag instead.

table_align_class_tmpl = ""

Value for the class attribute determining the alignment of table cells. The default value, which is empty, will cause the align attribute to be used instead of class to specify the alignment.

If not empty, the align attribute will not appear. Instead, the value for the class attribute will be determined by replacing any occurance of %% within the string by left, center, or right. For instance, if the configuration variable is "go-%%" and the cell is right-aligned, the result will be: class="go-right".

predef_abbr = array()

You can predefine abbreviations by setting predef_abbr to a list of abbreviations where the key is the text of the abbreviation and the value is the expanded name.

Differences with classic version

Configuration options for the classic version are mostly the same as those of PHP Markdown Lib described above. Still, here are some notable differences:

For the classic version, classes are named Markdown_Parser and MarkdownExtra_Parser, with no namespace.

The defaultTransform function does not exist. Instead a global Markdown function is available and uses either Markdown_Parser or MarkdownExtra_Parser depending on which file you download. The parser class used by the Markdown function can changed by defining the MARKDOWN_PARSER_CLASS constant prior including the file.

Default options are defined in similar constants, which can also be defined prior including the file to set the defaults.

In the classic version, a rel="footnote" attribute is added on links to footnotes, and a rev="footnote" on the backlinks. In the default configuration there is no class attribute. The Lib version replaces rel and rev with the class attribute defined earlier in this document.


  • © 2003–2017 Michel Fortin.