Source

mezzanine-mdown / README

Full commit
.. -*- restructuredtext -*-

mezzanine-mdown
===============

This package provides widgets and filters for mezzanine that enable admins
to use markdown formatting to create their site content, rather than using
the tinymce editor to generate html used in *rich content* types, such as 
*rich pages* and *blog posts*.

Installation
------------

Get the package
^^^^^^^^^^^^^^^

pip::

    user@home:~$ pip install mezzanine-mdown

easy_install::

    user@home:~$ easy_install mezzanine-mdown


Prep the static media
^^^^^^^^^^^^^^^^^^^^^

media with staticfiles or symlinks

Template Overrides
^^^^^^^^^^^^^^^^^^

While not 100% neccessary, there are some styles in the default theme that
will interfere with the rendering of the WmdWidget's preview panel when 
editing content on the site (rather than using the admin interface).

In order to remedy this issue ensure the app directory template loader is 
activated and ``mdown`` is listed in ``INSTALLED_APPS`` **before** ``mezzanine.core``

.. TODO: does the app order mean you don't have to remove the current theme's template?
   Testing required.

Configuration
-------------

With the app installed, you need to make a couple choices.

``RICHTEXT_WIDGET_CLASS``
^^^^^^^^^^^^^^^^^^^^^^^^^

This package provides 2 options for this setting.


+ ``"mdown.forms.WmdWidget"`` **(recommended)**  *Activates the WMD rich text editor.*
+ ``"mdown.forms.PlainWidget"`` *Use a plain Textarea (no rich text editor).*


``RICHTEXT_FILTER``
^^^^^^^^^^^^^^^^^^^
Again, there are 2 options for this setting.

+ ``"mdown.filters.codehilite"`` *Renders the content using markdown with the 
  codehilite extension enabled.*
+ ``"mdown.filters.plain"`` *Renders the content using vanilla markdown formatting.*

Extra Steps
-----------

Pygments Styles
^^^^^^^^^^^^^^^

Using the management command ``pygments_styles`` you can generate css to 
colorize code blocks parsed by the codehilite filter.

**Note:** this requires pygments to be installed (use ``pip install pygments``
or ``easy_install pygments`` to use this feature).

Invoke the command with no args to see a usage message and list of available color schemes on your system.::

    user@home:~/mysite$ ./manage.py pygments_styles
    Usage: ./manage.py pygments_styles <scheme_name>
    Available color schemes:
      borland
      bw
      colorful
      default
      ... [ snip ] ...

Invoking with the scheme's name as an argument will print the css to stdout, which you can 
redirect to a file like so: ::

    user@home:~/mysite$ ./manage.py pygment_styles colorful > site_media/css/pygments.css

Once you've got a css file generated, simply add it to your site's base template to get your code "pretty" printed.

Updating Theme Templates
^^^^^^^^^^^^^^^^^^^^^^^^

Themes that were based on the default theme and were created prior to 
**Mezzanine's 0.11.3 release** will most likely not have the ``richtext_filter``
applied to *rich content*. To correct this, you simply have to update the 
templates for these content types so that the filter is used.

For example, in the default theme, the 
``templates/blog/blog_post_detail.html`` had a line that  was updated from:::

    {{ blog_post.content|safe }}

to:::

    {{ blog_post.content|richtext_filter|safe }}

Just ensure that the ``safe`` filter comes after the ``richtext_filter``.