diff --git a/docs/contributing.md b/docs/contributing.md
index 764cda17..c3988004 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,5 +1,6 @@
-Contributing
-============
+---
+title: Contributing
+---
 
 Wheel-building can be pretty complex. I expect users to find many edge-cases - please help the rest of the community out by documenting these, adding features to support them, and reporting bugs.
 
diff --git a/docs/extra.css b/docs/extra.css
index ddebc211..2cee641f 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -26,6 +26,14 @@ code, pre, tt {
 
 h1, h2, h3, h4, h5, h6 {
     margin-top: 2em;
+    border-bottom: 1px solid  #e1e4e5;
+    margin-bottom: 0.8em;
+    padding-bottom: 0.2em;
+
+}
+
+.rst-content blockquote {
+    margin-bottom: 14px;
 }
 
 /*
diff --git a/docs/index.md b/docs/index.md
index 6ff84d00..cfadd421 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,12 +1,11 @@
-Home
-====
-
-Welcome to the cibuildwheel docs. 
-
-To get started, head over to the [setup guide](setup.md).
+---
+title: Home
+---
 
 {% 
    includemarkdown "../README.md"
    start="<!--intro-start-->" 
    end="<!--intro-end-->"
 %}
+
+To get started, head over to the [setup guide](setup.md).
diff --git a/docs/options.md b/docs/options.md
index 7f377fe8..4de7c313 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -44,7 +44,7 @@ variables:
 
 ## Build selection
 
-### CIBW_PLATFORM {: #platform}
+### `CIBW_PLATFORM` {: #platform}
 > Override the auto-detected target platform
 
 Options: `auto` `linux` `macos` `windows`
@@ -55,7 +55,7 @@ Default: `auto`
 
 For `linux` you need Docker running, on Mac or Linux. For `macos`, you need a Mac machine, and note that this script is going to automatically install MacPython on your system, so don't run on your development machine. For `windows`, you need to run in Windows, and it will build and test for all versions of Python at `C:\PythonXX[-x64]`.
 
-### CIBW_BUILD, CIBW_SKIP {: #build-skip}
+### `CIBW_BUILD`, `CIBW_SKIP` {: #build-skip}
 
 > Choose the Python versions to build
 
@@ -87,7 +87,7 @@ Examples:
 
 ## Build environment
 
-### CIBW_ENVIRONMENT {: #environment}
+### `CIBW_ENVIRONMENT` {: #environment}
 > Set environment variables needed during the build
 
 A space-separated list of environment variables to set during the build. Bash syntax should be used (even on Windows!).
@@ -96,17 +96,18 @@ You must set this variable to pass variables to Linux builds (since they execute
 
 You can use `$PATH` syntax to insert other variables, or the `$(pwd)` syntax to insert the output of other shell commands.
 
-Example: `CFLAGS="-g -Wall" CXXFLAGS="-Wall"`\
-Example: `PATH=$PATH:/usr/local/bin`\
-Example: `BUILD_TIME="$(date)"`\
+Example: `CFLAGS="-g -Wall" CXXFLAGS="-Wall"`  
+Example: `PATH=$PATH:/usr/local/bin`  
+Example: `BUILD_TIME="$(date)"`  
 Example: `PIP_EXTRA_INDEX_URL="https://pypi.myorg.com/simple"`
 
-Platform-specific variants also available:
+Platform-specific variants also available:  
 `CIBW_ENVIRONMENT_MACOS` | `CIBW_ENVIRONMENT_WINDOWS` | `CIBW_ENVIRONMENT_LINUX`
 
 In addition to the above, `cibuildwheel` always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](https://github.com/joerick/cibuildwheel/wiki/Building-packages-with-optional-C-extensions).
 
-### CIBW_BEFORE_BUILD {: #before-build}
+
+### `CIBW_BEFORE_BUILD` {: #before-build}
 > Execute a shell command preparing each wheel's build
 
 A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
@@ -115,14 +116,15 @@ If dependencies are required to build your wheel (for example if you include a h
 
 The active Python binary can be accessed using `python`, and pip with `pip`; `cibuildwheel` makes sure the right version of Python and pip will be executed. `{project}` can be used as a placeholder for the absolute path to the project's root.
 
-Example: `pip install .`\
-Example: `pip install pybind11`\
+Example: `pip install .`  
+Example: `pip install pybind11`  
 Example: `yum install -y libffi-dev && pip install .`
 
-Platform-specific variants also available:\
+Platform-specific variants also available:  
  `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
 
-### CIBW_MANYLINUX_X86_64_IMAGE, CIBW_MANYLINUX_I686_IMAGE {: #manylinux-image}
+
+### `CIBW_MANYLINUX_X86_64_IMAGE`, `CIBW_MANYLINUX_I686_IMAGE` {: #manylinux-image}
 > Specify alternative manylinux docker images 
 
 An alternative Docker image to be used for building [`manylinux`](https://github.com/pypa/manylinux) wheels. `cibuildwheel` will then pull these instead of the default images, [`quay.io/pypa/manylinux2010_x86_64`](https://quay.io/pypa/manylinux2010_x86_64) and [`quay.io/pypa/manylinux2010_i686`](https://quay.io/pypa/manylinux2010_i686).
@@ -133,13 +135,13 @@ Beware to specify a valid Docker image that can be used in the same way as the o
 
 Note that `auditwheel` detects the version of the `manylinux` standard in the Docker image through the `AUDITWHEEL_PLAT` environment variable, as `cibuildwheel` has no way of detecting the correct `--plat` command line argument to pass to `auditwheel` for a custom image. If a Docker image does not correctly set this `AUDITWHEEL_PLAT` environment variable, the `CIBW_ENVIRONMENT` option can be used to do so (e.g., `CIBW_ENVIRONMENT="manylinux2010_$(uname -m)"`).
 
-Example: `manylinux1`\
-Example: `dockcross/manylinux-x64`\
+Example: `manylinux1`  
+Example: `dockcross/manylinux-x64`  
 Example: `dockcross/manylinux-x86`
 
 ## Testing
 
-### CIBW_TEST_COMMAND {: #test-command}
+### `CIBW_TEST_COMMAND` {: #test-command}
 > Execute a shell command to test all built wheels
 
 Shell command to run tests after the build. The wheel will be installed automatically and available for import from the tests. `{project}` can be used as a placeholder for the absolute path to the project's root and will be replaced by `cibuildwheel`.
@@ -148,21 +150,21 @@ On Linux and Mac, the command runs in a shell, so you can write things like `cmd
 
 Example: `nosetests {project}/tests`
 
-Platform-specific variants also available:
+Platform-specific variants also available:  
 `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX`
 
-### CIBW_TEST_REQUIRES {: #test-requires}
+### `CIBW_TEST_REQUIRES` {: #test-requires}
 > Install Python dependencies before running the tests
 
 Space-separated list of dependencies required for running the tests.
 
-Example: `pytest`\
+Example: `pytest`  
 Example: `nose==1.3.7 moto==0.4.31`
 
-Platform-specific variants also available:
+Platform-specific variants also available:  
 `CIBW_TEST_REQUIRES_MACOS` | `CIBW_TEST_REQUIRES_WINDOWS` | `CIBW_TEST_REQUIRES_LINUX`
 
-### CIBW_TEST_EXTRAS {: #test-extras}
+### `CIBW_TEST_EXTRAS` {: #test-extras}
 > Install your wheel for testing using `extras_require`
 
 Comma-separated list of
@@ -175,17 +177,17 @@ tests. This can be used to avoid having to redefine test dependencies in
 Example: `test,qt` (will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`)
 
 
-Platform-specific variants also available:
+Platform-specific variants also available:  
 `CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX`
 
 ## Other
 
-### CIBW_BUILD_VERBOSITY {: #test-extras}
+### `CIBW_BUILD_VERBOSITY` {: #test-extras}
 > Increase/decrease the output of pip wheel
 
 An number from 1 to 3 to increase the level of verbosity (corresponding to invoking pip with `-v`, `-vv`, and `-vvv`), between -1 and -3 (`-q`, `-qq`, and `-qqq`), or just 0 (default verbosity). These flags are useful while debugging a build when the output of the actual build invoked by `pip wheel` is required.
 
-Platform-specific variants also available:
+Platform-specific variants also available:  
 `CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX`
 
 ## Command line options
diff --git a/docs/setup.md b/docs/setup.md
index 7a231588..d89c0db0 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1,4 +1,8 @@
-## Azure Pipelines [linux/mac/windows]
+---
+title: 'Setup'
+---
+
+# Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
 
 Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo.
 
@@ -43,7 +47,7 @@ Commit this file, enable building of your repo on Azure Pipelines, and push.
 
 Wheels will be stored for you and available through the Pipelines interface. For more info on this file, check out the [docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema).
 
-## Travis CI [linux/mac]
+# Travis CI [linux/mac] {: #travis-ci}
 
 To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo.
 
@@ -82,7 +86,7 @@ Commit this file, enable building of your repo on Travis CI, and push.
 
 Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](deliver-to-pypi.md). For more info on `.travis.yml`, check out the [docs](https://docs.travis-ci.com/).
 
-## CircleCI [linux/mac]
+# CircleCI [linux/mac] {: #circleci}
 
 To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
 
@@ -135,7 +139,7 @@ Commit this file, enable building of your repo on CircleCI, and push.
 
 CircleCI will store the built wheels for you - you can access them from the project console. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file.
 
-## AppVeyor [windows]
+# AppVeyor [windows] {: #appveyor}
 
 To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
 
@@ -160,12 +164,12 @@ For more info on this config file, check out the [docs](https://www.appveyor.com
 
 <script> 
   document.addEventListener('DOMContentLoaded', function() {
-    $('.toctree-l2 a, .rst-content h2').each(function(i, el) {
+    $('.toctree-l2 a, .rst-content h1').each(function(i, el) {
       var text = $(el).text()
       var match = text.match(/(.*) \[([a-z/]+)\]/);
 
       if (match) {
-        var iconHTML = match[2].split('/').map(function(ident) {
+        var iconHTML = $.map(match[2].split('/'), function(ident) {
           switch (ident) {
             case 'linux':
               return '<i class="fa fa-linux" aria-hidden="true"></i>'
@@ -175,7 +179,15 @@ For more info on this config file, check out the [docs](https://www.appveyor.com
               return '<i class="fa fa-apple" aria-hidden="true"></i>'
           }
         }).join(' ');
-        $(el).html(match[1] + ' ' + iconHTML)
+
+        $(el).append(
+          $('<div>')
+            .append(iconHTML)
+            .css({float: 'right'})
+        )
+        $(el).contents()
+          .filter(function(){ return this.nodeType == 3; }).first()
+          .replaceWith(match[1]);
       }
     });
   });