1Using Markdown as Python Library
2================================
3
4First and foremost, Python-Markdown is intended to be a python library module
5used by various projects to convert Markdown syntax into HTML.
6
7The Basics
8----------
9
10To use markdown as a module:
11
12    import markdown
13    html = markdown.markdown(your_text_string)
14
15Encoded Text
16------------
17
18Note that ``markdown()`` expects **Unicode** as input (although a simple ASCII
19string should work) and returns output as Unicode.  Do not pass encoded strings to it!
20If your input is encoded, e.g. as UTF-8, it is your responsibility to decode
21it.  E.g.:
22
23    input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
24    text = input_file.read()
25    html = markdown.markdown(text, extensions)
26
27If you later want to write it to disk, you should encode it yourself:
28
29    output_file = codecs.open("some_file.html", "w", encoding="utf-8")
30    output_file.write(html)
31
32More Options
33------------
34
35If you want to pass more options, you can create an instance of the ``Markdown``
36class yourself and then use ``convert()`` to generate HTML:
37
38    import markdown
39    md = markdown.Markdown(
40            extensions=['footnotes'],
41            extension_configs= {'footnotes' : ('PLACE_MARKER','~~~~~~~~')},
42            safe_mode=True,
43            output_format='html4'
44    )
45    return md.convert(some_text)
46
47You should also use this method if you want to process multiple strings:
48
49    md = markdown.Markdown()
50    html1 = md.convert(text1)
51    html2 = md.convert(text2)
52
53Working with Files
54------------------
55
56While the Markdown class is only intended to work with Unicode text, some
57encoding/decoding is required for the command line features. These functions
58and methods are only intended to fit the common use case.
59
60The ``Markdown`` class has the method ``convertFile`` which reads in a file and
61writes out to a file-like-object:
62
63    md = markdown.Markdown()
64    md.convertFile(input="in.txt", output="out.html", encoding="utf-8")
65
66The markdown module also includes a shortcut function ``markdownFromFile`` that
67wraps the above method.
68
69    markdown.markdownFromFile(input="in.txt",
70                              output="out.html",
71                              extensions=[],
72                              encoding="utf-8",
73                              safe=False)
74
75In either case, if the ``output`` keyword is passed a file name (i.e.:
76``output="out.html"``), it will try to write to a file by that name. If
77``output`` is passed a file-like-object (i.e. ``output=StringIO.StringIO()``),
78it will attempt to write out to that object. Finally, if ``output`` is
79set to ``None``, it will write to ``stdout``.
80
81Using Extensions
82----------------
83
84One of the parameters that you can pass is a list of Extensions. Extensions
85must be available as python modules either within the ``markdown.extensions``
86package or on your PYTHONPATH with names starting with `mdx_`, followed by the
87name of the extension.  Thus, ``extensions=['footnotes']`` will first look for
88the module ``markdown.extensions.footnotes``, then a module named
89``mdx_footnotes``.   See the documentation specific to the extension you are
90using for help in specifying configuration settings for that extension.
91
92Note that some extensions may need their state reset between each call to
93``convert``:
94
95    html1 = md.convert(text1)
96    md.reset()
97    html2 = md.convert(text2)
98
99Safe Mode
100---------
101
102If you are using Markdown on a web system which will transform text provided
103by untrusted users, you may want to use the "safe_mode" option which ensures
104that the user's HTML tags are either replaced, removed or escaped. (They can
105still create links using Markdown syntax.)
106
107* To replace HTML, set ``safe_mode="replace"`` (``safe_mode=True`` still works
108    for backward compatibility with older versions). The HTML will be replaced
109    with the text defined in ``markdown.HTML_REMOVED_TEXT`` which defaults to
110    ``[HTML_REMOVED]``. To replace the HTML with something else:
111
112        markdown.HTML_REMOVED_TEXT = "--RAW HTML IS NOT ALLOWED--"
113        md = markdown.Markdown(safe_mode="replace")
114
115    **Note**: You could edit the value of ``HTML_REMOVED_TEXT`` directly in
116    markdown/__init__.py but you will need to remember to do so every time you
117    upgrade to a newer version of Markdown. Therefore, this is not recommended.
118
119* To remove HTML, set ``safe_mode="remove"``. Any raw HTML will be completely
120    stripped from the text with no warning to the author.
121
122* To escape HTML, set ``safe_mode="escape"``. The HTML will be escaped and
123    included in the document.
124
125Output Formats
126--------------
127
128If Markdown is outputing (X)HTML as part of a web page, most likely you will
129want the output to match the (X)HTML version used by the rest of your page/site.
130Currently, Markdown offers two output formats out of the box; "HTML4" and
131"XHTML1" (the default) . Markdown will also accept the formats "HTML" and
132"XHTML" which currently map to "HTML4" and "XHTML" respectively. However,
133you should use the more explicit keys as the general keys may change in the
134future if it makes sense at that time. The keys can either be lowercase or
135uppercase.
136
137To set the output format do:
138
139    html = markdown.markdown(text, output_format='html4')
140
141Or, when using the Markdown class:
142
143    md = markdown.Markdown(output_format='html4')
144    html = md.convert(text)
145
146Note that the output format is only set once for the class and cannot be
147specified each time ``convert()`` is called. If you really must change the
148output format for the class, you can use the ``set_output_format`` method:
149
150    md.set_output_format('xhtml1')
151