diff options
| -rw-r--r-- | docs/command_line.txt | 57 | ||||
| -rw-r--r-- | docs/using_as_module.txt | 123 |
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. + |