diff --git a/docs/extra.css b/docs/extra.css
new file mode 100644
index 00000000..42095298
--- /dev/null
+++ b/docs/extra.css
@@ -0,0 +1,72 @@
+
+/* Global styles */
+
+p {
+    margin-bottom: 12px;
+}
+
+code {
+    font-size: 85%;
+    background-color: rgba(27,31,35,.05);
+    border-radius: 3px;
+    padding: .2em .4em;
+    color: inherit;
+    border: none;
+    margin: 0 1px;
+}
+
+code, pre, tt {
+    font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
+}
+
+.hljs {
+    padding: 1em;
+    background-color: #f6f8fa;
+}
+
+/*
+    Code block filename style
+
+    Use by putting a quote before a code block e.g.
+
+       > filename.txt
+
+       ```
+       code here
+       ```
+
+    JS adds the relevant classes to make the following selectors work.
+*/
+.rst-content .code-block-filename {
+    margin: 0;
+    padding: 2px 1em;
+    background-color: #eff1f3;
+    font-size: 85%;
+    font-weight: bold;
+    
+    border-top-left-radius: 3px;
+    border-top-right-radius: 3px;
+
+    border-bottom: 1px solid #e6e8e9;
+    color: #444;
+}
+
+.rst-content .code-block-filename * {
+    font-size: inherit;
+}
+.rst-content .code-block-filename :last-child {
+    margin-bottom: 0;
+}
+
+.code-block-filename + pre {
+    margin-top: 0;
+    border-top-left-radius: 0;
+    border-top-right-radius: 0;
+}
+
+.code-block-filename + pre code {
+    padding-top: 0.9em;
+}
+
+/* import font awesome 4 for icons */
+@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css);
diff --git a/docs/extra.js b/docs/extra.js
new file mode 100644
index 00000000..d32c3cc0
--- /dev/null
+++ b/docs/extra.js
@@ -0,0 +1,5 @@
+
+$('.rst-content pre')
+    .prev('blockquote')
+    .addClass('code-block-filename');
+
diff --git a/docs/options.md b/docs/options.md
index 12814d01..8c6146fc 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1,24 +1,42 @@
+### Setting options
+
 cibuildwheel is configured using environment variables, that can be set using 
 your CI config.
 
-<table>
-<tr><td><i>example .travis.yml environment variables</i><pre><code>env:
+For example, to configure cibuildwheel to run tests, add the following YAML to
+your CI config file:
+
+> .travis.yml ([docs](https://docs.travis-ci.com/user/environment-variables/))
+```yaml
+env:
   global:
     - CIBW_TEST_REQUIRES=nose
     - CIBW_TEST_COMMAND="nosetests {project}/tests"
-</code></pre></td>
-<td><i>example appveyor.yml environment variables</i><pre><code>environment:
+```
+
+> appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
+```yaml
+environment:
   global:
     CIBW_TEST_REQUIRES: nose
     CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-</code></pre></td>
-<td><i>example .circleci/config.yml environment variables</i><pre><code>jobs:
+```
+
+> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
+```yaml
+jobs:
   job_name:
     environment:
       CIBW_TEST_REQUIRES: nose
-      CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-</code></pre></td>
-</tr></table>
+      CIBW_TEST_COMMAND: "nosetests {project}/tests"
+```
+
+> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables))
+```yaml
+variables:
+  CIBW_TEST_REQUIRES: nose
+  CIBW_TEST_COMMAND: "nosetests {project}/tests"
+```
 
 ## 🚩Build selection
 
@@ -150,7 +168,7 @@ Platform-specific variants also available:
 
 ## Command line options
 
-```
+```text
 usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
                     [--output-dir OUTPUT_DIR] [--print-build-identifiers]
                     [project_dir]
