Migration from Misaka to Mistune

Introduction

Misaka was the rendering engine for converting Markdown to HTML in previous versions of Isso. It is being replaced by Mistune. The Markdown syntax and options between these engines is differing and this is to document the differences.

See Server Configuration how to set Mistune as the new rendering engine.

For Misaka, plugins are configured with the options setting. Misaka actually refers to plugins as extensions. The options setting must be in section [markup.misaka] in the server configuration file isso.cfg.

For Mistune, plugins are configured with the plugins setting. The plugins setting must be in section [markup.mistune] in the server configuration file isso.cfg.

Syntax differences

HTML elements

Misaka allows HTML expressions like <em>Hi</em> in Markdown. This expression will be rendered to HTML as is: <em>Hi</em>. Mistune takes a stricter approach and replaces any HTML element with rendered text like this: &lt;em&gt;Hi&lt;/em&gt;.

Strong and emphasis

Misaka interprets asterisks like this:

  1. **word**: Strong word

  2. *word*: Emphasized word

  3. **word1***word2*: Strong word1 and emphasized word2

Mistune is the same on the first two points but does not interpret asterisks inside words:

  1. **word1***word2*: Renders as **word1***word2*

If you want to have the same rendered result with Mistune, use underscores for emphasis:

  1. **word1**_word2_: Strong word1 and emphasized word2

Fenced code

In Misaka, fenced code can be marked by enclosing the code block in three backticks ``` or by putting four space characters in front of each code line. Mistune only understands three backticks.

Plugins

Fenced-code

Mistune always renders fenced code. The behavior is not configurable and no fenced-code plugin exists for Mistune.

Superscript

This plugin exists in both engines with the same name superscript. The Markdown syntax is different however.

Misaka: ^(superscripted_text)

Mistune: ^superscripted_text^