diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cli.md | 6 | ||||
| -rw-r--r-- | docs/extensions/api.md | 47 | ||||
| -rw-r--r-- | docs/index.md | 14 | ||||
| -rw-r--r-- | docs/reference.md | 74 |
4 files changed, 70 insertions, 71 deletions
diff --git a/docs/cli.md b/docs/cli.md index 6048ecc..9babc50 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -14,14 +14,14 @@ of Markdown, you may not have them installed, or you may prefer to use Python-Markdown's various extensions. Generally, you will want to have the Markdown library fully installed on your -system (``setup.py install`` or ``easy_install markdown``) to run the command -line script. +system to run the command line script. See the +[Installation instructions](install.html) for details. Assuming the `python` executable is on your system path, just run the following: python -m markdown [options] [args] -That will run the module as a script. Note that on older python versions (2.5 +That will run the module as a script. Note that on older Python versions (2.5 and 2.6), you may need to specify the appropriate module: python -m markdown.__main__ [options] [args] diff --git a/docs/extensions/api.md b/docs/extensions/api.md index c27abf0..8886b8f 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -7,9 +7,6 @@ next_url: ../test_suite.html Writing Extensions for Python-Markdown ====================================== -Overview --------- - Python-Markdown includes an API for extension writers to plug their own custom functionality and/or syntax into the parser. There are preprocessors which allow you to alter the source before it is passed to the parser, @@ -25,20 +22,8 @@ Additionally, reading the source of some [Available Extensions][] may be helpful. For example, the [Footnotes][] extension uses most of the features documented here. -* [Preprocessors][] -* [InlinePatterns][] -* [Treeprocessors][] -* [Postprocessors][] -* [BlockParser][] -* [Working with the ElementTree][] -* [Integrating your code into Markdown][] - * [extendMarkdown][] - * [OrderedDict][] - * [registerExtension][] - * [Config Settings][] - * [makeExtension][] - -<h3 id="preprocessors">Preprocessors</h3> +Preprocessors {: #preprocessors } +--------------------------------- Preprocessors munge the source text before it is passed into the Markdown core. This is an excellent place to clean up bad syntax, extract things the @@ -65,7 +50,8 @@ A pseudo example: new_lines.append(line) return new_lines -<h3 id="inlinepatterns">Inline Patterns</h3> +Inline Patterns {: #inlinepatterns } +------------------------------------ Inline Patterns implement the inline HTML element syntax for Markdown such as ``*emphasis*`` or ``[links](http://example.com)``. Pattern objects should be @@ -140,7 +126,8 @@ or use as well. Read through the source and see if there is anything you can use. You might even get a few ideas for different approaches to your specific situation. -<h3 id="treeprocessors">Treeprocessors</h3> +Treeprocessors {: #treeprocessors } +----------------------------------- Treeprocessors manipulate an ElemenTree object after it has passed through the core BlockParser. This is where additional manipulation of the tree takes @@ -163,7 +150,8 @@ A pseudo example: For specifics on manipulating the ElementTree, see [Working with the ElementTree][] below. -<h3 id="postprocessors">Postprocessors</h3> +Postprocessors {: #postprocessors } +----------------------------------- Postprocessors manipulate the document after the ElementTree has been serialized into a string. Postprocessors should be used to work with the @@ -183,7 +171,8 @@ contents to a document: def run(self, text): return MYMARKERRE.sub(MyToc, text) -<h3 id="blockparser">BlockParser</h3> +BlockParser {: #blockparser } +----------------------------- Sometimes, pre/tree/postprocessors and Inline Patterns aren't going to do what you need. Perhaps you want a new type of block type that needs to be integrated @@ -309,7 +298,8 @@ the ``BlockParser``. The new class would have to provide the same public API. However, be aware that other extensions may expect the core parser provided and will not work with such a drastically different parser. -<h3 id="working_with_et">Working with the ElementTree</h3> +Working with the ElementTree {: #working_with_et } +-------------------------------------------------- As mentioned, the Markdown parser converts a source document to an [ElementTree][] object before serializing that back to Unicode text. @@ -363,7 +353,8 @@ For more information about working with ElementTree see the ElementTree [Documentation](http://effbot.org/zone/element-index.htm) ([Python Docs](http://docs.python.org/lib/module-xml.etree.ElementTree.html)). -<h3 id="integrating_into_markdown">Integrating Your Code Into Markdown</h3> +Integrating Your Code Into Markdown {: #integrating_into_markdown } +------------------------------------------------------------------- Once you have the various pieces of your extension built, you need to tell Markdown about them and ensure that they are run in the proper sequence. @@ -383,7 +374,7 @@ instances of your processors and patterns into the appropriate location in an OrderedDict, remove a built-in instance, or replace a built-in instance with your own. -<h4 id="extendmarkdown">extendMarkdown</h4> +### extendMarkdown {: #extendmarkdown } The ``extendMarkdown`` method of a ``markdown.extensions.Extension`` class accepts two arguments: @@ -433,7 +424,7 @@ A simple example: # Insert instance of 'mypattern' before 'references' pattern md.inlinePatterns.add('mypattern', MyPattern(md), '<references') -<h4 id="ordereddict">OrderedDict</h4> +### OrderedDict {: #ordereddict } An OrderedDict is a dictionary like object that retains the order of it's items. The items are ordered in the order in which they were appended to @@ -518,7 +509,7 @@ To change the location of an existing item: t.link('somekey', '<otherkey') -<h4 id="registerextension">registerExtension</h4> +### registerExtension {: #registerextension } Some extensions may need to have their state reset between multiple runs of the Markdown class. For example, consider the following use of the [Footnotes][] @@ -550,7 +541,7 @@ note that ``reset`` will be called on each registered extension after it is initialized the first time. Keep that in mind when over-riding the extension's ``reset`` method. -<h4 id="configsettings">Config Settings</h4> +### Config Settings {: #configsettings } If an extension uses any parameters that the user may want to change, those parameters should be stored in ``self.config`` of your @@ -569,7 +560,7 @@ values, and should be converted at run time. For example: i = int(self.getConfig("SOME_PARAM")) -<h4 id="makeextension">makeExtension</h4> +### makeExtension {: #makeextension } Each extension should ideally be placed in its own module starting with the ``mdx_`` prefix (e.g. ``mdx_footnotes.py``). The module must diff --git a/docs/index.md b/docs/index.md index fb48399..570f36b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,16 +21,16 @@ features: * __International Input__ - Python-Markdown will accept input in any language supported by Unicode - including bi-directional text. In fact the test suite includes documents - written in Russian and Arabic. + Python-Markdown will accept [input](reference.html#text) in any language + supported by Unicode including bi-directional text. In fact the test suite + includes documents written in Russian and Arabic. * __Middle-Word Emphasis__ Python-Markdown defaults to ignoring middle-word emphasis. In other words, `some_long_filename.txt` will not become `some<em>long</em>filename.txt`. This can be switched off if desired. See the - [Library Reference](reference.html) for details. + [Library Reference](reference.html#smart_emphasis) for details. * __Extensions__ @@ -41,13 +41,15 @@ features: * __Output Formats__ - Python-Markdown can output documents in HTML4, XHTML and HTML5. + Python-Markdown can output documents in HTML4, XHTML and HTML5. See the + [Library Reference](reference.html#output_format) for details. * __"Safe Mode"__ When using Python-Markdown to parse input from untrusted users on the web, the handling of raw HTML can be controlled in various ways to prevent - harmful code from being injected into your site. + harmful code from being injected into your site. See the + [Library Reference](reference.html#safe_mode) for details. * __Command Line Interface__ diff --git a/docs/reference.md b/docs/reference.md index 16735c7..daf24ac 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -22,21 +22,22 @@ To use markdown as a module: 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. +Python-Markdown provides two public functions ([`markdown.markdown`](#markdown) +and [`markdown.markdownFromFile`](#markdownFromFile)) both of which wrap the +public class [`markdown.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])` +### `markdown.markdown (text [, **kwargs])` {: #markdown } The following options are available on the `markdown.markdown` function: -* __`text`__ (required): The source text string. +* __`text`__{: #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. + 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: @@ -52,7 +53,7 @@ The following options are available on the `markdown.markdown` function: ) output_file.write(html) -* __`extensions`__: A list of extensions. +* __`extensions`__{: #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 @@ -68,7 +69,8 @@ The following options are available on the `markdown.markdown` function: `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. +* __`extension-configs`__{: #extensions_configs }: A dictionary of + configuration settings for extensions. The dictionary must be of the following format: @@ -85,7 +87,7 @@ The following options are available on the `markdown.markdown` function: See the documentation specific to the extension you are using for help in specifying configuration settings for that extension. -* __`output_format`__: Format of output. +* __`output_format`__{: #output_format }: Format of output. Supported formats are: @@ -101,7 +103,7 @@ The following options are available on the `markdown.markdown` function: if it makes sense at that time. The values can either be lowercase or uppercase. -* __`safe_mode`__: Disallow raw html. +* __`safe_mode`__{: #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" @@ -138,16 +140,19 @@ The following options are available on the `markdown.markdown` function: 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]`. +* __`html_replacement_text`__{: #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 +* __`tab_length`__{: #tab_length }: Length of tabs in the source. Default: 4 -* __`enable_attributes`__: Enable the conversion of attributes. Default: True +* __`enable_attributes`__{: #enable_attributes}: Enable the conversion of + attributes. Default: True -* __`smart_emphasis`__: Treat `_connected_words_` intelligently Default: True +* __`smart_emphasis`__{: #smart_emphasis }: Treat `_connected_words_` + intelligently Default: True -* __`lazy_ol`__: Ignore number of first item of ordered lists. Default: True +* __`lazy_ol`__{: #lazy_ol }: Ignore number of first item of ordered lists. + Default: True Given the following list: @@ -167,13 +172,13 @@ The following options are available on the `markdown.markdown` function: </ol> -### `markdown.markdownFromFile(**kwargs)` +### `markdown.markdownFromFile (**kwargs)` {: #markdownFromFile } 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`__{: #input } (required): The source text file. `input` may be set to one of three options: @@ -181,7 +186,7 @@ Instead, it accepts the following required options: * a readable file-like object, * or `None` (default) which will read from `stdin`. -* __`output`__: The target which output is written to. +* __`output`__{: #output }: The target which output is written to. `output` may be set to one of three options: @@ -189,8 +194,8 @@ Instead, it accepts the following required options: * 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. +* __`encoding`__{: #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 @@ -198,17 +203,17 @@ Instead, it accepts the following required options: meet your specific needs, it is suggested that you write your own code to handle your encoding/decoding needs. -### `markdown.Markdown([**kwargs])` +### `markdown.Markdown ([**kwargs])` {: #Markdown } 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: +as on the [`markdown.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)` +* `Markdown.convert(source)` {: #convert } - The `source` text must meet the same requirements as the `text` argument - of the `markdown.markdown` function. + The `source` text must meet the same requirements as the [`text`](#text) + argument of the [`markdown.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. @@ -228,11 +233,12 @@ must be passed to one of two instance methods: html3 = md.reset().convert(text3) -* `Markdown.convertFile(**kwargs)` +* `Markdown.convertFile(**kwargs)` {: #convertFile } 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 + name on the `markdown.markdownFromFile` function ([`input`](#input), + [`output`](#output), and [`encoding`](#encoding)). As with the + [`convert`](#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`. |