Version 1.0.1m - Sat 21 Jun 2008
by Michel Fortin http://michelf.com/
based on work by John Gruber http://daringfireball.net/
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
"Markdown" is two things: a plain text markup syntax, and a software tool, written in Perl, that converts the plain text markup to HTML. PHP Markdown is a port to PHP of the original Markdown program by John Gruber.
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.
Full documentation of Markdown's syntax is available on John's Markdown page: http://daringfireball.net/projects/markdown/
Installation and Requirement
PHP Markdown requires PHP version 4.0.5 or later.
PHP Markdown works with WordPress, version 1.2 or later.
To use PHP Markdown with WordPress, place the "makrdown.php" file in the "plugins" folder. This folder is located inside "wp-content" at the root of your site:
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.
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.
It is not possible at this time to apply a different set of filters to different entries. All your entries will be formated by PHP Markdown. This is a limitation of WordPress. If your old entries are written in HTML (as opposed to another formatting syntax, like Textile), they'll probably stay fine after installing Markdown.
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:
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.
Rename the "markdown.php" file to "classTextile.php". This will make PHP Markdown behave as if it was the actual Textile parser.
Replace the "classTextile.php" file TextPattern installed in your web directory. It can be found in the "lib" directory:
Contrary to Textile, Markdown does not convert quotes to curly ones
and does not convert multiple hyphens (
---) 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 SmartyPants beside the "classTextile.php" file. The Textile
Compatibility Mode function will use SmartyPants automatically without
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 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|
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.
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));
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
(MT CGI root)/php/extlib/smarty/plugins. This will allow
Markdown to work on dynamic pages.
By default, PHP Markdown produces XHTML output for tags with empty elements. E.g.:
Markdown can be configured to produce HTML-style tags; e.g.:
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.