title:      Footnotes Extension
prev_title: Fenced Code Block Extension
prev_url:   fenced_code_blocks.html
next_title: Tables Extension
next_url:   tables.html

Footnotes
=========

Summary
-------

An extension to Python-Markdown that adds footnote syntax. This extension has 
been included with Python-Markdown since 1.7 and should be available to anyone 
who has a typical install of Python-Markdown.

Syntax
------

Python-Markdown's Footnote syntax follows the generally accepted syntax of the 
Markdown community at large and almost exactly matches [PHP Markdown Extra][]'s
implementation of footnotes. The only differences involve a few subtleties in 
the output.

[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/#footnotes

Example:

    Footnotes[^1] have a label[^@#$%] and the footnote's content.

    [^1]: This is a footnote's content.
    [^@#$%]: A footnote on the label: "@#$%".

A footnote label must start with a carot `^` and may contain any inline text 
(including spaces) between a set of square brackets `[]`. Only the first
carot has any special meaning.

A footnote's content must start with the label followed by a colon and at least 
one space. The label used to define the content must exactly match the label used
in the body (inlcuding capitalization and whitespace). The content would then 
follow the label either on the same line or on the next line. The content may 
contain multiple lines, paragraphs, code blocks, blockquotes and most any other 
markdown syntax. The additional lines must be indented one level (four spaces or 
one tab). 

When working with mutiple blocks, it may be helpful to start the content on a 
seperate line from the label which defines the content. This way the entire block 
is indented consistantly and any errors are more easily disernable by the author.


    [^1]: 
        The first paragraph of the definition.

        Paragraph two of the definition.

        > A blockquote with
        > multiple lines.

            a code block

        A final paragraph.

By default, the footnote definitions are placed at the end of the resulting 
HTML document. However, you may want the footnotes in another location within 
the document. Simply place the following text at that location within your 
markdown document (See how to configure this text below):

    ///Footnotes Go Here///

Usage
-----

From the Python interpreter:

    >>> html = markdown.markdown(text, ['footnotes'])

To configure the place marker for footnote definitions (just be sure not to 
use any existing markdown syntax):

    >>> html = markdown.markdown(text, ['footnotes(PLACE_MARKER=+++my marker+++)'])