wagtail-markdown: Markdown fields and blocks for Wagtail

Tired of annoying rich text editors getting in the way of your content input? Wish Wagtail worked more like a wiki? Well, now it can.

wagtail-markdown provides Markdown field support for Wagtail. Specifically, it provides:

• A wagtailmarkdown.blocks.MarkdownBlock for use in streamfields.
• A wagtailmarkdown.fields.MarkdownField for use in page models.
• A wagtailmarkdown.edit_handlers.MarkdownPanel for use in the editor interface.
• A markdown template tag.

The markdown rendered is based on python-markdown, but with several extensions to make it actually useful in Wagtail:

• Tables.
• Code highlighting.
• Inline links to pages (<:My page name|link title>) and documents (<:doc:My fancy document.pdf>), and inline images (<:image:My pretty image.jpeg>).
• Inline Markdown preview using SimpleMDE

These are implemented using the python-markdown extension interface.

You can configure wagtail-markdown to use additional Markdown extensions by via the WAGTAILMARKDOWN_EXTENSIONS setting. config.

For example, to enable the Table of Contents and Sane Lists extensions:

WAGTAILMARKDOWN_EXTENSIONS = ["toc", "sane_lists"]

Installation

Alpha release is available on Pypi - https://pypi.org/project/wagtail-markdown/ - installable via pip install wagtail-markdown. It's not a production ready release.

The SimpleMDE editor uses FontAwesome for its widget icons. You can install Wagtail FontAwesome via pip install wagtailfontawesome, or if you already have the stylesheet, add the following to a wagtail_hooks module in a registered app in your project:

@hooks.register('insert_global_admin_css')
def import_fontawesome_stylesheet():
    elem = '<link rel="stylesheet" href="{}path/to/font-awesome.min.css">'.format(
        settings.STATIC_URL
    )
    return format_html(elem)

Syntax highlighting

Syntax highlighting using codehilite is an optional feature, which works by adding CSS classes to the generated HTML. To use these classes, you will need to install Pygments (pip install Pygments), and to generate an appropriate stylesheet. You can generate one as per the Pygments documentation, with:

>>> from pygments.formatters import HtmlFormatter
>>> print HtmlFormatter().get_style_defs('.codehilite')

Save the output to a file and reference it somewhere that will be picked up on pages rendering the relevant output, e.g. your base template:

<link rel="stylesheet" type="text/css" href="{% static 'path/to/pygments.css' %}">

Using it

Add it to INSTALLED_APPS:

INSTALLED_APPS += [
    'wagtailmarkdown',
]

Use it as a StreamField block:

from wagtailmarkdown.blocks import MarkdownBlock

class MyStreamBlock(StreamBlock):
    markdown = MarkdownBlock(icon="code")

Or use as a page field:

from wagtailmarkdown.edit_handlers import MarkdownPanel
from wagtailmarkdown.fields import MarkdownField

class MyPage(Page):
    body = MarkdownField()

    content_panels = [
        FieldPanel("title", classname="full title"),
        MarkdownPanel("body"),
    ]

And render the content in a template:

{% load wagtailmarkdown %}
<article>
{{ self.body|markdown }}
</article>

To enable syntax highlighting please use the Pygments (pip install Pygments) library.

NB: The current version was written in about an hour and is probably completely unsuitable for production use. Testing, comments and feedback are welcome: kevin.howbrook@torchbox.com (or open a Github issue).

Roadmap for 0.5

• Set up tests: torchbox#28