aboutsummaryrefslogtreecommitdiffstats
path: root/docs/reference.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference.md')
-rw-r--r--docs/reference.md238
1 files changed, 238 insertions, 0 deletions
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 0000000..16735c7
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,238 @@
+title: Library Reference
+prev_title: Installation
+prev_url: install.html
+next_title: Command Line
+next_url: cli.html
+
+
+Using Markdown as a 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)
+
+The Details
+-----------
+
+Python-Markdown provides two public functions (`markdown.markdown` and
+`markdown.markdownFromFile`) both of which wrap the public class
+`markdown.Markdown`. If you're processing one document at a time, the
+functions will serve your needs. However, if you need to process
+multiple documents, it may be advantageous to create a single instance
+of the `markdown.Markdown` class and pass multiple documents through it.
+
+### `markdown.markdown(text [, **kwargs])`
+
+The following options are available on the `markdown.markdown` function:
+
+* __`text`__ (required): The source text string.
+
+ Note that Python-Markdown expects **Unicode** as input (although
+ a simple ASCII string may work) 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. For example:
+
+ input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
+ text = input_file.read()
+ html = markdown.markdown(text)
+
+ If you want to write the output to disk, you must encode it yourself:
+
+ output_file = codecs.open("some_file.html", "w",
+ encoding="utf-8",
+ errors="xmlcharrefreplace"
+ )
+ output_file.write(html)
+
+* __`extensions`__: A list of extensions.
+
+ Python-Markdown provides an API for third parties to write extensions to
+ the parser adding their own additions or changes to the syntax. A few
+ commonly used extensions are shipped with the markdown library. See
+ the [extension documentation](extensions/index.html) for a list of
+ available extensions.
+
+ The list of extensions may contain instances of extensions or stings of
+ extension names. If an extension name is provided as a string, the
+ extension must be importable as a python module either within the
+ `markdown.extensions` package or on your PYTHONPATH with a name starting
+ with `mdx_`, followed by the name of the extension. Thus,
+ `extensions=['extra']` will first look for the module
+ `markdown.extensions.extra`, then a module named `mdx_extra`.
+
+* __`extension-configs`__: A dictionary of configuration settings for extensions.
+
+ The dictionary must be of the following format:
+
+ extension-configs = {'extension_name_1':
+ [
+ ('option_1', 'value_1'),
+ ('option_2', 'value_2')
+ ],
+ 'extension_name_2':
+ [
+ ('option_1', 'value_1')
+ ]
+ }
+ See the documentation specific to the extension you are using for help in
+ specifying configuration settings for that extension.
+
+* __`output_format`__: Format of output.
+
+ Supported formats are:
+
+ * `"xhtml1"`: Outputs XHTML 1.x. **Default**.
+ * `"xhtml5"`: Outputs XHTML style tags of HTML 5
+ * `"xhtml"`: Outputs latest supported version of XHTML (currently XHTML 1.1).
+ * `"html4"`: Outputs HTML 4
+ * `"html5"`: Outputs HTML style tags of HTML 5
+ * `"html"`: Outputs latest supported version of HTML (currently HTML 4).
+
+ Note that it is suggested that the more specific formats ("xhtml1",
+ "html5", & "html4") be used as "xhtml" or "html" may change in the future
+ if it makes sense at that time. The values can either be lowercase or
+ uppercase.
+
+* __`safe_mode`__: Disallow raw html.
+
+ 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.)
+
+ The following values are accepted:
+
+ * `False` (Default): Raw HTML is passed through unaltered.
+
+ * `replace`: Replace all HTML blocks with the text assigned to
+ `html_replacement_text` To maintain backward compatibility, setting
+ `safe_mode=True` will have the same effect as `safe_mode='replace'`.
+
+ To replace raw HTML with something other than the default, do:
+
+ md = markdown.Markdown(safe_mode='replace',
+ html_replacement_text='--RAW HTML NOT ALLOWED--')
+
+ * `remove`: All raw HTML will be completely stripped from the text with
+ no warning to the author.
+
+ * `escape`: All raw HTML will be escaped and included in the document.
+
+ For example, the following source:
+
+ Foo <b>bar</b>.
+
+ Will result in the following HTML:
+
+ <p>Foo &lt;b&gt;bar&lt;/b&gt;.</p>
+
+ Note that "safe_mode" does not alter the `enable_attributes` option, which
+ could allow someone to inject javascript (i.e., `{@onclick=alert(1)}`). You
+ may also want to set `enable_attributes=False` when using "safe_mode".
+
+* __`html_replacement_text`__: Text used when safe_mode is set to `replace`.
+ Defaults to `[HTML_REMOVED]`.
+
+* __`tab_length`__: Length of tabs in the source. Default: 4
+
+* __`enable_attributes`__: Enable the conversion of attributes. Default: True
+
+* __`smart_emphasis`__: Treat `_connected_words_` intelligently Default: True
+
+* __`lazy_ol`__: Ignore number of first item of ordered lists. Default: True
+
+ Given the following list:
+
+ 4. Apples
+ 5. Oranges
+ 6. Pears
+
+ By default markdown will ignore the fact the the first line started
+ with item number "4" and the HTML list will start with a number "1".
+ If `lazy_ol` is set to `True`, then markdown will output the following
+ HTML:
+
+ <ol>
+ <li start="4">Apples</li>
+ <li>Oranges</li>
+ <li>Pears</li>
+ </ol>
+
+
+### `markdown.markdownFromFile(**kwargs)`
+
+With a few exceptions, `markdown.markdownFromFile` accepts the same options as
+`markdown.markdown`. It does **not** accept a `text` (or Unicode) string.
+Instead, it accepts the following required options:
+
+* __`input`__ (required): The source text file.
+
+ `input` may be set to one of three options:
+
+ * a string which contains a path to a readable file on the file system,
+ * a readable file-like object,
+ * or `None` (default) which will read from `stdin`.
+
+* __`output`__: The target which output is written to.
+
+ `output` may be set to one of three options:
+
+ * a string which contains a path to a writable file on the file system,
+ * a writable file-like object,
+ * or `None` (default) which will write to `stdout`.
+
+* __`encoding`__: The encoding of the source text file. Defaults to
+ "utf-8". The same encoding will always be used for input and output.
+ The 'xmlcharrefreplace' error handler is used when encoding the output.
+
+ **Note:** This is the only place that decoding and encoding of unicode
+ takes place in Python-Markdown. If this rather naive solution does not
+ meet your specific needs, it is suggested that you write your own code
+ to handle your encoding/decoding needs.
+
+### `markdown.Markdown([**kwargs])`
+
+The same options are available when initializing the `markdown.Markdown` class
+as on the `markdown.markdown` function, except that the class does **not**
+accept a source text string on initialization. Rather, the source text string
+must be passed to one of two instance methods:
+
+* `Markdown.convert(source)`
+
+ The `source` text must meet the same requirements as the `text` argument
+ of the `markdown.markdown` function.
+
+ You should also use this method if you want to process multiple strings
+ without creating a new instance of the class for each string.
+
+ md = markdown.Markdown()
+ html1 = md.convert(text1)
+ html2 = md.convert(text2)
+
+ Note that depending on which options and/or extensions are being used,
+ the parser may need its state reset between each call to `convert`.
+
+ html1 = md.convert(text1)
+ md.reset()
+ html2 = md.convert(text2)
+
+ You can also change calls to `reset` togeather:
+
+ html3 = md.reset().convert(text3)
+
+* `Markdown.convertFile(**kwargs)`
+
+ The arguments of this method are identical to the arguments of the same
+ name on the `markdown.markdownFromFile` function (`input`, `output`, and
+ `encoding`). As with the `convert` method, this method should be used to
+ process multiple files without creating a new instance of the class for
+ each document. State may need to be `reset` between each call to
+ `convertFile` as is the case with `convert`.