abrunyate / wagtail-markdown Goto Github PK

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.

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.

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>

You can pass extensions by name to the filter:

{% load wagtailmarkdown %}
<article>
{{ self.body|markdown:"my_extension_package.my_extension_module" }}
</article>

The markdown filter sanitizes the output of the underlying markdown processor, to prevent an untrusted user from passing malicious markup. This may conflict with some extensions. When additional extensions are specified, it is possible to specify what additional HTML must be allowed through. This is done by defining a module variable allowed_markup for extensions specified as "module name", or a class variable allowed_markup for extensions specified as "module_name:class_name". In either case it is possible to recursively add to the bleach white list for tags, attributes, and styles. For example, adding

allowed_markup = {
  tags : ["sub"],
  attributes : { img : ["srcset"] },
  styles : [ "text-decoration-line" ]
}

to the extension module allows subscripts, image source sets, and text decoration (such as underline or strike through) in addition to the HTML permitted by default.

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: [email protected] (or open a Github issue).

• Set up tests: torchbox#28