php Markdown

Introduction

PHP Markdown is a port to PHP of the Markdown program written by John Gruber.

“Markdown” is two things: a plain text markup syntax, and a software tool that converts the plain text markup to HTML for publishing on the web.

The Markdown syntax allows you to write text naturally and format it without using HTML tags. More importantly: in Markdown format, your text stays enjoyable to read for a human being, and this is true enough that it makes a Markdown document publishable as-is, as plain text. If you are using text-formatted email, you already know some part of the syntax.

Visit the Concepts page for a short introduction full of examples where you will learn to write with Markdown. If you have some understanding of HTML, you can also read the full documentation of Markdown’s syntax, available on John’s web site.

PHP Markdown can work as a plug-in for WordPress and bBlog, as a modifier for the Smarty templating engine, or as a remplacement for textile formatting in any software that support textile.

Download

PHP Markdown 1.0.1o (25 Kb)

Latest version of PHP Markdown, released on January 8, 2012.

PHP Markdown Extra 1.2.5 (34 Kb)

A special version of PHP Markdown with extra features. See the PHP Markdown Extra description. Released on January 8, 2012.

Participate to the development of this project on Github. PHP Markdown and PHP Markdown Extra are also available as PEAR packages.

Installation and Requirement

PHP Markdown requires PHP version 4.0.5 or later.

WORDPRESS

PHP Markdown works with WordPress, version 1.2 or later.

1. To use PHP Markdown with WordPress, place the “markdown.php” file in the “plugins” folder. This folder is located inside “wp-content” at the root of your site:

   (site home)/wp-content/plugins/
   

2. Activate the plugin with the administrative interface of WordPress. In the “Plugins” section you will now find Markdown. To activate the plugin, click on the “Activate” button on the same line than Markdown. Your entries will now be formatted by PHP Markdown.

3. To post Markdown content, you’ll first have to disable the “visual” editor in the User section of WordPress.

You can configure PHP Markdown to not apply to the comments on your WordPress weblog. See the “Configuration” section below.

BBLOG

PHP Markdown also works with bBlog.

To use PHP Markdown with bBlog, rename “markdown.php” to “modifier.markdown.php” and place the file in the “bBlog_plugins” folder. This folder is located inside the “bblog” directory of your site, like this:

    (site home)/bblog/bBlog_plugins/modifier.markdown.php

Select “Markdown” as the “Entry Modifier” when you post a new entry. This setting will only apply to the entry you are editing.

REPLACING TEXTILE IN TEXTPATTERN

TextPattern use Textile to format your text. You can replace Textile by Markdown in TextPattern without having to change any code by using the Texitle Compatibility Mode. This may work with other software that expect Textile too.

1. Rename the “markdown.php” file to “classTextile.php”. This will make PHP Markdown behave as if it was the actual Textile parser.

2. Replace the “classTextile.php” file TextPattern installed in your web directory. It can be found in the “lib” directory:

   (site home)/textpattern/lib/
   

Contrary to Textile, Markdown does not convert quotes to curly ones and does not convert multiple hyphens (-- and ---) into en- and em-dashes. If you use PHP Markdown in Textile Compatibility Mode, you can solve this problem by installing the “smartypants.php” file from PHP SmartyPantsbeside the “classTextile.php” file. The Textile Compatibility Mode function will use SmartyPants automatically without further modification.

IN YOUR OWN PROGRAMS

You can use PHP Markdown easily in your current PHP program. Simply include the file and then call the Markdown function on the text you want to convert:

include_once "markdown.php";
$my_html = Markdown($my_text);

If you wish to use PHP Markdown with another text filter function built to parse HTML, you should filter the text after the Markdown function call. This is an example with PHP SmartyPants:

$my_html = SmartyPants(Markdown($my_text));

WITH SMARTY

If your program use the Smarty template engine, PHP Markdown can now be used as a modifier for your templates. Rename “markdown.php” to “modifier.markdown.php” and put it in your smarty plugins folder.

If you are using MovableType 3.1 or later, the Smarty plugin folder is located at (MT CGI root)/php/extlib/smarty/plugins. This will allow Markdown to work on dynamic pages.

Configuration

By default, PHP Markdown produces XHTML output for tags with empty elements. E.g.:

<br />

Markdown can be configured to produce HTML-style tags; e.g.:

<br>

To do this, you must edit the “MARKDOWN_EMPTY_ELEMENT_SUFFIX” definition below the “Global default settings” header at the start of the “markdown.php” file.

WORDPRESS-SPECIFIC SETTINGS

By default, the Markdown plugin applies to both posts and comments on your WordPress weblog. To deactivate one or the other, edit the MARKDOWN_WP_POSTS or MARKDOWN_WP_COMMENTS definitions under the “WordPress settings” header at the start of the “markdown.php” file.

UPDATING MARKDOWN IN OTHER PROGRAMS

Many web applications now ship with PHP Markdown, or have plugins to perform the conversion to HTML. You can update PHP Markdown — or replace it with PHP Markdown Extra — in many of these programs by swapping the old “markdown.php” file for the new one.

Here is a short non-exhaustive list of some programs and where they hide the “markdown.php” file.

PROGRAM	PATH TO MARKDOWN
Pivot	(site home)/pivot/includes/markdown/

If you’re unsure if you can do this with your application, ask the developer, or wait for the developer to update his application or plugin with the new version of PHP Markdown.

Bugs

To file bug reports please send email to: michel.fortin@michelf.com

Please include with your report: (1) the example input; (2) the output you expected; (3) the output PHP Markdown actually produced.