-Inspired by [mezzanine-mdown] and [django-pagedown].
+Inspired by [mezzanine-mdown], [django-pagedown], and
-This package provides widgets and filters for [Mezzanine] that
-enable admins to use Markdown syntax to create their site content,
-rather than using the TinyMCE editor to generate HTML code for rich
-text content types, such as *rich text pages* and *blog posts*.
-Differences between mezzanine-pagedown and:
- - mezzanine-mdown: mezzanine-pagdown replaces OpenLibrary's wmd
- Markdown editor and previewer from Stack Exchange.
- PageDown have two main advantages over wmd:
- - Extensible via [hooks]
- Also, mezzanine-pagedown integrates with Mezzanine's file browser
- differently. See the differences between mezzanine-pagedown and
- - django-pagedown: mezzanine-pagedown integrates the editor's `Insert
- Image` button with Mezzanine's file browser (Media
- Library). Clicking the `Insert Image` button pops up an in-window
- dialog of Mezzanine's Media Library.
+This package provides rich text widgets and filters for [Mezzanine]
+to author content using Markdown syntax instead of the default TinyMCE
+ - Uses the [PageDown] markdown editor from Stack Exchange
+ (optional), and [Python-Markdown] for rendering.
-mezzanine-pagedown provides two rich text widgets that can be used for
-editing Mezzanine's rich text content fields:
+ - Supports client-side and server-side live previews in the
+ previewer. Server-side previews use the same rendering filter as
- - `mezzanine_pagedown.widgets.PageDownWidget`: Uses the PageDown
+ - 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
- - `mezzanine_pagedown.widgets.PlainWidget`: Uses a plain text area.
+ - HTML sanitizing using [Bleach]. Bleach is already a dependency
-mezzanine-pagedown provides two rich text filters that can be used to
-render Markdown content:
- - `mezzanine_pagedown.filters.codehilite`: Renders the content using
- Markdown with the [CodeHilite] extension enabled.
- - `mezzanine_pagedown.filters.plain`: Renders the content using
- vanilla Markdown formatting.
-### CodeHilite Style Generation
-mezzanine-pagedown shamelessly *reuses* (among other things)
-[mezzanine-mdown]'s management command `pygments_styles`, which
-allows you to generate CSS styles for colorizing code blocks parsed by
-This feature requires the `pygments` python package, which can be
-Invoke the management command without arguments to see a usage message:
- $ python manage.py pygments_styles
- Usage: ./manage.py pygments_styles <scheme_name>
- Available color schemes:
-Invoking with the scheme's name as an argument will print the CSS to
- python manage.py pygment_styles colorful > pygments.css
-In additon to this single scheme method, the command also accepts the
-`--all` flag, which will generate styles for all available styles, but
-with one key difference: each scheme is prefixed with its name as a
-CSS class name. This is handy during theme development as you can
-quickly switch pygments schemes just by setting the class on the body
-tag to your choice of scheme without having to regenerate CSS files
+ - 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.
`mezzanine_pagedown` to the list of `INSTALLED_APPS` in your
- 3. Configure Mezzanine to use one of the provided widgets and filters
- for its rich text fields.
+ 3. Configure Mezzanine to use one of the provided rich text
+ widgets. In your project's `settings.py`, set
+ `RICHTEXT_WIDGET_CLASS` to:
- In your project's `settings.py`, add the following two lines,
- depending on the widget and filter you would like to use:
+ - `'mezzanine_pagedown.widgets.PageDownWidget'` to use the
+ PageDown editor with live preview.
- 1. `RICHTEXT_WIDGET_CLASS = 'mezzanine_pagedown.widgets.PageDownWidget'`
- `RICHTEXT_WIDGET_CLASS = 'mezzanine_pagedown.widgets.PlainWidget'`
+ - `'mezzanine_pagedown.widgets.PlainWidget'` to use a plain
+ textarea without preview.
- 2. `RICHTEXT_FILTER = 'mezzanine_pagedown.filters.codehilite'`
- `RICHTEXT_FILTER = 'mezzanine_pagedown.filters.plain'`
+ 4. Configure Mezzanine to use one of the provided rich text filters
+ for rendering markdown content. In `settings.py`, set
- 4. (Optional): Generate and use a pygments CSS style:
+ - `'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`
+ 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): Enable server-side live previews in the editor.
+ PAGEDOWN_SERVER_SIDE_PREVIEW = True
+ By default (`False`), previews are generated client-side using
+ 7. (Optional): Set enabled extensions. Requires the `custom` filter:
+ RICHTEXT_FILTER = '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>
Licence: BSD. See included `LICENSE` file.
Note that this license applies to this repository only. The
-: https://code.google.com/p/pagedown/ "Official PageDown project"
+: https://code.google.com/p/pagedown/ "Official PageDown project"
+: http://pythonhosted.org/Markdown/extensions/api.html "Writing Extensions for Python-Markdown"