Switch docs to MKDocs (#602)

Fixes #601. Merged in 6f87b32 from the md3 branch and did a lot of cleanup.

Changes include:

* Removed old docs build tool, templates, etc.

* Added MkDocs config file, etc.

* filename.txt => filename.md

* pythonhost.org/Markdown => Python-Markdown.github.io

* Markdown lint and other cleanup.

* Automate pages deployment in makefile with `mkdocs gh-deploy`

    Assumes a git remote is set up named "pages". Do

        git remote add pages https://github.com/Python-Markdown/Python-Markdown.github.io.git

    ... before running `make deploy` the first time.

1 files changed, 111 insertions, 0 deletions

diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..d21b5c5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,111 @@
+title: Python-Markdown
+
+Python-Markdown
+===============
+
+This is a Python implementation of John Gruber's
+[Markdown](http://daringfireball.net/projects/markdown/).
+It is almost completely compliant with the reference implementation,
+though there are a few very minor [differences](#differences). See John's
+[Syntax Documentation](http://daringfireball.net/projects/markdown/syntax)
+for the syntax rules.
+
+See the [installation instructions](install.md) to get started.
+
+Goals
+-----
+
+The Python-Markdown project is developed with the following goals in mind:
+
+* Maintain a Python 2 *and* Python 3 library (with an optional CLI wrapper)
+  suited to use in web server environments (never raise an exception, never
+  write to stdout, etc.) as an implementation of the markdown parser that
+  follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax)
+  and the behavior of the original (markdown.pl) implementation as reasonably as
+  possible (see [differences](#differences) for a few exceptions).
+
+* Provide an [Extension API](extensions/api.md) which makes it possible
+  to change and/or extend the behavior of the parser.
+
+Features
+--------
+
+In addition to the basic markdown syntax, Python-Markdown supports the following
+features:
+
+* __International Input__
+
+    Python-Markdown will accept [input](reference.md#text) in any language
+    supported by Unicode including bi-directional text. In fact the test suite
+    includes documents written in Russian and Arabic.
+
+* __Extensions__
+
+    Various [extensions](extensions/index.md) are provided (including
+    [extra](extensions/extra.md)) to change and/or extend the base syntax.
+    Additionally, a public [Extension API](extensions/api.md) is available
+    to write your own extensions.
+
+* __Output Formats__
+
+    Python-Markdown can output documents with either HTML or XHTML styel tags.
+    See the [Library Reference](reference.md#output_format) for details.
+
+* __Command Line Interface__
+
+    In addition to being a Python Library, a
+    [command line script](cli.md) is available for your convenience.
+
+Differences
+-----------
+
+While Python-Markdown strives to fully implement markdown as described in the
+[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules
+can be interpreted in different ways and different implementations
+occasionally vary in their behavior (see the
+[Babelmark FAQ](http://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations)
+for some examples). Known and intentional differences found in Python-Markdown
+are summarized below:
+
+* __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.md#smart_emphasis) for details.
+
+* __Indentation/Tab Length__
+
+    The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list)
+    clearly state that when a list item consists of multiple paragraphs, "each
+    subsequent paragraph in a list item **must** be indented by either 4 spaces
+    or one tab" (emphasis added). However, many implementations do not enforce
+    this rule and allow less than 4 spaces of indentation. The implementers of
+    Python-Markdown consider it a bug to not enforce this rule.
+
+    This applies to any block level elements nested in a list, including
+    paragraphs, sub-lists, blockquotes, code blocks, etc. They **must** always
+    be indented by at least four spaces (or one tab) for each level of nesting.
+
+    In the event that one would prefer different behavior,
+    [tab_length](reference.md#tab_length) can be set to whatever length is
+    desired. Be warned however, as this will affect indentation for all aspects
+    of the syntax (including root level code blocks).
+
+* __Consecutive Lists__
+
+    While the syntax rules are not clear on this, many implementations (including
+    the original) do not end one list and start a second list when the list marker
+    (asterisks, pluses, hyphens, and numbers) changes. For consistency,
+    Python-Markdown maintains the same behavior with no plans to change in the
+    foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.md)
+    is available to provide a less surprising behavior.
+
+Support
+-------
+
+You may ask for help and discuss various other issues on the [mailing list][]
+and report bugs on the [bug tracker][].
+
+[mailing list]: http://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
+[bug tracker]: http://github.com/Python-Markdown/markdown/issues