Extension:MarkdownSyntax

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
MarkdownSyntax

Release status: unmaintained

Implementation Extended syntax
Description Adds support for markdown syntax.
Author(s) Simon Dorfman (SimonDorfmantalk)
Latest version 0.2
MediaWiki 1.10.0
Database changes No
License The MIT License
Download See the code section

Translate the MarkdownSyntax extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

The MarkdownSyntax 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[edit | edit source]

For previous version of PHP Markdown to 1.4.1[edit | edit source]

  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" );
    

For PHP Markdown version 1.4.1+[edit | edit source]

  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 the php files into your new MarkdownSyntax dir.
    Note: Don't download PHP Markdown Extra. Only PHP Markdown is supported. PHP Markdown Extra may be supported in a future release
  3. Copy the MarkdownSyntax.php source below and save it as MarkdownSyntax.php.
  4. Change this line:
    require_once("markdown.php");
    
  5. to this:
    require_once('Markdown.inc.php');
    
  6. Change this line:
    $text = Markdown($text);
    
  7. to this
    $text = Michelf\Markdown::defaultTransform($text);
    
  8. Drop it into $IP/extensions/MarkdownSyntax/ also.
  9. Enable the extension by adding this line to your LocalSettings.php:
    require_once( "$IP/extensions/MarkdownSyntax/MarkdownSyntax.php" );
    

Developer notes[edit | edit source]

  • 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[edit | edit source]

  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[edit | edit source]

  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[edit | edit source]

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

Todo List[edit | edit source]

  • Create a Mediawiki toolbar replacement with Markdown versions of the existing commands. Show how to add it.
  • Try PHP Markdown Extra and see if it's features work.

See also[edit | edit source]

Code[edit | edit source]

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'=>'https://www.mediawiki.org/wiki/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;
}