PmWiki: CustomMarkup

Since a few people have asked, here's a brief summary of the $DoubleBrackets, $LinkPatterns, and $InlineReplacements arrays and how they work/interact. These arrays were designed to allow WikiAdministrators to create custom markups without having to modify pmwiki.php to achieve them. Here's a brief description of the variables:

$DoubleBrackets contains the substitutions to make before making Wiki Word, URL, and other "link" substitutions. It generally handles the conversions of things like "[[$Group]]", "[[$Title]]", "[[spacewikiwords]]", "[[$LastModified]]", etc., which is how it got its name.

$LinkPatterns specifies the rules for converting WikiWords, Free Links, URLs, Inter Map links, etc. into HTML.

$InlineReplacements specifies the substitutions to make after most of the other structural markup has been handled. These include things such as bold/italic text, character entitites, larger/smaller text, and horizontal rules.

The sequence Pm Wiki uses to convert wiki markup to HTML approximates something like the following:

  1. process any [[include:]] directives that may exist
  2. handle any substitutions in $BrowseDirectives
  3. replace HTML special characters (&, <, >) with entities (&amp; &lt; &gt;)
  4. save all text inside of [=...=] so it doesn't get processed
  5. process replacements listed in $DoubleBrackets
  6. convert sequences matching $LinkPatterns to HTML and save for step 8
  7. output "structural" HTML for paragraphs, tables, preformatted text, lists, headers, etc.
  8. convert replacements given in $InlineReplacements
  9. restore the HTML links produced from step 5
  10. process and apply Wiki Styles
  11. restore the things in [=...=] from step 2

Thus, $DoubleReplacements specifies translations to be performed before doing any processing of things held in the $LinkPatterns array, and $InlineReplacements specifies the conversions to be made to handle "inline" sorts of markup after $LinkPatterns and structural markup are done.

The entries in $DoubleBrackets are associative arrays; the keys (indexes) are replaced by their corresponding values. Thus

   $DoubleBrackets["[[Pm]]"] = "[[PatrickMichaud Pm]]";

will replace all occurrences of "[[Pm]]" in the markup with "[[PatrickMichaud Pm]]". This takes place before LinkPatterns are processed, so the text after substitution will be treated as if the user had entered it directly. Also, the values from $DoubleBrackets are processed using FmtPageName, so things like '$Group', '$Titlespaced', '$PageUrl', etc. are replaced with their appropriate values for the page being processed.

The entries in $InlineReplacements are associative arrays; the keys are regular expressions to be matched, and the values are the replacement strings (via PHP's preg_replace function).
    #### superscripts via ^^text^^, subscripts via __text__
    $InlineReplacements['/\\^\\^(.*?)\\^\\^/'] = "<sup>\$1</sup>";
    $InlineReplacements['/__(.*?)__/'] = "<sub>\$1</sub>";

    #### a simple smiley to gif conversion
    $InlineReplacements['/:-)/'] = 
     '<img src="" alt=":-)">';

Note that the $InlineReplacement keys must include regular expression delimiters (normally slashes). Also note that the smiley example could not have been done using $DoubleBrackets because the src="http://..." would've been picked up and modified by the $LinkPatterns.

The $DoubleBrackets array will also perform a regular expression search/replace (via preg_replace) for any keys that begin with a slash.

Finally, $LinkPatterns works a bit like $DoubleBrackets and $InlineReplacements, but is more complex because of the variety of replacements to be performed and the fact that order is very significant. The first index of $LinkPatterns entries specifies the sequence in which to process the patterns, the second index specifies the regular expression pattern to match, and the value of the entry specifies either the replacement string or the name of a function to be called to provide the replacement string. Thus:
    $LinkPatterns[200]["\\bmailto:($UrlPathPattern)"] = 
      "<a href='$0'>$1</a>";

says to replace the markup text like "mailto:[email protected]" with "<a href='mailto:[email protected]'>[email protected]</a>", and to do this after $LinkPatterns numbered less than 200 but before $LinkPatterns numbered higher than 200. The statement
      = 'FmtAttachLink';

says to replace Attach: markup by calling the FmtAttachLink function.

The standard sequence of replacements in a PmWiki distribution are currently:
    100   ThisWiki:, ThisGroup:, ThisPage: links (from thiswiki.php)
    120   Attach: links (from upload.php)
    200   mailto: links
    300   http:, ftp:, gopher:, etc. links
    400   InterMap links
    500   Group/{{free links}}  and Group.{{free links}}
    600   {{free links}}
    700   Group/WikiWords  and Group.WikiWords
    800   WikiWords

Note that unlike $InlineReplacements, the regexps in $LinkPatterns cannot include the regular expression delimiters.

Anyway, hopefully this sheds a little light on the role that these arrays play in PmWiki's markup to HTML conversion for those who are wanting to add their own customized markups. Of course, if anyone has any questions, feel free to write me or the listserv.

<< Custom Free Links | PmWiki.Documentation Index | Available Actions >>
Retrieved from
Page last modified on March 03, 2004, at 08:03 PM