Markdown
From MODx Wiki
Contents |
About Markdown
By its author, John Gruber, 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).
Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
PHP Markdown & Extra
PHP Markdown, by Michel Fortin, is a port to PHP of the original Markdown. PHP Markdown Extra is a special version of PHP Markdown implementing some features currently not available with the plain Markdown syntax, namely:
- Inline HTML
- Markdown Inside HTML Blocks
- Header Id Attribute
- Tables
- Definition Lists
- Footnotes
- Abbreviations
- Emphasis
- Backslash Escapes
Markdown syntax
- Full documentation of Markdown's syntax is available on John's Markdown page: http://daringfireball.net/projects/markdown/
- Full documentation of PHP Markdown's Extra syntax is available on Michel's page: http://www.michelf.com/projects/php-markdown/extra/
- You can test Markdown syntax online using Michel's PHP Markdown Dingus.
PHP Markdown plugin
PHP Markdown plugin allows you to use Markdown syntax in MODx documents. It requires PHP Markdown & Extra script. It will also work with PHP SmartyPants & Typographer.
The plugin is based on Textile plugin by Raymond Irving.
Download
- You can download PHP Markdown plugin from MODx repository.
- You can download PHP Markdown & Extra parser from PHP Markdown home page.
Support
You can post any comments about this plugin or any questions you have regarding its use on Support/Comments for PHP Markdown plugin topic on MODx forums.
Installation
- In the MODx manager, go to Resources > Plugins and create a new plugin. Name it "Markdown". Copy the contents of Markdown.tpl.php into it. Switch to "System Events" tab and check "OnWebPagePrerenderer" event. Save the plugin.
- Download the latest PHP Markdown Extra and put the contents into the folder /assets/plugins/markdown. Make sure that at least markdown.php is there. It contains the parser code.
Using the plugin
To make the plugin parse text and convert it to HTML you have to place it inside markdown tags as shown below:
<markdown>text to be parsed</markdown>
You may put the tags into the document content field, a chunk or a template.
Configuration
Path to Markdown parser
Path to the Markdown parser can be set in the plugin code. To change the default path edit the line shown below:
$mdStrMarkdownPath = 'assets/plugins/markdown/markdown.php';
Path to SmartyPants parser
To enable use of PHP SmartyPants, the path to the SmartyPants parser should point to the existing file. If the target file doesn't exist it will be ignored.
$mdStrSmartyPantsPath = 'assets/plugins/smartypants/smartypants.php';
Changing the markdown tags
If for any reason you need to change the default markdown tag, edit the plugin and modify the code shown below:
preg_match_all( "|<markdown>(.*)</markdown>|Uis", $mdStrDocOutput, $mdArrParseBlocks );
Replace markdown with your custom tag name.
Changing the tag matching
By default the matching pattern is ungreedy, which means the plugin will match the narrowest selection it can find. To change the plugin matching to greedy, that is, to match the widest tag pair, modify the plugin code by removing the U modifier from the matching pattern:
preg_match_all( "|<markdown>(.*)</markdown>|is", $mdStrDocOutput, $mdArrParseBlocks );
