From 9c2830f7b0273ae399b771a7d9780ee7a7430fc4 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan@gmail.com>
Date: Wed, 7 Mar 2012 08:43:36 -0500
Subject: Added a bunch of internal links to the docs.

---
 docs/cli.md            |  6 ++--
 docs/extensions/api.md | 47 +++++++++++++-------------------
 docs/index.md          | 14 ++++++----
 docs/reference.md      | 74 +++++++++++++++++++++++++++-----------------------
 4 files changed, 70 insertions(+), 71 deletions(-)

(limited to 'docs')

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`.
-- 
cgit v1.2.3