amites/mezzanine-pagedown

Fork from https://bitbucket.org/akhayyat/mezzanine-pagedown

Mezzanine PageDown

Inspired by mezzanine-mdown, django-pagedown, and django-markupmirror.

This package provides rich text widgets and filters for Mezzanine to author content using Markdown syntax instead of the default TinyMCE editor.

Features

• Uses the PageDown markdown editor from Stack Exchange (optional), and Python-Markdown for rendering.

• Supports client-side and server-side live previews in the editor. Client-side previews use PageDown's JavaScript previewer. Server-side previews use the same rendering filter as the final page.

• 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

1. Get and install the package:

   pip install mezzanine-pagedown
   

   Mezzanine 1.3 or higher is required.

2. Install the app in your Mezzanine project by adding mezzanine_pagedown to the list of INSTALLED_APPS in your project's settings.py.

3. 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.

4. 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).

5. 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.

6. (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:

      import mezzanine_pagedown.urls
     

     Then add the following line to urlpatterns:

      ("^pagedown/", include(mezzanine_pagedown.urls)),
     

     In this case, the preview URL is /pagedown/preview/. You can replace "^pagedown/" with your own path.

7. (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())
   

8. (Optional): Generate and use a pygments CSS style for use with the CodeHilite extension (requires installing pygments):

   python manage.py pygments_styles <scheme_name>
   

License

Licence: BSD. See included LICENSE file.

Note that this license applies to this repository only. The PageDown JavaScript library is used as a sub-repository and has its own license.