Commits

Ahmad Khayyat committed 8edb700

Rewrite README and update with new features

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
+[django-markupmirror][3].
 
-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
------------
-
-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
+editor.
 
 
 Features
 --------
 
-### 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 manage.py pygments_styles
-    Usage: ./manage.py 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
-stdout:
-
-    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
-constantly.
+ - 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 `settings.py`.
 
- 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'`  
-        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 `settings.py`, set
+    `RICHTEXT_FILTER` to:
 
- 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 (`>`):
+
+        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
+    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 manage.py 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.
 
 
 [1]: https://bitbucket.org/onelson/mezzanine-mdown
 [2]: https://bitbucket.org/moberley/django-pagedown
-[3]: http://mezzanine.jupo.org/
-[4]: https://code.google.com/p/pagedown/ "Official PageDown project"
-[5]: http://code.google.com/p/pagedown/wiki/PageDown#Plugin_hooks
-[6]: http://packages.python.org/Markdown/extensions/code_hilite.html
+[3]: https://bitbucket.org/fabianbuechler/django-markupmirror
+[4]: http://mezzanine.jupo.org/
+[5]: https://code.google.com/p/pagedown/ "Official PageDown project"
+[6]: http://pythonhosted.org/Markdown/
+[7]: http://pythonhosted.org/Markdown/extensions/index.html
+[8]: http://pythonhosted.org/Markdown/extensions/extra.html
+[9]: https://github.com/jsocol/bleach
+[10]: http://packages.python.org/Markdown/extensions/code_hilite.html
+[11]: http://pythonhosted.org/Markdown/extensions/api.html "Writing Extensions for Python-Markdown"
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.