Using Markdown as Python Library

================================

First and foremost, Python-Markdown is intended to be a python library module

used by various projects to convert Markdown syntax into HTML.

The Basics

----------

To use markdown as a module:

    import markdown

    html = markdown.markdown(your_text_string)

Encoded Text

------------

Note that ``markdown()`` expects **Unicode** as input (although a simple ASCII 

string should work) and returns output as Unicode.  Do not pass encoded strings to it!

If your input is encoded, e.g. as UTF-8, it is your responsibility to decode 

it.  E.g.:

    input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")

    text = input_file.read()

    html = markdown.markdown(text, extensions)

If you later want to write it to disk, you should encode it yourself:

    output_file = codecs.open("some_file.html", "w", encoding="utf-8")

    output_file.write(html)

More Options

------------

If you want to pass more options, you can create an instance of the ``Markdown``

class yourself and then use ``convert()`` to generate HTML:

    import markdown

    md = markdown.Markdown(

            extensions=['footnotes'], 

            extension_configs= {'footnotes' : ('PLACE_MARKER','~~~~~~~~')},

            output_format='html4',

            safe_mode="replace",

            html_replacement_text="--NO HTML ALLOWED--",

            tab_length=8,

            enable_attributes=False,

            smart_emphasis=False,

    )

    return md.convert(some_text)

You should also use this method if you want to process multiple strings:

    md = markdown.Markdown()

    html1 = md.convert(text1)

    html2 = md.convert(text2)

Any options accepted by the `Markdown` class are also accepted by the 

`markdown` shortcut function. However, a new instant of the class will be

created each time the shortcut function is called.

Working with Files

------------------

While the Markdown class is only intended to work with Unicode text, some

encoding/decoding is required for the command line features. These functions 

and methods are only intended to fit the common use case.

The ``Markdown`` class has the method ``convertFile`` which reads in a file and

writes out to a file-like-object:

    md = markdown.Markdown()

    md.convertFile(input="in.txt", output="out.html", encoding="utf-8")

The markdown module also includes a shortcut function ``markdownFromFile`` that

wraps the above method.

    markdown.markdownFromFile(input="in.txt", 

                              output="out.html", 

                              extensions=[],

                              encoding="utf-8",

                              safe=False)

In either case, if the ``output`` keyword is passed a file name (i.e.: 

``output="out.html"``), it will try to write to a file by that name. If

``output`` is passed a file-like-object (i.e. ``output=StringIO.StringIO()``),

it will attempt to write out to that object. Finally, if ``output`` is 

set to ``None``, it will write to ``stdout``.

Using Extensions

----------------

One of the parameters that you can pass is a list of Extensions. Extensions 

must be available as python modules either within the ``markdown.extensions``

package or on your PYTHONPATH with names starting with `mdx_`, followed by the 

name of the extension.  Thus, ``extensions=['footnotes']`` will first look for 

the module ``markdown.extensions.footnotes``, then a module named 

``mdx_footnotes``.   See the documentation specific to the extension you are 

using for help in specifying configuration settings for that extension.

Note that some extensions may need their state reset between each call to 

``convert``:

    html1 = md.convert(text1)

    md.reset()

    html2 = md.convert(text2)

Safe Mode

---------

If you are using Markdown on a web system which will transform text provided 

by untrusted users, you may want to use the "safe_mode" option which ensures 

that the user's HTML tags are either replaced, removed or escaped. (They can 

still create links using Markdown syntax.)

* To replace HTML, set ``safe_mode="replace"`` (``safe_mode=True`` still works 

    for backward compatibility with older versions). The HTML will be replaced 

    with the text assigned to ``html_replacement_text`` which defaults to 

    ``[HTML_REMOVED]``. To replace the HTML with something else:

        md = markdown.Markdown(safe_mode="replace", 

                               html_replacement_text="--RAW HTML NOT ALLOWED--")

* To remove HTML, set ``safe_mode="remove"``. Any raw HTML will be completely 

    stripped from the text with no warning to the author.

* To escape HTML, set ``safe_mode="escape"``. The HTML will be escaped and 

    included in the document.

Note that "safe_mode" does not alter the "enable_attributes" option, which 

could allow someone to inject javascript (i.e., `{@onclick=alert(1)}`). You 

may also want to set `enable_attributes=False` when using "safe_mode".

Output Formats

--------------

If Markdown is outputing (X)HTML as part of a web page, most likely you will

want the output to match the (X)HTML version used by the rest of your page/site.

Currently, Markdown offers two output formats out of the box; "HTML4" and 

"XHTML1" (the default) . Markdown will also accept the formats "HTML" and 

"XHTML" which currently map to "HTML4" and "XHTML" respectively. However, 

you should use the more explicit keys as the general keys may change in the 

future if it makes sense at that time. The keys can either be lowercase or 

uppercase.

To set the output format do:

    html = markdown.markdown(text, output_format='html4')

Or, when using the Markdown class:

    md = markdown.Markdown(output_format='html4')

    html = md.convert(text)

Note that the output format is only set once for the class and cannot be 

specified each time ``convert()`` is called. If you really must change the

output format for the class, you can use the ``set_output_format`` method:

    md.set_output_format('xhtml1')