Uploaded image for project: 'XWiki Rendering'
  1. XWiki Rendering
  2. XRENDERING-297

Add Markdown Syntax 1.1 with macros, superscript and subscript support

    Details

    • Tests:
      Integration
    • Pull Request Status:
      Awaiting Committer feedback
    • Similar issues:

      Description

      Markdown syntax in XWiki supports only the features provided by PegDown parser, it lacks support for macros etc. Therefore it cannot be used as a full replacement of XWiki 2.x syntax.

      I like Markdown a lot, this was actually one of the reasons why I’ve chosen XWiki. Although it’s limited, it was very simple to extend it, thanks to its awesomely clean and modular architecture!

      So I’ve implemented support for block and inline macros (the most important) and also superscript and subscript formatting for now. PegDown is extensible since version 1.4.0, so the extra parser is implemented as a PegDown plugin.

      Block macro

      Same as in XWiki:

      {{mymacro par1="foo"}}
        content
      {{/mymacro}}
      

      Inline macro

      I can’t find any Markdown dialect with macros so I’ve come with my own, derived from the image and link syntax. It’s quite intuitive and simple.

      • #[mymacro](par1="foo" par2=42 "any content") – macro with parameters and content
      • #[mymacro]("any content (quoted)") or #[mymacro](any content) – macro without parameters
      • #[mymacro] – macro without parameters and content

      Superscript and subscript

      This is common feature in many Markdown dialects (Pandoc, Multimarkdown, …)

      This is ^superscript^, but ^this not^, you have to ^escape\ spaces^. 
      Subscripts are similar, just use ~tilda~ instead. Do you want some H~2~O?
      

      Inline (X)HTML

      Markdown supports an inline HTML so you can write e. g. Hello <del>there</del> and these tags are interpreted as HTML. The problem is that the Pegdown parser is too lenient, it allows any number of whitespaces and even optional new line inside a HTML tag. Therefore it’s very hard to properly escape < and > characters to not be confused with a HTML.

      I’ve replaced parsing rules for an inline HTML in the Pegdown with rules for an inline XML. The XML syntax is more strict and so more suitable for an inline (X)HTML in the Markdown syntax. One can still write Hello <del>there</del> and it’s parsed as (X)HTML, but something like a < b > c is not. It’s more predicable and much simpler to properly escape special characters.


      Here’s my pull request: https://github.com/xwiki/xwiki-rendering/pull/5

        Attachments

          Activity

            People

            • Assignee:
              vmassol Vincent Massol
              Reporter:
              jirutka Jakub Jirutka
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:
                Date of First Response: