Flask-Misaka

Flask-Misaka provides a pleasant interface between the Flask web framework and the Misaka Markdown parser. [1]

Installation

Install the extension with:

$ pip install Flask-Misaka

Usage

Just import the markdown() function and use it!

>>> from flask.ext.misaka import markdown
>>> markdown("A *simple* example.")
Markup(u'<p>A <em>simple</em> example.</p>\n')

To use Markdown in your templates, you just need to import the Misaka class and wrap your Flask instance with it:

from flask import Flask
from flask.ext.misaka import Misaka

app = Flask(__name__)
Misaka(app)

or use the application factory pattern:

md = Misaka()
app = Flask(__name__)
md.init_app(app)

And then the markdown filter will be available in your Jinja2 templates. You can pass variables in your template through it:

{{ text|markdown }}

Or, you can use the filter tag to write your template directly in Markdown and have Jinja dynamically interpret it for you!

{% filter markdown %}
I'm writing my templates in *Markdown!*
{% endfilter %}

API

flask.ext.misaka.markdown(text, renderer=None, **options)

Parses the provided Markdown-formatted text into valid HTML, and returns it as a flask.Markup instance.

Parameters:
  • text – Markdown-formatted text to be rendered into HTML
  • renderer – A custom misaka renderer to be used instead of the default one
  • options – Additional options for customizing the default renderer
Returns:

A flask.Markup instance representing the rendered text

class flask.ext.misaka.Misaka(app=None, renderer=None, **defaults)
__init__(app=None, renderer=None, **defaults)

Set the default options for the render() method. If you want the markdown template filter to use options, set them here.

A custom misaka renderer can be specified to be used instead of the default one.

init_app(app)

Registers the rendering method as template filter.

Parameters:app – a flask.Flask instance.
render(text, **overrides)

It delegates to the markdown() function, passing any default options or renderer set in the __init__() method.

The markdown template filter calls this method.

Parameters:
  • text – Markdown-formatted text to be rendered to HTML
  • overrides – Additional options which may override the defaults
Returns:

A flask.Markup instance representing the rendered text

Options

Misaka is very customizable, and supports many Markdown extensions. Flask-Misaka provides a nicer API for these extensions. All functions in the public API (except Misaka.init_app()) accept the following boolean arguments, all of which default to False:

Option Name Description
autolink Parse links even when they are not enclosed in <> characters. Autolinks for the http, https and ftp protocols will be automatically detected. Email addresses are also handled, and http links without protocol, but starting with www.
fenced_code Blocks delimited with 3 or more ~ or backticks will be considered as code, without the need to be indented. An optional language name may be added at the end of the opening fence for the code block.
lax_html or lax_html_blocks HTML blocks do not require to be surrounded by an empty line as in the Markdown standard.
no_intra_emphasis Do not parse emphasis inside of words. Strings such as foo_bar_baz will not generate <em> tags.
space_headers A space is always required between the hash at the beginning of a header and its name, e.g. #this is my header would not be a valid header.
strikethrough Two ~ characters mark the start of a strikethrough, e.g. this is ~~good~~ bad.
superscript Parse superscripts after the ^ character; contiguous superscripts are nested together, and complex values can be enclosed in parenthesis, e.g. this is the 2^(nd) time.
tables Parse PHP-Markdown tables.
hard_wrap or wrap Insert HTML <br> tags inside on paragraphs where the origin Markdown document had newlines (by default, Markdown ignores these newlines).
safelink Only generate links for protocols which are considered safe.
escape Escape all HTML tags, regardless of what they are.
skip_html or no_html Do not allow any user-inputted HTML in the output.
skip_images or no_images Do not generate any <img> tags.
skip_links or no_links Do not generate any <a> tags.
skip_style or no_style Do not generate any <style> tags.
smartypants Post-process rendered markdown text with SmartyPants.
toc or toc_tree Render a table of contents.
use_xhtml or xhtml Output XHTML-conformant tags.

Any option that starts with no_ can also be passed as its inverse set to False. For example, no_html=True and html=False have exactly the same effect, just as no_intra_emphasis=True and intra_emphasis=False have exactly the same effect.

Note

To override an option, you must use exactly the same option name as you used to originally set the option. If you set html=False as a default, you must override it with html=True: using no_html=False or skip_html=False will not work, even though they all refer to the same thing.

Footnotes

[1](Technically, Misaka is just a Python binding to the Sundown library, which is written in C.)