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.

Configure the Parser
Markdown Configuration
Markdown Extra Configuration
Differences with classic version

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.

hard_wrap = false

Setting this to true will change line breaks into <br /> when the context allows it. When set to false, following the standard Markdown syntax these newlines are ignored unless they a preceded by two spaces.

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 <) from being passed verbatim in the output as it is the standard with Markdown. Instead, the HTML output will be &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 strtolower($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 ($text) {
    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>.

code_span_content_func = null

The content of code code spans 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_span_content_func = function ($code) {
    return htmlspecialchars($code);
};

A more advanced version could infer the language of the code and perform syntax coloring. The result returned by this function is automatically wrapped in a <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.

For backlinks, the title is also used as an accessibility label with the aria-label attribute.

Occurances of “^^” in the string will be replaced by the corresponding footnote number in the HTML output. Occurances of “%%” will be replaced by a number for the reference (footnotes can have multiple references).

fn_link_class = "footnote-ref"

fn_backlink_class = "footnote-backref"

The class attribute to use for footnotes links and backlinks.

fn_backlink_label = ""

Add an accessibility label for backlinks (the aria-label attribute), when you want it to be different from the title attribute.

fn_backlink_html = "↩︎"

HTML content for a footnote backlink. The ︎ 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.

omit_footnotes = false

When true, footnotes are not appended at the end of the generated HTML and the footnotes_assembled variable will contain the HTML for the footnote list, allowing footnotes to be moved somewhere else on the page.

Note: when placing the content of footnotes_assembled on the page, consider adding the attribute role="doc-endnotes" to the <div> or <section> that will enclose the list of footnotes so they are reachable to accessibility tools the same way they would be with the default HTML output.

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.

hashtag_protection = false

When set to true, prevents ATX-style headers with no space after the initial hash from being interpreted as headers. This way your precious hashtags are preserved.

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.