aboutsummaryrefslogtreecommitdiffstats
path: root/docs/using_as_module.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2008-10-15 22:45:32 -0400
committerWaylan Limberg <waylan@gmail.com>2008-10-15 22:45:32 -0400
commit1ae68f81bdf22d764f6283f8fd70b3b11e33dad0 (patch)
treea1112441e2d884bb11ea645634f81969560b1072 /docs/using_as_module.txt
parent32eeea883fa316fbcff49b790c269b2e35083619 (diff)
downloadmarkdown-1ae68f81bdf22d764f6283f8fd70b3b11e33dad0.tar.gz
markdown-1ae68f81bdf22d764f6283f8fd70b3b11e33dad0.tar.bz2
markdown-1ae68f81bdf22d764f6283f8fd70b3b11e33dad0.zip
Added docs for command line and using as a module.
Diffstat (limited to 'docs/using_as_module.txt')
-rw-r--r--docs/using_as_module.txt123
1 files changed, 123 insertions, 0 deletions
diff --git a/docs/using_as_module.txt b/docs/using_as_module.txt
new file mode 100644
index 0000000..10c276c
--- /dev/null
+++ b/docs/using_as_module.txt
@@ -0,0 +1,123 @@
+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 either a simple ASCII string or **Unicode**
+as input 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="utf8")
+ text = input_file.read()
+ html = markdown.markdown(text, extensions)
+
+If you later want to write it to disk, you should encode it:
+
+ output_file = codecs.open("some_file.html", "w", encoding="utf8")
+ 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','~~~~~~~~')}
+ encoding='utf8',
+ safe_mode = True)
+ 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)
+
+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 file-like-object:
+
+ md = markdown.Markdown()
+ md.convertFile(input="in.txt", output="out.html", encoding="uft8")
+
+The markdown module also includes a shortcut function ``markdownFromFile`` that
+wraps the above method.
+
+ markdown.markdownFromFile(input="in.txt",
+ output="out.html",
+ extensions=[],
+ encoding="utf8",
+ 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, is ``output`` is
+set to ``None``, is 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 defined in ``markdown.HTML_REMOVED_TEXT`` which defaults to
+ ``[HTML_REMOVED]``. To replace the HTML with something else:
+
+ markdown.HTML_REMOVED_TEXT = "--RAW HTML IS NOT ALLOWED--"
+ md = markdown.Markdown(safe_mode="replace")
+
+ **Note**: You may edit the value of ``HTML_REMOVED_TEXT`` directly in
+ markdown.py but you will need to remember to do so every time you upgrade
+ to a newer version of Markdown.
+
+* 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.
+