diff options
Diffstat (limited to 'docs/reference.txt')
| -rw-r--r-- | docs/reference.txt | 81 |
1 files changed, 50 insertions, 31 deletions
diff --git a/docs/reference.txt b/docs/reference.txt index 8117e69..fa32972 100644 --- a/docs/reference.txt +++ b/docs/reference.txt @@ -34,24 +34,25 @@ it. The following options are available on the `markdown.markdown` function: -* __`text`__{: #text } (required): The source text string. +* __`text`__{: #text } (required): The source unicode 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: + !!! note "Important" + Python-Markdown expects **Unicode** as input (although + some simple ASCII strings *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) + 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: + 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) + output_file = codecs.open("some_file.html", "w", + encoding="utf-8", + errors="xmlcharrefreplace" + ) + output_file.write(html) * __`extensions`__{: #extensions }: A list of extensions. @@ -98,8 +99,9 @@ The following options are available on the `markdown.markdown` function: suggested that the [extension_configs](#extension_configs) keyword be used or an instance of a class be passed in. - See the documentation of the [Extension API](extensions/api.html) for - assistance in creating extensions. + !!! seealso "See Also" + See the documentation of the [Extension API](extensions/api.html) for + assistance in creating extensions. * __`extension_configs`__{: #extension_configs }: A dictionary of configuration settings for extensions. @@ -134,10 +136,12 @@ The following options are available on the `markdown.markdown` function: * `"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. + The values can be in either lowercase or uppercase. + + !!! warning + 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. * __`safe_mode`__{: #safe_mode }: Disallow raw html. @@ -145,7 +149,7 @@ The following options are available on the `markdown.markdown` function: 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. @@ -172,8 +176,21 @@ The following options are available on the `markdown.markdown` function: <p>Foo <b>bar</b>.</p> - Note that "safe_mode" also alters the default value for the - [`enable_attributes`](#enable_attributes) option. + !!! Note + "safe_mode" also alters the default value for the + [`enable_attributes`](#enable_attributes) option. + + !!! seealso "See Also" + HTML sanitizers (like [Bleach]) 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. + + import markdown + import bleach + html = bleach.clean(markdown.markdown(evil_text)) + +[Bleach]: https://github.com/jsocol/bleach * __`html_replacement_text`__{: #html_replacement_text }: Text used when safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`. @@ -184,10 +201,11 @@ The following options are available on the `markdown.markdown` function: attributes. Defaults to `True`, unless [`safe_mode`](#safe_mode) is enabled, in which case the default is `False`. - Note that `safe_mode` only overrides the default. If `enable_attributes` - is explicitly set, the explicit value is used regardless of `safe_mode`. - However, this could potentially allow an untrusted user to inject - JavaScript into your documents. + !!! Note + `safe_mode` only overrides the default. If `enable_attributes` + is explicitly set, the explicit value is used regardless of `safe_mode`. + However, this could potentially allow an untrusted user to inject + JavaScript into your documents. * __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` intelligently Default: True @@ -239,10 +257,11 @@ Instead, it accepts the following required options: 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. + !!! 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])` {: #Markdown } |