diff --git a/.gitignore b/.gitignore
index 659c251..e1e9743 100644
--- a/.gitignore
+++ b/.gitignore
@@ -61,3 +61,4 @@ target/
 # Vim
 *.swp
 .DS_Store
+.pytest_cache
diff --git a/docs/conf.py b/docs/conf.py
index 2508839..fa6bfb7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -35,6 +35,10 @@
 #
 # needs_sphinx = '1.0'
 
+source_parsers = {
+   '.md': 'recommonmark.parser.CommonMarkParser',
+}
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -50,8 +54,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The master toctree document.
 master_doc = 'index'
diff --git a/docs/index.rst b/docs/index.rst
index fc5cf7b..b6af6f0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,19 +1,119 @@
-.. mapbox documentation master file, created by
-   sphinx-quickstart on Thu May  3 16:31:16 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+=====================================================
+Mapbox: The Mapbox Platform client library for Python
+=====================================================
 
-Welcome to the Mapbox Python SDK documentation
-==============================================
+.. image:: https://travis-ci.org/mapbox/mapbox-sdk-py.png?branch=master
+   :target: https://travis-ci.org/mapbox/mapbox-sdk-py
+
+.. image:: https://coveralls.io/repos/mapbox/mapbox-sdk-py/badge.png
+   :target: https://coveralls.io/r/mapbox/mapbox-sdk-py
+
+A Python client for Mapbox web services
+
+The Mapbox Python SDK is a low-level client API, not a Resource API such as the ones in `boto3 <http://aws.amazon.com/sdk-for-python/>`__ or `github3.py <https://github3py.readthedocs.org/en/master/>`__. Its methods return objects containing `HTTP responses <http://docs.python-requests.org/en/latest/api/#requests.Response>`__ from the Mapbox API.
+
+Services
+========
+
+- **Analytics V1** `examples <./docs/analytics.md>`__, `website <https://www.mapbox.com/api-documentation/#analytics>`__
+
+  - API usage for services by resource. 
+  - available for premium and enterprise plans.
+
+- **Directions V4** `examples <./docs/directions.md#directions>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#directions>`__
+
+  - Profiles for driving, walking, and cycling
+  - GeoJSON & Polyline formatting
+  - Instructions as text or HTML
+
+- **Distance V1** **DEPRECATED**
+- **Geocoding V5** `examples <./docs/geocoding.md#geocoding>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#geocoding>`__
+
+  - Forward (place names ⇢ longitude, latitude)
+  - Reverse (longitude, latitude ⇢ place names)
+
+- **Map Matching V4** `examples <./docs/mapmatching.md#map-matching>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#map-matching>`__
+
+  - Snap GPS traces to OpenStreetMap data
+
+- **Static Maps V4** `examples <./docs/static.md#static-maps>`__, `website <https://www.mapbox.com/api-documentation/pages/static_classic.html>`__
+
+  - Generate standalone images from existing Mapbox *mapids* (tilesets)
+  - Render with GeoJSON overlays
+  
+- **Static Styles V1** `examples <./docs/static.md#static-maps>`__, `website <https://www.mapbox.com/api-documentation/#static>`__
+
+  - Generate standalone images from existing Mapbox *styles*
+  - Render with GeoJSON overlays
+  - Adjust pitch and bearing, decimal zoom levels
+  
+- **Surface V4** `examples <./docs/surface.md#surface>`__, `website <https://www.mapbox.com/developers/api/surface/>`__
+
+  - Interpolates values along lines. Useful for elevation traces.
+
+- **Uploads V1** `examples <./docs/uploads.md#uploads>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#uploads>`__
+
+  - Upload data to be processed and hosted by Mapbox.
+
+- **Datasets V1** `examples <./docs/datasets.md#datasets>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#datasets>`__
+
+  - Manage editable collections of GeoJSON features
+  - Persistent storage for custom geographic data
+
+Please note that there may be some lag between the release of new Mapbox web
+services and releases of this package.
+
+Installation
+============
+
+.. code:: bash
+
+    $ pip install mapbox
+
+Testing
+=======
+
+.. code:: bash
+
+    $ pip install -e .[test]
+    $ python -m pytest
+
+To run the examples as integration tests on your own Mapbox account
+
+.. code:: bash
+
+    $ MAPBOX_ACCESS_TOKEN="MY_ACCESS_TOKEN" python -m pytest --doctest-glob='*.md' docs/*.md
+
+See Also
+========
+
+* Command line interface: https://github.com/mapbox/mapbox-cli-py
+* Javascript SDK: https://github.com/mapbox/mapbox-sdk-js
+
+Documentation
+=============
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :maxdepth: 1
 
+   access_tokens.md
+   datasets.md
+   geocoding.md
+   matrix.md
+   surface.md
+   directions.md
+   input_features.md
+   static.md
+   uploads.md
+   analytics.md
+   distance.md
+   mapmatching.md
+   static_style.md
    api/mapbox.rst
    api/mapbox.services.rst
    api/modules.rst
 
+
 Indices and tables
 ==================