aboutsummaryrefslogtreecommitdiffstats
path: root/docs/reference.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2013-02-19 16:33:36 -0500
committerWaylan Limberg <waylan@gmail.com>2013-02-19 16:33:36 -0500
commit8aa2fc7b5138fd97ded7dd1e70103532a9fd6583 (patch)
treea85aec909892c3e9ca08d23369f0e743e3beb177 /docs/reference.txt
parent3b732805676969fdf61ac3214c42ab94e96da0ea (diff)
downloadmarkdown-8aa2fc7b5138fd97ded7dd1e70103532a9fd6583.tar.gz
markdown-8aa2fc7b5138fd97ded7dd1e70103532a9fd6583.tar.bz2
markdown-8aa2fc7b5138fd97ded7dd1e70103532a9fd6583.zip
Various changes to docs for updated changes, clarity, and to fix typos.
Diffstat (limited to 'docs/reference.txt')
-rw-r--r--docs/reference.txt81
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 &lt;b&gt;bar&lt;/b&gt;.</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 }