PageDown rich text widget for Mezzanine
This package provides rich text widgets and filters for Mezzanine to author content using Markdown syntax instead of the default TinyMCE editor.
- Uses the PageDown markdown editor from Stack Exchange (optional), and Python-Markdown for rendering.
- Supports bundled and custom Python-Markdown extensions, and provides a few filters that are preconfigured to use some extensions, such as Markdown Extra. If server-side previews are enabled, configured extensions will be enabled in the editor preview.
- HTML sanitizing using Bleach. Bleach is already a dependency of Mezzanine.
- Integrates the editor’s Insert Image button with Mezzanine’s file browser (Media Library). Clicking the Insert Image button pops up an in-window selection dialog of Mezzanine’s Media Library.
How to Use
Get and install the package:
pip install mezzanine-pagedown
Mezzanine 1.3 or higher is required.
Install the app in your Mezzanine project by adding mezzanine_pagedown to the list of INSTALLED_APPS in your project’s settings.py.
Configure Mezzanine to use one of the provided rich text widgets. In your project’s settings.py, set RICHTEXT_WIDGET_CLASS to:
- 'mezzanine_pagedown.widgets.PageDownWidget' to use the PageDown editor with live preview.
- 'mezzanine_pagedown.widgets.PlainWidget' to use a plain textarea without preview.
Configure Mezzanine to use one of the provided rich text filters for rendering markdown content. In settings.py, set RICHTEXT_FILTERS to include one of the following:
- 'mezzanine_pagedown.filters.plain' to use plain Markdown syntax with no extensions.
- 'mezzanine_pagedown.filters.extra' to use Markdown Extra.
- 'mezzanine_pagedown.filters.codehilite' to enable the CodeHilite extension.
- 'mezzanine_pagedown.filters.custom' to enable an explicit list of extensions through the PAGEDOWN_MARKDOWN_EXTENSIONS setting (see below).
Disable Mezzanine’s HTML sanitizing so that it does not interfere with markdown’s blockquote syntax (>):
RICHTEXT_FILTER_LEVEL = 3
mezzanine-pagedown provides its own sanitizing after rendering Markdown to HTML, and respects Mezzanine’s RICHTEXT_ALLOWED_TAGS, RICHTEXT_ALLOWED_ATTRIBUTES, and RICHTEXT_ALLOWED_STYLES settings.
(Optional): Server-side previews:
In settings.py, enable server-side live previews in the editor:
PAGEDOWN_SERVER_SIDE_PREVIEW = True
By default (False), previews are generated client-side using PageDown’s previewer.
In urls.py, enable the preview URL:
Then add the following line to urlpatterns:
In this case, the preview URL is /pagedown/preview/. You can replace "^pagedown/" with your own path.
(Optional): Set enabled extensions. Requires the custom filter:
RICHTEXT_FILTERS = ['mezzanine_pagedown.filters.custom'] PAGEDOWN_MARKDOWN_EXTENSIONS = ('extra','codehilite','toc')
To use a custom extension, import it and include an instance in the list of extensions:
from myapp.markdown_extensions.myextension import MyExtension PAGEDOWN_MARKDOWN_EXTENSIONS = ('extra', MyExtension())
(Optional): Generate and use a pygments CSS style for use with the CodeHilite extension (requires installing pygments):
python manage.py pygments_styles <scheme_name>
Licence: BSD. See included LICENSE file.