aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/command_line.txt57
-rw-r--r--docs/using_as_module.txt123
2 files changed, 180 insertions, 0 deletions
diff --git a/docs/command_line.txt b/docs/command_line.txt
new file mode 100644
index 0000000..8ec2522
--- /dev/null
+++ b/docs/command_line.txt
@@ -0,0 +1,57 @@
+Using Python-Markdown on the Command Line
+=========================================
+
+While Python-Markdown is primarily a python library, it also serves as a
+command line program. While there are many other command line implementations
+of Markdown, you may not have them installed, or you may prefer to use
+Python-Markdown's various extensions.
+
+The Basics
+----------
+
+To use ``markdown.py`` from the command line, run it as
+
+ python markdown.py input_file.txt
+
+or
+
+ python markdown.py input_file.txt > output_file.html
+
+More Options
+
+If you are using Python 2.3 or higher, you can also use advanced
+command line options to specify encoding or to run extensions.
+
+ $ python markdown.py
+ Usage: markdown.py INPUTFILE [options]
+
+ Options:
+ -h, --help show this help message and exit
+ -f OUTPUT_FILE, --file=OUTPUT_FILE
+ write output to OUTPUT_FILE
+ -e ENCODING, --encoding=ENCODING
+ encoding for input and output files
+ -q, --quiet suppress all messages
+ -v, --verbose print info messages
+ -s SAFE_MODE, --safe=SAFE_MODE
+ safe mode ('replace', 'remove' or 'escape' user's
+ HTML tag)
+ --noisy print debug messages
+ -x EXTENSION, --extension=EXTENSION
+ load extension EXTENSION
+
+Using Extensions
+----------------
+
+For an extension to be ran this way it must be provided in a module
+named ``mdx_{extensionname}.py`` which should be in your python path,
+e.g. ``mdx_footnotes.py``. It can then be invoked as by name (the
+part after "mdx_"):
+
+ python markdown.py -x footnotes text_with_footnotes.txt > output.html
+
+If the extension supports config options (see below), you can also
+pass them in as well:
+
+ python markdown.py -x "footnotes(PLACE_MARKER=~~~~~~~~)" input.txt
+
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.
+