diff --git a/docs/extra.css b/docs/extra.css
index e7d035aea..ab62371e1 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -89,3 +89,59 @@ h1, h2, h3, h4, h5, h6 {
 
 /* import font awesome 4 for icons */
 @import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css);
+
+
+/* Tabs */
+
+/* Style the tab */
+.tabs {
+  margin-bottom: 1em;
+  -webkit-font-smoothing: antialiased;
+}
+
+.tabs-header {
+  background-color: white;
+  display: flex;
+  justify-content: flex-start;
+  border-bottom: 2px solid #ccc;
+}
+
+/* Style the buttons that are used to open the tab content */
+.tabs-header button {
+  background-color: transparent;
+  border: none;
+  outline: none;
+  cursor: pointer;
+  color: inherit;
+  font: inherit;
+  font-size: 0.9em;
+  font-weight: 600;
+  padding: 8px 16px;
+  border-bottom: 2px solid transparent;
+
+  /* put the border on top of the parent border */
+  margin-bottom: -2px;
+}
+
+.tabs-header button:focus-visible {
+  /* preserve an outline for accesibility purposes */
+  outline: 1px solid currentColor;
+}
+
+/* Change background color of buttons on hover */
+.tabs-header button:hover {
+  background-color: rgba(0, 0, 0, 0.02);
+}
+
+/* Create an active/current tablink class */
+.tabs-header button.active {
+  color: #4086bd;
+  border-bottom-color: currentColor;
+}
+
+/* Style the tab content */
+.tabs-content {
+  background-color: #f1f6fa;
+  padding: 1px 1em;
+  padding-top: 0.8em;
+}
diff --git a/docs/extra.js b/docs/extra.js
index 1965a84e9..9ef194fa4 100644
--- a/docs/extra.js
+++ b/docs/extra.js
@@ -1,4 +1,49 @@
-
+// add classes for code-block-filename styling
 $('.rst-content pre')
     .prev('blockquote')
     .addClass('code-block-filename');
+
+var tabConversionIterations = 0
+
+// convert tab admonition to tabs
+while (true) {
+  const firstTab = $('.rst-content .admonition.tab').first()
+  if (firstTab.length == 0) break;
+
+  const otherTabs = firstTab.nextUntil(':not(.admonition.tab)');
+  const allTabs = $($.merge($.merge([], firstTab), otherTabs));
+
+  const tabContainer = $('<div>').addClass('tabs');
+  const headerContainer = $('<div>').addClass('tabs-header');
+  const contentContainer = $('<div>').addClass('tabs-content');
+
+  tabContainer.insertBefore(firstTab);
+  tabContainer.append(headerContainer, contentContainer)
+
+  const selectTab = function (index) {
+    headerContainer.children().removeClass('active')
+    headerContainer.children().eq(index).addClass('active')
+    contentContainer.children().hide()
+    contentContainer.children().eq(index).show()
+  }
+
+  allTabs.each(function (tabI, el) {
+    const $el = $(el)
+    const titleElement = $el.children('.admonition-title')
+    const title = titleElement.text()
+    const button = $('<button>').text(title)
+    button.click(function () {
+      selectTab(tabI)
+    })
+    headerContainer.append(button)
+
+    titleElement.remove()
+    $el.removeClass('admonition')
+    contentContainer.append($el)
+  })
+
+  selectTab(0)
+
+  // this will catch infinite loops which can occur when editing the above
+  if (tabConversionIterations++ > 1000) throw 'too many iterations'
+}
diff --git a/docs/faq.md b/docs/faq.md
index ade836871..d9dfb9f1b 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -105,6 +105,7 @@ Actions. Once QEMU is set up and registered, you just need to set the
 Linux), and the other architectures are emulated automatically.
 
 > .github/workflows/build.yml
+
 ```yaml
 {% include "../examples/github-with-qemu.yml" %}
 ```
@@ -130,6 +131,7 @@ Hopefully, this is a temporary situation. Once we have widely available Apple Si
 Here's an example GitHub Actions workflow with a job that builds for Apple Silicon:
 
 > .github/workflows/build_macos.yml
+
 ```yml
 {% include "../examples/github-apple-silicon.yml" %}
 ```
diff --git a/docs/options.md b/docs/options.md
index 7cba035b3..11546bf96 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -10,44 +10,72 @@ your CI config.
 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=pytest
