(I can't help it. I keep coming up with ideas for cool Flask extensions.)

If you've asked or answered a question on Stack Overflow you have seen the editor that they use. You type your text using Markdown syntax in a standard text area HTML control and below it a preview is generated as you type. This editor is powered by an open source project called PageDown.

Today I'm introducing Flask-PageDown, a wrapper extension that makes it really easy to add this control to your Flask-WTF based forms.

Demo

Below is a an example that will give you an idea of what this extension can do in your own application. Type Markdown in the text editor below and see how it gets converted on the fly to HTML!

# This is a demo of Flask-PageDown **Markdown** is rendered on the fly in the *preview area*!

Installation & Configuration

You can install the extension with pip:

$ pip install flask-pagedown

The extension needs to be initialized after the application instance is created:

from flask.ext.pagedown import PageDown app = Flask(__name__) pagedown = PageDown(app)

You can also use the init_app(app) format.

The Editor is supported via two Javascript files. To include these files in your HTML document you have to call pagedown.html_head() from inside the <head> element of your page:

<html> <head> {{ pagedown.html_head() }} </head> <body> ... </body> </html>

The Javascript files are loaded from a CDN, the files do not need to be hosted by your application. If you prefer to host these files locally then replace the html_head() call with your own <script> tags for files Markdown.Converter.js and Markdown.Sanitizer.js (or their minified versions).

Creating a Form with a PageDown Field

The extension exports a PageDownField class that works exactly like a TextAreaField . Here is an example form that uses this field:

from flask.ext.wtf import Form from flask.ext.pagedown.fields import PageDownField from wtforms.fields import SubmitField class PageDownFormExample(Form): pagedown = PageDownField('Enter your markdown') submit = SubmitField('Submit')

The field can be rendered to a template in the usual way. For example:

<form method="POST"> {{ form.pagedown(rows = 10) }} {{ form.submit }} </form>

The preview element does not need to be added, the extension does that for you.

Note that when a form with a PageDownField is submitted the raw Markdown text is submitted. The form does not receive the HTML preview. If you need to store the HTML in the server then you should use a server-side Markdown converter like Flask-Markdown.

Styles

You can define custom styles for the text area and preview elements. The text area can be referenced with the flask-pagedown-input CSS class. The CSS class for the preview is flask-pagedown-preview .

Feedback and Contributions Accepted

As always I look forward to your comments and suggestions. Please write below in the comments.

At this time the extension does not display a toolbar like the one on Stack Overflow. I will probably add that in a future release, but if you get to it first please send me a pull request on github.

Miguel