/mezzanine-pagedown-git

clone from

Primary LanguagePythonBSD 2-Clause "Simplified" LicenseBSD-2-Clause

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.