-    - CIBW_TEST_COMMAND="pytest {project}/tests"
-```
 
-> appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
-```yaml
-environment:
-  global:
-    CIBW_TEST_REQUIRES: pytest
-    CIBW_TEST_COMMAND: "pytest {project}\\tests"
-```
+!!! tab "GitHub Actions"
 
-> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
-```yaml
-jobs:
-  job_name:
-    environment:
+    > .github/workflows/*.yml ([docs](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables)) (can be global, in job, or in step)
+
+    ```yaml
+    env:
       CIBW_TEST_REQUIRES: pytest
       CIBW_TEST_COMMAND: "pytest {project}/tests"
-```
+    ```
 
-> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables))
-```yaml
-variables:
-  CIBW_TEST_REQUIRES: pytest
-  CIBW_TEST_COMMAND: "pytest {project}/tests"
-```
+!!! tab "Azure Pipelines"
+
+    > azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables))
+
+    ```yaml
+    variables:
+      CIBW_TEST_REQUIRES: pytest
+      CIBW_TEST_COMMAND: "pytest {project}/tests"
+    ```
+
+!!! tab "Travis CI"
+
+    > .travis.yml ([docs](https://docs.travis-ci.com/user/environment-variables/))
+
+    ```yaml
+    env:
+      global:
+        - CIBW_TEST_REQUIRES=pytest
+        - CIBW_TEST_COMMAND="pytest {project}/tests"
+    ```
+
+!!! tab "AppVeyor"
+
+    > appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
+
+    ```yaml
+    environment:
+      global:
+        CIBW_TEST_REQUIRES: pytest
+        CIBW_TEST_COMMAND: "pytest {project}\\tests"
+    ```
+
+!!! tab "CircleCI"
+
+    > .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
+
+    ```yaml
+    jobs:
+      job_name:
+        environment:
+          CIBW_TEST_REQUIRES: pytest
+          CIBW_TEST_COMMAND: "pytest {project}/tests"
+    ```
+
+!!! tab "Gitlab CI"
+
+    > .gitlab-ci.yml ([docs](https://docs.gitlab.com/ee/ci/variables/README.html#create-a-custom-variable-in-gitlab-ciyml))
+
+    ```yaml
+    linux:
+      variables:
+        CIBW_TEST_REQUIRES: pytest
+        CIBW_TEST_COMMAND: "pytest {project}/tests"
+    ```
 
-> .github/workflows/*.yml ([docs](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables)) (can be global, in job, or in step)
-```yaml
-env:
-  CIBW_TEST_REQUIRES: pytest
-  CIBW_TEST_COMMAND: "pytest {project}/tests"
-```
 
 
 ## Build selection
diff --git a/docs/setup.md b/docs/setup.md
index cdc2880f9..fe4696e68 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -4,12 +4,101 @@ title: 'Setup'
 
 # GitHub Actions [linux/mac/windows] {: #github-actions}
 
-To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build.yml` file in your repo.
+To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo.
+
+!!! tab "Action"
+    For GitHub Actions, `cibuildwheel` provides an action you can use. This is
+    concise and enables easier auto updating via GitHub's Dependabot; see
+    [Automatic updates](faq.md#automatic-updates).
+
+    > .github/workflows/build_wheels.yml
+
+    ```yaml
+    {% include "../examples/github-minimal.yml" %}
+    ```
+
+
+    You can use `env:` with the action just like you would with `run:`; you can
+    also use `with:` to set the command line options: `package-dir: .` and
+    `output-dir: wheelhouse` (those values are the defaults).
+
+!!! tab "pipx"
+    The GitHub Actions runners have pipx installed, so you can easily build in
+    just one line. This is internally how the action works; the main benefit of
+    the action form is easy updates via GitHub's Dependabot.
+
+    > .github/workflows/build_wheels.yml
+
+    ```yaml
+    name: Build
+
+    on: [push, pull_request]
+
+    jobs:
+      build_wheels:
+        name: Build wheels on ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+        strategy:
+          matrix:
+            os: [ubuntu-20.04, windows-2019, macos-10.15]
+
+        steps:
+          - uses: actions/checkout@v2
+
+          - name: Install Visual C++ for Python 2.7
+            if: runner.os == 'Windows'
+            run: choco install vcpython27 -f -y
+
+          - name: Build wheels
+            run: pix run cibuildwheel==1.8.0
+
+          - uses: actions/upload-artifact@v2
+            with:
+              path: ./wheelhouse/*.whl
+    ```
+
+!!! tab "Generic"
+    This is the most generic form using setup-python and pip; it looks the most
+    like the other CI examples. If you want to avoid having setup that takes
+    advantage of GitHub Actions features or pipx being preinstalled, this might
+    appeal to you.
+
+    > .github/workflows/build_wheels.yml
+
+    ```yaml
+    name: Build
+
+    on: [push, pull_request]
+
+    jobs:
+      build_wheels:
+        name: Build wheels on ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+        strategy:
+          matrix:
+            os: [ubuntu-20.04, windows-2019, macos-10.15]
+
+        steps:
+          - uses: actions/checkout@v2
+
+          # Used to host cibuildwheel
+          - uses: actions/setup-python@v2
+
+          - name: Install cibuildwheel
+            run: python -m pip install cibuildwheel==1.9.0
+
+          - name: Install Visual C++ for Python 2.7
+            if: runner.os == 'Windows'
+            run: choco install vcpython27 -f -y
+
+          - name: Build wheels
+            run: python -m cibuildwheel --output-dir wheelhouse
+
+          - uses: actions/upload-artifact@v2
+            with:
+              path: ./wheelhouse/*.whl
+    ```
 
-> build.yml
-```yaml
-{% include "../examples/github-minimal.yml" %}
-```
 
 Commit this file, and push to GitHub - either to your default branch, or to a PR branch. The build should start automatically.
 
@@ -17,13 +106,13 @@ For more info on this file, check out the [docs](https://help.github.com/en/acti
 
 [`examples/github-deploy.yml`](https://github.com/joerick/cibuildwheel/blob/master/examples/github-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
-You can also use cibuildwheel directly as an action with `uses: joerick/cibuildwheel@v1.9.0`; this combines the download and run steps into a single action, and command line arguments are available via `with:`. This makes it easy to manage cibuildwheel updates via normal actions update mechanisms like dependabot, see [Automatic updates](faq.md#automatic-updates).
 
 # Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
 
 To build Linux, Mac, and Windows wheels on Azure Pipelines, create a `azure-pipelines.yml` file in your repo.
 
 > azure-pipelines.yml
+
 ```yaml
 {% include "../examples/azure-pipelines-minimal.yml" %}
 ```
@@ -40,6 +129,7 @@ Wheels will be stored for you and available through the Pipelines interface. For
 To build Linux, Mac, and Windows wheels on Travis CI, create a `.travis.yml` file in your repo.
 
 > .travis.yml
+
 ```yaml
 {% include "../examples/travis-ci-minimal.yml" %}
 ```
@@ -52,11 +142,28 @@ Then setup a deployment method by following the [Travis CI deployment docs](http
 
 [`examples/travis-ci-deploy.yml`](https://github.com/joerick/cibuildwheel/blob/master/examples/travis-ci-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
+# AppVeyor [linux/mac/windows] {: #appveyor}
+
+To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
+
+> appveyor.yml
+
+```yaml
+{% include "../examples/appveyor-minimal.yml" %}
+```
+
+Commit this file, enable building of your repo on AppVeyor, and push.
+
+AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](deliver-to-pypi.md) below.
+
+For more info on this config file, check out the [docs](https://www.appveyor.com/docs/).
+
 # CircleCI [linux/mac] {: #circleci}
 
 To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
 
 > .circleci/config.yml
+
 ```yaml
 {% include "../examples/circleci-minimal.yml" %}
 ```
@@ -73,6 +180,7 @@ CircleCI will store the built wheels for you - you can access them from the proj
 To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
 
 > .gitlab-ci.yml
+
 ```yaml
 {% include "../examples/gitlab-minimal.yml" %}
 ```
@@ -81,22 +189,6 @@ Commit this file, and push to Gitlab. The pipeline should start automatically.
 
 Gitlab will store the built wheels for you - you can access them from the Pipelines view. Check out the Gitlab [docs](https://docs.gitlab.com/ee/ci/yaml/) for more info on this config file.
 
-# AppVeyor [linux/mac/windows] {: #appveyor}
-
-To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
-
-> appveyor.yml
-
-```yaml
-{% include "../examples/appveyor-minimal.yml" %}
-```
-
-Commit this file, enable building of your repo on AppVeyor, and push.
-
-AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](deliver-to-pypi.md) below.
-
-For more info on this config file, check out the [docs](https://www.appveyor.com/docs/).
-
 > ⚠️ Got an error? Check the [FAQ](faq.md).
 
 <script>
diff --git a/mkdocs.yml b/mkdocs.yml
index 3b404dbca..59f6a2903 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -25,13 +25,17 @@ nav:
   - changelog.md
 
 markdown_extensions:
-  - fenced_code
+  - md_in_html
   - toc:
       permalink: True
   - attr_list
   - admonition
   - pymdownx.magiclink:
       repo_url_shortener: True
+  - pymdownx.highlight:
+      # use highlightjs - it's built-in to the theme
+      use_pygments: False
+  - pymdownx.superfences
 
 plugins:
   - include-markdown
diff --git a/setup.py b/setup.py
index bf34fe946..87168e76c 100644
--- a/setup.py
+++ b/setup.py
@@ -2,7 +2,7 @@
 
 extras = {
     "docs": [
-        "mkdocs-include-markdown-plugin==2.1.1",
+        "mkdocs-include-markdown-plugin==2.8.0",
         "mkdocs==1.0.4",
         "pymdown-extensions",
     ],