Ahmad Khayyat committed 8edb700

Rewrite README and update with new features

  • Participants
  • Parent commits 143c59e

Comments (0)

Files changed (1)

 Mezzanine PageDown
-Inspired by [mezzanine-mdown][1] and [django-pagedown][2].
+Inspired by [mezzanine-mdown][1], [django-pagedown][2], and
-This package provides widgets and filters for [Mezzanine][3] 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
-    editor used by mezzanine-mdown with the [PageDown][4] JavaScript
-    Markdown editor and previewer from Stack Exchange.
-    PageDown have two main advantages over wmd:
-     - Still maintained
-     - Extensible via [hooks][5]
-    Also, mezzanine-pagedown integrates with Mezzanine's file browser
-    differently. See the differences between mezzanine-pagedown and
-    django-pagedown below.
- -  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][4]
+to author content using Markdown syntax instead of the default TinyMCE
-### Widgets
+ - Uses the [PageDown][5] markdown editor from Stack Exchange
+   (optional), and [Python-Markdown][6] 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
+   editor. Client-side previews use PageDown's JavaScript
+   previewer. Server-side previews use the same rendering filter as
+   the final page.
- - `mezzanine_pagedown.widgets.PageDownWidget`: Uses the PageDown
-   JavaScript editor and previewer.
+ - Supports bundled and custom [Python-Markdown extensions][7], and
+   provides a few filters that are preconfigured to use some
+   extensions, such as [Markdown Extra][8]. If server-side previews
+   are enabled, configured extensions will be enabled in the editor
+   preview.
- - `mezzanine_pagedown.widgets.PlainWidget`: Uses a plain text area.
+ - HTML sanitizing using [Bleach][9]. Bleach is already a dependency
+   of Mezzanine.
-### Filters
-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][6] 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][1]'s management command `pygments_styles`, which
-allows you to generate CSS styles for colorizing code blocks parsed by
-the CodeHilite filter.
-This feature requires the `pygments` python package, which can be
-installed by running:
-    pip install pygments
-Invoke the management command without arguments to see a usage message:
-    $ python pygments_styles
-    Usage: ./ pygments_styles <scheme_name>
-    Available color schemes:
-      monokai
-      manni
-      rrt
-      perldoc
-      borland
-      colorful
-      default
-      ...
-Invoking with the scheme's name as an argument will print the CSS to
-    python 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.
 How to Use
     `mezzanine_pagedown` to the list of `INSTALLED_APPS` in your
     project's ``.
- 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 ``, set
-    In your project's ``, 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'`  
-        Or:  
-        `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'`  
-        Or:  
-        `RICHTEXT_FILTER = 'mezzanine_pagedown.filters.plain'`
+ 4. Configure Mezzanine to use one of the provided rich text filters
+    for rendering markdown content. In ``, 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][10] 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 (`>`):
+    mezzanine-pagedown provides its own sanitizing after rendering
+    Markdown to HTML, and respects Mezzanine's
+ 6. (Optional): Enable server-side live previews in the editor.
+    By default (`False`), previews are generated client-side using
+    PageDown's previewer.
+ 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][11], 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 pygments_styles <scheme_name>
 Licence: BSD. See included `LICENSE` file.
 Note that this license applies to this repository only. The
-[PageDown][4] JavaScript library is used as a sub-repository and has
+[PageDown][5] JavaScript library is used as a sub-repository and has
 its own license.
-[4]: "Official PageDown project"
+[5]: "Official PageDown project"
+[11]: "Writing Extensions for Python-Markdown"