mezzanine-pagedown / README.md

Mezzanine PageDown

Inspired by mezzanine-mdown and django-pagedown.

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

Differences between mezzanine-pagedown and:

  • mezzanine-mdown: mezzanine-pagdown replaces OpenLibrary's wmd editor used by mezzanine-mdown with the PageDown JavaScript Markdown editor and previewer from Stack Exchange.

    PageDown have two main advantages over wmd:

    • Still maintained
    • Extensible via hooks

    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.

Features

Widgets

mezzanine-pagedown provides two rich text widgets that can be used for editing Mezzanine's rich text content fields:

  • mezzanine_pagedown.widgets.PageDownWidget: Uses the PageDown JavaScript editor and previewer.

  • mezzanine_pagedown.widgets.PlainWidget: Uses a plain text area.

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

How to Use

  1. Get and install the package:

    hg clone https://bitbucket.org/akhayyat/mezzanine-pagedown
    pip install -e mezzanine-pagedown
    
  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 widgets and filters for its rich text fields.

    In your project's settings.py, add the following two lines, depending on the widget and filter you would like to use:

    1. RICHTEXT_WIDGET_CLASS = 'mezzanine_pagedown.widgets.PageDownWidget'
      Or:
      RICHTEXT_WIDGET_CLASS = 'mezzanine_pagedown.widgets.PlainWidget'

    2. RICHTEXT_FILTER = 'mezzanine_pagedown.filters.codehilite'
      Or:
      RICHTEXT_FILTER = 'mezzanine_pagedown.filters.plain'

  4. (Optional): Generate and use a pygments CSS style:

    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.

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.