Extension:MarkdownSyntax

MediaWiki extensions manual - list

MarkdownSyntax Release status: beta
Implementation	Extended syntax
Description	Adds support for markdown syntax.
Author(s)	Simon Dorfman
Last version	0.2
MediaWiki	1.10.0
License	The MIT License
Download	Extension:MarkdownSyntax
Check usage and version matrix

MarkdownSyntax is a MediaWiki extension that enables markdown syntax. 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).

Installation

1. Create a folder in your $IP/extensions directory called MarkdownSyntax.

   Note: $IP is your MediaWiki install dir.

   You have something like this: $IP/extensions/MarkdownSyntax/

2. Download Michel Fortin's PHP Markdown, unzip and look for the file markdown.php.

   Note: Don't download PHP Markdown Extra. Only PHP Markdown is supported. PHP Markdown Extra may be supported in a future release

3. Drop markdown.php into $IP/extensions/MarkdownSyntax/
4. Copy the MarkdownSyntax.php source below and save it as MarkdownSyntax.php. Drop it into $IP/extensions/MarkdownSyntax/ also.
5. Enable the extension by adding this line to your LocalSettings.php:

   require_once( "$IP/extensions/MarkdownSyntax/MarkdownSyntax.php" );
   

Developer notes

• Thanks to Ian Smith for his suggestion to use UsenetSyntax as a model for this extension. Thanks to Jim R. Wilson (Jimbojw) for writing UsenetSyntax.
• Thanks to Thomas Peri (via New Orleans 2600) for tons of help with v0.2, especially writing the parsing URLs and converting them to MediaWiki URLs.

Limitations

