.. _markup:

=============================
Markup Processing in Birdland
=============================

Birdland comes with support for several different markup language formatters
out of the box as well as support for extending the available markup
formatters. These formatters are used to process the raw input given for the
entry summary and body fields and store the formatted output for later use.

Built-In Formatters
===================

Here is a list of the default formatters.

Raw HTML
--------

Normalized database name: ``'rawhtml'``

Simply stores the raw input.

Plain Text
----------

Normalized database name: ``'plaintext'``

Simply stores the raw input.

Plain Text with Linebreaks
--------------------------

Normalized database name: ``'linebreaks'``

Splits the raw input on linebreaks and wraps each part in HTML paragraph tags

reStructured Text
-----------------

Normalized database name: ``'rest'``

Runs the raw input through the `reStructured Text`_ HTML 4 publisher.
Requires docutils_.

Textile
-------

Normalized database name: ``'textile'``

Runs the raw input through the Textile_ processor. Requires `Python Textile`_.

Markdown
--------

Normalized database name: ``'markdown'``

Runs the raw input through a Markdown_ processor. Requires either markdown2_ or
markdown.py_. markdown2_ is favored over markdown.py_.

.. _reStructured Text: http://docutils.sourceforge.net/rst.html
.. _docutils: http://docutils.sourceforge.net/index.html
.. _Textile: http://www.textism.com/tools/textile/
.. _Python Textile: http://loopcore.com/python-textile/
.. _Markdown: http://daringfireball.net/projects/markdown/
.. _markdown2: http://code.google.com/p/python-markdown2/
.. _markdown.py: http://www.freewisdom.org/projects/python-markdown/


Setting a Default Markup Formatter
==================================

To set the default markup formatter selection for the summary and body
markup fields, set the ``BIRDLAND_DEFAULT_MARKUP_LANG`` setting in your
project's ``settings.py`` to the appropriate normalized database name
for the markup processor.

Adding Support for Other Markup Formatters
==========================================

The list of available markup formatters may be extended by providing a
``BIRDLAND_EXTRA_MARKUP_LANGS`` setting in your ``settings.py``. This setting
should be an iterable of 3-tuples of the form:

       (normalized name, display name, markup formatter callable name)

The markup formatter callable must simply be a callable that takes the raw
input string and returns the processed, formatted results as a unicode string.
If this callable cannot be imported, the markup formatter will not appear in
the list of available formatters.

Other Markup Processing Hooks
=============================

Birdland also provides hooks for customizing how markup is processed in the
form of several signals that are emitted during the markup processing stage
of an ``Entry`` save. To read about these, refer to the
:ref:`signals <signals>` documentation.