@@ -178,3 +196,44 @@ optional arguments:
                         invocation and exit.
 
 ```
+
+<style>
+  .cibw-option-header {
+    margin-top: 5px;
+    /* border-bottom: 1px solid rgba(0, 0, 0, 0.05); */
+  }
+  .cibw-option-header:hover {
+    background-color: transparent !important;
+  }
+  .cibw-option-name {
+    display: block;
+    font-weight: bold;
+  }
+  .cibw-option-description {
+    font-size: 0.9em;
+  }
+</style>
+
+<script>
+  document.addEventListener('DOMContentLoaded', function() {
+    // add styling classes to the toc-tree elements
+    $('.wy-menu-vertical li.current a').each(function(i, el) {
+      var $el = $(el);
+      $el.html( $el.text().replace(
+        /(^[A-Z0-9, _]+) - (.*)$/,
+        '<div class="cibw-option-name">$1</div><div class="cibw-option-description">$2</div>')
+      );
+    })
+    
+    // add styling classes to the emoji headers
+    $('.wy-menu-vertical li.current a').each(function(i, el) {
+      var $el = $(el);
+      var text = $el.text();
+      var emojiStartRegex = /^(\u00a9|\u00ae|[\u2000-\u3300]|\ud83c[\ud000-\udfff]|\ud83d[\ud000-\udfff]|\ud83e[\ud000-\udfff])/
+
+      if (text.match(emojiStartRegex)) {
+        $el.addClass('cibw-option-header')
+      }
+    })
+  })
+</script>
diff --git a/docs/setup.md b/docs/setup.md
index 2e87c5a8..3ec28623 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -2,7 +2,7 @@
 
 Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo.
 
-**azure-pipelines.yml**
+> azure-pipelines.yml
 ```yaml
 jobs:
 - job: linux
@@ -50,6 +50,7 @@ jobs:
 
 To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo.
 
+> .travis.yml
 ```yaml
 language: python
 
@@ -74,6 +75,7 @@ Then setup a deployment method by following the [Travis CI deployment docs](http
     
 To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
 
+> .circleci/config.yml
 ```yaml
 version: 2
 
@@ -124,6 +126,8 @@ CircleCI will store the built wheels for you - you can access them from the proj
 
 To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
 
+> appveyor.yml
+
 ```yaml
 build_script:
   - pip install cibuildwheel==0.12.0
@@ -139,4 +143,27 @@ Commit those files, enable building of your repo on Travis CI and AppVeyor, and
 
 All being well, you should get wheels delivered to you in a few minutes. 
 
-> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below.
+> ⚠️ Got an error? Check the [FAQ](faq.md).
+
+<script> 
+  document.addEventListener('DOMContentLoaded', function() {
+    $('.toctree-l2 a, .rst-content h2').each(function(i, el) {
+      var text = $(el).text()
+      var match = text.match(/(.*) \[([a-z/]+)\]/);
+
+      if (match) {
+        var iconHTML = match[2].split('/').map(function(ident) {
+          switch (ident) {
+            case 'linux':
+              return '<i class="fa fa-linux" aria-hidden="true"></i>'
+            case 'windows':
+              return '<i class="fa fa-windows" aria-hidden="true"></i>'
+            case 'mac':
+              return '<i class="fa fa-apple" aria-hidden="true"></i>'
+          }
+        }).join(' ');
+        $(el).html(match[1] + ' ' + iconHTML)
+      }
+    });
+  });
+</script>
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 4c187bd6..2c9caadc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,8 +1,18 @@
 site_name: cibuildwheel
 docs_dir: docs
-theme: readthedocs
+theme:
+  name: readthedocs
+  highlightjs: true
+  hljs_languages:
+      - yaml
 repo_url: https://github.com/joerick/cibuildwheel
 
+extra_css:
+  - extra.css
+
+extra_javascript:
+  - extra.js
+
 nav:
   - Home: index.md
   - "Setup guide": setup.md
@@ -10,6 +20,7 @@ nav:
   - deliver-to-pypi.md
   - faq.md
   - contributing.md
+
 markdown_extensions:
   - fenced_code
   - toc: