Extension:MarkdownSyntax

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

Release status:Extension status unmaintained

ImplementationTemplate:Extension#type Extended syntax
DescriptionTemplate:Extension#description Adds support for markdown syntax.
Author(s)Template:Extension#username Simon Dorfman (SimonDorfmantalk)
Latest versionTemplate:Extension#version 0.2
MediaWikiTemplate:Extension#mediawiki 1.10.0
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license MIT License
Download See the code section

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

Check usage and version matrix.

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]

For previous version of PHP Markdown to 1.4.1[edit]

  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]

  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 "Michelf/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]

  • 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]

  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]

  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. Daniel: Underscores in links need to be escaped with a backslash (`\`), e.g.
    [https://de.wikipedia.org/wiki/Linus\_Torvalds Linus Torvalds]
    
  5. Help:Magic words (like __NOTOC) are rendered as bold text and their behaviour is disabled
  6. standard Wikitext is disabled totally (would it be possible to use the non-colliding ones?)
  7. Daniel: Tables don't work with this extension, neither in Markdown nor MediaWiki syntax. Otherwise you could use this nice generator. Solution: write in HTML. If you want them to be pretty, add CSS:
    <table class="wikitable">...</table>
    
  8. 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]

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

Todo List[edit]

  • 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]

Code[edit]

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;
}