.. -*- 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 ^^^^^^^^^^^^^^^^^^^^^ Using the excellent `staticfiles <>`_ app, mdown's static files should get picked up automatically. If the staticfiles app is not your style, you'll need to locate the install location for the ``mdown`` package (usually your python interpreter's ``site-packages`` directory) and copy/symlink ``mdown/static/mdown`` into your project ``site_media`` directory. Configuration ------------- First off, add ``mdown`` to your list of ``INSTALLED_APPS`` in your project settings module. With the app installed, you need to make a couple choices. You'll have to specify the ``RICHTEXT_WIDGET_CLASS`` and ``RICHTEXT_FILTER`` values in your settings module. RICHTEXT_WIDGET_CLASS ^^^^^^^^^^^^^^^^^^^^^ This package provides 2 options for this setting. **mdown.forms.WmdWidget** *Activates the WMD rich text editor.* **(recommended)** **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$ ./ pygments_styles Usage: ./ 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$ ./ pygment_styles colorful > site_media/css/pygments.css In additon to this single scheme method, the command also accepts the ``--all`` flag, which will generate styles for all available, 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. 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``.