/
usr
/
share
/
doc
/
python2-markdown-2.4.1
/
Upload File
HOME
<!DOCTYPE html> <html> <head> <meta charset=utf-8> <title>Library Reference — Python Markdown</title> <link rel="stylesheet" href="default.css" type="text/css"> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="siteindex.html" title="General Index">index</a></li> <li class="right"> <a href="cli.html" title="Command Line" accesskey="N">next</a> |</li> <li class="right"> <a href="install.html" title="Installation" accesskey="P">previous</a> |</li> <li><img src="py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="index.html">Python Markdown v2.4.1 documentation</a> »</li> <li><a href="reference.html">Library Reference</a> »</li> </ul> </div> <!-- .related --> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <h1 id="using-markdown-as-a-python-library">Using Markdown as a Python Library<a class="headerlink" href="#using-markdown-as-a-python-library" title="Permanent link">¶</a></h1> <p>First and foremost, Python-Markdown is intended to be a python library module used by various projects to convert Markdown syntax into HTML.</p> <h2 id="the-basics">The Basics<a class="headerlink" href="#the-basics" title="Permanent link">¶</a></h2> <p>To use markdown as a module:</p> <pre><code>import markdown html = markdown.markdown(your_text_string) </code></pre> <h2 id="the-details">The Details<a class="headerlink" href="#the-details" title="Permanent link">¶</a></h2> <p>Python-Markdown provides two public functions (<a href="#markdown"><code>markdown.markdown</code></a> and <a href="#markdownFromFile"><code>markdown.markdownFromFile</code></a>) both of which wrap the public class <a href="#Markdown"><code>markdown.Markdown</code></a>. If you’re processing one document at a time, these functions will serve your needs. However, if you need to process multiple documents, it may be advantageous to create a single instance of the <code>markdown.Markdown</code> class and pass multiple documents through it. If you do use a single instance though, make sure to call the <code>reset</code> method appropriately (<a href="#convert">see below</a>).</p> <h3 id="markdown"><code>markdown.markdown (text [, **kwargs])</code><a class="headerlink" href="#markdown" title="Permanent link">¶</a></h3> <p>The following options are available on the <code>markdown.markdown</code> function:</p> <ul> <li> <p><strong id="text"><code>text</code></strong> (required): The source unicode string.</p> <div class="admonition note"> <p class="admonition-title">Important</p> <p>Python-Markdown expects <strong>Unicode</strong> as input (although some simple ASCII strings <em>may</em> 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:</p> <pre><code>input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8") text = input_file.read() html = markdown.markdown(text) </code></pre> <p>If you want to write the output to disk, you <em>must</em> encode it yourself:</p> <pre><code>output_file = codecs.open("some_file.html", "w", encoding="utf-8", errors="xmlcharrefreplace" ) output_file.write(html) </code></pre> </div> </li> <li> <p><strong id="extensions"><code>extensions</code></strong>: A list of extensions.</p> <p>Python-Markdown provides an <a href="extensions/api.html">API</a> 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 <a href="extensions/index.html">extension documentation</a> for a list of available extensions.</p> <p>The list of extensions may contain instances of extensions and/or strings of extension names. </p> <pre><code>extensions=[MyExtension(), 'path.to.my.ext', 'extra'] </code></pre> <p>When passing in extension instances, each class instance must be a subclass of <code>markdown.extensions.Extension</code> and any configuration options should be defined when initiating the class instance rather than using the <a href="#extension_configs">extension_configs</a> keyword. For example:</p> <pre><code>from markdown.extensions import Extension class MyExtension(Extension): # define your extension here... markdown.markdown(text, extensions=[MyExtension(configs={'option': 'value'})) </code></pre> <p>If an extension name is provided as a string, the extension must be importable as a python module on your PYTHONPATH. Python’s dot notation is supported. Therefore, to import the ‘extra’ extension, one could do <code>extensions=['markdown.extensions.extra']</code> However, if no dots are provided in the string (<code>extensions=['extra']</code>) Markdown will first look for the module <code>markdown.extensions.extra</code> (the built-in extension), then a module named <code>mdx_extra</code> (‘mdx_’ will be appended to the beginning of the string) at the root of your PYTHONPATH. </p> <p>When loading an extension by name (as a string), you may either pass in configuration settings to the extension using the <a href="#extension_configs">extension_configs</a> keyword or by appending the settings to the name in the following format:</p> <pre><code>extensions=['name(option1=value,option2=value)'] </code></pre> <p>Note that there are no quotes or whitespace in the above format, which severely limits how it can be used. For more complex settings, it is suggested that the <a href="#extension_configs">extension_configs</a> keyword be used or an instance of a class be passed in.</p> <div class="admonition seealso"> <p class="admonition-title">See Also</p> <p>See the documentation of the <a href="extensions/api.html">Extension API</a> for assistance in creating extensions.</p> </div> </li> <li> <p><strong id="extension_configs"><code>extension_configs</code></strong>: A dictionary of configuration settings for extensions.</p> <p>Any configuration settings will only be passed to extensions loaded by name (as a string). When loading extensions as class instances, pass the configuration settings directly to the class when initializing it. </p> <p>The dictionary of configuration settings must be in the following format:</p> <pre><code>extension_configs = {'extension_name_1': [ ('option_1', 'value_1'), ('option_2', 'value_2') ], 'extension_name_2': [ ('option_1', 'value_1') ] } </code></pre> <p>See the documentation specific to the extension you are using for help in specifying configuration settings for that extension.</p> </li> <li> <p><strong id="output_format"><code>output_format</code></strong>: Format of output. </p> <p>Supported formats are:</p> <ul> <li><code>"xhtml1"</code>: Outputs XHTML 1.x. <strong>Default</strong>.</li> <li><code>"xhtml5"</code>: Outputs XHTML style tags of HTML 5</li> <li><code>"xhtml"</code>: Outputs latest supported version of XHTML (currently XHTML 1.1).</li> <li><code>"html4"</code>: Outputs HTML 4</li> <li><code>"html5"</code>: Outputs HTML style tags of HTML 5</li> <li><code>"html"</code>: Outputs latest supported version of HTML (currently HTML 4).</li> </ul> <p>The values can be in either lowercase or uppercase.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>It is suggested that the more specific formats (“xhtml1”, “html5”, & “html4”) be used as the more general formats (“xhtml” or “html”) may change in the future if it makes sense at that time. </p> </div> </li> <li> <p><strong id="safe_mode"><code>safe_mode</code></strong>: Disallow raw html.</p> <p>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.)</p> <p>The following values are accepted:</p> <ul> <li> <p><code>False</code> (Default): Raw HTML is passed through unaltered.</p> </li> <li> <p><code>replace</code>: Replace all HTML blocks with the text assigned to <code>html_replacement_text</code> To maintain backward compatibility, setting <code>safe_mode=True</code> will have the same effect as <code>safe_mode='replace'</code>. </p> <p>To replace raw HTML with something other than the default, do:</p> <pre><code>md = markdown.Markdown(safe_mode='replace', html_replacement_text='--RAW HTML NOT ALLOWED--') </code></pre> </li> <li> <p><code>remove</code>: All raw HTML will be completely stripped from the text with no warning to the author.</p> </li> <li> <p><code>escape</code>: All raw HTML will be escaped and included in the document.</p> <p>For example, the following source:</p> <pre><code>Foo <b>bar</b>. </code></pre> <p>Will result in the following HTML:</p> <pre><code><p>Foo &lt;b&gt;bar&lt;/b&gt;.</p> </code></pre> </li> </ul> <div class="admonition note"> <p class="admonition-title">Note</p> <p>“safe_mode” also alters the default value for the <a href="#enable_attributes"><code>enable_attributes</code></a> option.</p> </div> <div class="admonition seealso"> <p class="admonition-title">See Also</p> <p>HTML sanitizers (like <a href="https://github.com/jsocol/bleach">Bleach</a>) may provide a better solution for dealing with markdown text submitted by untrusted users. That way, both the HTML generated by Markdown and user submited raw HTML are fully sanitized.</p> <pre><code>import markdown import bleach html = bleach.clean(markdown.markdown(evil_text)) </code></pre> </div> </li> <li> <p><strong id="html_replacement_text"><code>html_replacement_text</code></strong>: Text used when safe_mode is set to <code>replace</code>. Defaults to <code>[HTML_REMOVED]</code>.</p> </li> <li> <p><strong id="tab_length"><code>tab_length</code></strong>: Length of tabs in the source. Default: 4</p> </li> <li> <p><strong id="enable_attributes"><code>enable_attributes</code></strong>: Enable the conversion of attributes. Defaults to <code>True</code>, unless <a href="#safe_mode"><code>safe_mode</code></a> is enabled, in which case the default is <code>False</code>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p><code>safe_mode</code> only overrides the default. If <code>enable_attributes</code> is explicitly set, the explicit value is used regardless of <code>safe_mode</code>. However, this could potentially allow an untrusted user to inject JavaScript into your documents.</p> </div> </li> <li> <p><strong id="smart_emphasis"><code>smart_emphasis</code></strong>: Treat <code>_connected_words_</code> intelligently Default: True</p> </li> <li> <p><strong id="lazy_ol"><code>lazy_ol</code></strong>: Ignore number of first item of ordered lists. Default: True</p> <p>Given the following list:</p> <pre><code>4. Apples 5. Oranges 6. Pears </code></pre> <p>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 <code>lazy_ol</code> is set to <code>False</code>, then markdown will output the following HTML:</p> <pre><code><ol> <li start="4">Apples</li> <li>Oranges</li> <li>Pears</li> </ol> </code></pre> </li> </ul> <h3 id="markdownFromFile"><code>markdown.markdownFromFile (**kwargs)</code><a class="headerlink" href="#markdownFromFile" title="Permanent link">¶</a></h3> <p>With a few exceptions, <code>markdown.markdownFromFile</code> accepts the same options as <code>markdown.markdown</code>. It does <strong>not</strong> accept a <code>text</code> (or Unicode) string. Instead, it accepts the following required options:</p> <ul> <li> <p><strong id="input"><code>input</code></strong> (required): The source text file.</p> <p><code>input</code> may be set to one of three options:</p> <ul> <li>a string which contains a path to a readable file on the file system,</li> <li>a readable file-like object,</li> <li>or <code>None</code> (default) which will read from <code>stdin</code>.</li> </ul> </li> <li> <p><strong id="output"><code>output</code></strong>: The target which output is written to.</p> <p><code>output</code> may be set to one of three options:</p> <ul> <li>a string which contains a path to a writable file on the file system,</li> <li>a writable file-like object,</li> <li>or <code>None</code> (default) which will write to <code>stdout</code>.</li> </ul> </li> <li> <p><strong id="encoding"><code>encoding</code></strong>: 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.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>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.</p> </div> </li> </ul> <h3 id="Markdown"><code>markdown.Markdown ([**kwargs])</code><a class="headerlink" href="#Markdown" title="Permanent link">¶</a></h3> <p>The same options are available when initializing the <code>markdown.Markdown</code> class as on the <a href="#markdown"><code>markdown.markdown</code></a> function, except that the class does <strong>not</strong> accept a source text string on initialization. Rather, the source text string must be passed to one of two instance methods:</p> <ul> <li> <p><code id="convert">Markdown.convert(source)</code></p> <p>The <code>source</code> text must meet the same requirements as the <a href="#text"><code>text</code></a> argument of the <a href="#markdown"><code>markdown.markdown</code></a> function.</p> <p>You should also use this method if you want to process multiple strings without creating a new instance of the class for each string.</p> <pre><code>md = markdown.Markdown() html1 = md.convert(text1) html2 = md.convert(text2) </code></pre> <p>Depending on which options and/or extensions are being used, the parser may need its state reset between each call to <code>convert</code>, otherwise performance can degrade drastically:</p> <pre><code>html1 = md.convert(text1) md.reset() html2 = md.convert(text2) </code></pre> <p>To make this easier, you can also chain calls to <code>reset</code> together:</p> <pre><code>html3 = md.reset().convert(text3) </code></pre> </li> <li> <p><code id="convertFile">Markdown.convertFile(**kwargs)</code></p> <p>The arguments of this method are identical to the arguments of the same name on the <code>markdown.markdownFromFile</code> function (<a href="#input"><code>input</code></a>, <a href="#output"><code>output</code></a>, and <a href="#encoding"><code>encoding</code></a>). As with the <a href="#convert"><code>convert</code></a> 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 <code>reset</code> between each call to <code>convertFile</code> as is the case with <code>convert</code>.</p> </li> </ul> </div> <!-- .body --> </div> <!-- .bodywrapper --> </div> <!-- .documentwrapper --> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3>Table Of Contents</h3> <div class="toc"> <ul> <li><a href="#using-markdown-as-a-python-library">Using Markdown as a Python Library</a><ul> <li><a href="#the-basics">The Basics</a></li> <li><a href="#the-details">The Details</a><ul> <li><a href="#markdown">markdown.markdown (text [, **kwargs])</a></li> <li><a href="#markdownFromFile">markdown.markdownFromFile (**kwargs)</a></li> <li><a href="#Markdown">markdown.Markdown ([**kwargs])</a></li> </ul> </li> </ul> </li> </ul> </div> <h4>Previous topic</h4> <p class="topless"><a href="install.html" title="previous chapter">Installation</a></p> <h4>Next topic</h4> <p class="topless"><a href="cli.html" title="next chapter">Command Line</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="https://github.com/waylan/Python-Markdown/issues" >Report a Bug</a></li> <li><a href="reference.txt" rel="nofollow">Show Source</a></li> </ul> </div> <!-- .sphinxsidebarwrapper --> </div> <!-- .sphinxsidebar --> <div class="clearer"></div> </div> <!-- .document --> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="siteindex.html" title="General Index">index</a></li> <li class="right"> <a href="cli.html" title="Command Line" accesskey="N">next</a> |</li> <li class="right"> <a href="install.html" title="Installation" accesskey="P">previous</a> |</li> <li><img src="py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="index.html">Python Markdown v2.4.1 documentation</a> »</li> <li><a href="reference.html">Library Reference</a> »</li> </ul> </div> <!-- .related --> <div class="footer">© 2010-2012 Python Markdown Project</div> </body> </html>