1. Markdown links: Link titles are not supported because MediaWiki links don't support them.

   i.e.

   [an example](http://example.com/ "Title")
   

   becomes

   <a href="http://example.com/">an example</a>
   

   , not

   <a href="http://example.com/" title="Title">an example</a>
   

   .

Bugs

1. Markdown's code blocks and spans are a little buggy
   1. Huy: There's an easy fix for the code block problem: edit markdown.php and change

      <pre><code>
      

      to

      <code><pre>
      

      and do the same for the closing tags on that line.
2. The edit links to the right of each heading aren't working for some reason. They return a page like this:

   No such section: You tried to edit a section that doesn't exist. Since there is no section 3, there's no place to save your edit.
   

3. Wikilinks to a title on the same page work, but they render the # symbol at the beginning of the link.
4. Help:Magic words (like __NOTOC) are rendered as bold text and their behaviour is disabled
5. standard Wikitext is disabled totally (would it be possible to use the non-colliding ones?)
6. some <p> around the title tag
   1. Huy: Here's how I fixed that: I added the code to the end of wfProcessMarkdownSyntax before the return statement

       // To fix the <p> in the title problem, detect if the text consists only of a single
       // paragraph and remove the tags
       $multi_par_pattern = "/^<p>.*<p>/i";
       $par_pattern = "/^<p>(.*)<\/p>\n?$/i";
       if (! preg_match($multi_par_pattern, $text)) {
           $text = preg_replace($par_pattern, '$1', $text);
       }

More Testing Needed

• Does anyone know how these Markdown tests (written in perl) could be executed somehow on a MediaWiki with this extension installed?

Todo List

• Create a Mediawiki toolbar replacement with Markdown versions of the existing commands. Show how to add it.
  • Consider using Control.TextArea. It can format in Markdown syntax.
• Try PHP Markdown Extra and see if it's features work.

MarkdownSyntax.php

<?php
/*
 * MarkdownSyntax.php - A MediaWiki extension which adds support for Markdown syntax.
 * @author Simon Dorfman (Thomas Peri (http://www.tumuski.com) pretty much figured this whole thing out!)
 * @version 0.2
 * @copyright Copyright (C) 2007 Simon Dorfman
 * @license The MIT License - http://www.opensource.org/licenses/mit-license.php 
 * @addtogroup Extensions
 * -----------------------------------------------------------------------
 * Description:
 *     This is a MediaWiki (http://www.mediawiki.org/) extension which adds support
 *     for Markdown syntax.
 * Requirements:
 *     This extension was written and tested with MediaWiki 1.10.0.
 *     It depends upon PHP Markdown:
 *         http://www.michelf.com/projects/php-markdown/ (version 1.0.1f)
 * Installation:
 *     1. Create a folder in your $IP/extensions directory called MarkdownSyntax.
 *         Note: $IP is your MediaWiki install dir.
 *         You have something like this: $IP/extensions/MarkdownSyntax/
 *     2. Download Michel Fortin's PHP Markdown, unzip and look for the file markdown.php.
 *         Note: Don't download PHP Markdown Extra. Only PHP Markdown is supported. PHP Markdown Extra may be supported in a future release
 *     3. Drop markdown.php into $IP/extensions/MarkdownSyntax/
 *     4. Download MarkdownSyntax.php and drop it into $IP/extensions/MarkdownSyntax/ also.
 *     5. Enable the extension by adding this line to your LocalSettings.php:
 *            require_once( "{$IP}/extensions/MarkdownSyntax.php" );
 * Usage:
 *     See http://daringfireball.net/projects/markdown/syntax
 * Version Notes:
 *     version 0.2:
 *         Switched to ParserBeforeStrip hook.
 *         Hacked html links produced by markdown.php into mediawiki links.
 *     version 0.1:
 *         Initial release.
 * -----------------------------------------------------------------------
 * Copyright (c) 2007 Simon Dorfman
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy 
 * of this software and associated documentation files (the "Software"), to deal 
 * in the Software without restriction, including without limitation the rights to 
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
 * the Software, and to permit persons to whom the Software is furnished to do 
 * so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all 
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
 * OTHER DEALINGS IN THE SOFTWARE. 
 * -----------------------------------------------------------------------
 */
 
# Confirm MediaWiki environment
if (!defined('MEDIAWIKI')) die();
 
# Credits
$wgExtensionCredits['other'][] = array(
    'name'=>'MarkdownSyntax',
    'author'=>'Simon Dorfman &lt;simon@yamlike.com&gt;',
    'url'=>'[[Extension:MarkdownSyntax]]',
    'description'=>'Adds support for markdown syntax.',
    'version'=>'0.2'
);
 
# Attach Hook
$wgHooks['ParserBeforeStrip'][] = 'wfProcessMarkdownSyntax';
 
/**
 * Processes any Markdown sytnax in the text.
 * Usage: $wgHooks['ParserBeforeStrip'][] = 'wfProcessMarkdownSyntax';
 * @param Parser $parser Handle to the Parser object currently processing text.
 * @param String $text The text being processed.
 */
 
# includes Michel Fortin's PHP Markdown: http://www.michelf.com/projects/php-markdown/
require_once("markdown.php");
#require_once( dirname( __FILE__ ) . '/markdown.php' );

function wfProcessMarkdownSyntax($parser, $text) {
 
    # Perform Markdown syntax processing on provided $text from markdown.php line 43 function
        $text = Markdown($text);
        // <a href="http://example.com/" title="Title">an example</a>
 
        /* After running the text through this parser, mediawiki converts <a> tags to &lt...
                So, here we convert such links to mediawiki format links so they will be properly rendered. */
 
        /*
                pattern: <a href="(.+?)"( title="(.+?)")?>(.+?)</a>
                escaped quotes and slash: <a href=\"(.+?)\"( title=\"(.+?)\")?>(.+?)<\/a>
                regexed and quoted: "/<a href=\"(.+?)\"( title=\"(.+?)\")?>(.+?)<\/a>/i"
                split php end tag: "/<a href=\"(.+?)\"( title=\"(.+?)\")?".">(.+?)<\/a>/i"
        */
        $pattern = "/<a href=\"(.+?)\"( title=\"(.+?)\")?".">(.+?)<\/a>/i";
        $replacement = '[$1 $4]';
 
        $text = preg_replace($pattern, $replacement, $text);
        return true;
}