15 files changed, 174 insertions, 50 deletions
diff --git a/docs/.gitignore b/docs/.gitignore
index 1fb99949..610ffdf1 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,5 +1,6 @@
 generated/
-src/public
-node_modules
-public
+src/public/
+node_modules/
+public/
 src/resources/_gen/
+src/content/addons-examples.md
diff --git a/docs/README.md b/docs/README.md
index 5c99fb39..24c24d24 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,7 +8,7 @@ This directory houses the mitmproxy documentation available at <https://docs.mit
  2. Windows users: Depending on your git settings, you may need to manually create a symlink from
  /docs/src/examples to /examples.
  3. Make sure the mitmproxy Python package is installed.
- 4. Run `./build-current` to generate the documentation source files in `./src/generated`.
+ 4. Run `./build.sh` to generate additional documentation source files.
 
 Now you can run `hugo server -D` in ./src.
 
diff --git a/docs/build-archive b/docs/build-archive
deleted file mode 100755
index 004e625a..00000000
--- a/docs/build-archive
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/bin/sh
-set -e
-
-DOCS_ARCHIVE=true ./build-current
diff --git a/docs/build-current b/docs/build-current
deleted file mode 100755
index 7164de6d..00000000
--- a/docs/build-current
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env bash
-
-set -e
-
-for script in scripts/* ; do
-  echo "Generating output for $script ..."
-  output="${script##*/}"
-  "$script" > "src/generated/${output%.*}.html"
-done
-
-cd src
-hugo
diff --git a/docs/build.sh b/docs/build.sh
new file mode 100755
index 00000000..aaa52a2f
--- /dev/null
+++ b/docs/build.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+set -o errexit
+set -o pipefail
+set -o nounset
+# set -o xtrace
+
+SCRIPTPATH="$( cd "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"
+pushd ${SCRIPTPATH}
+
+for script in scripts/* ; do
+  output="${script##*/}"
+  output="src/generated/${output%.*}.html"
+  echo "Generating output for ${script} into ${output} ..."
+  "${script}" > "${output}"
+done
+
+output="src/content/addons-examples.md"
+echo "Generating examples content page into ${output} ..."
+./render_examples.py > "${output}"
+
+cd src
+hugo
diff --git a/docs/ci b/docs/ci.sh
index 95a5218e..159d0b50 100755
--- a/docs/ci
+++ b/docs/ci.sh
@@ -1,9 +1,13 @@
-#!/bin/bash
-set -e
+#!/usr/bin/env bash
 
-# This script gets run from CI to render and upload docs
+set -o errexit
+set -o pipefail
+set -o nounset
+# set -o xtrace
 
-./build-current
+# This script gets run from CI to render and upload docs for the master branch.
+
+./build.sh
 
 # Only upload if we have defined credentials - we only have these defined for
 # trusted commits (i.e. not PRs).
diff --git a/docs/render_examples.py b/docs/render_examples.py
new file mode 100755
index 00000000..9c6dea74
--- /dev/null
+++ b/docs/render_examples.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+
+import os
+import textwrap
+from pathlib import Path
+
+print("""
+---
+title: "Examples"
+menu:
+    addons:
+        weight: 6
+---
+
+# Examples of Addons and Scripts
+
+The most recent set of examples is also available [on our GitHub project](https://github.com/mitmproxy/mitmproxy/tree/master/examples).
+
+""")
+
+base = os.path.dirname(os.path.realpath(__file__))
+examples_path = os.path.join(base, 'src/examples/')
+pathlist = Path(examples_path).glob('**/*.py')
+
+examples = [os.path.relpath(str(p), examples_path) for p in sorted(pathlist)]
+examples = [p for p in examples if not os.path.basename(p) == '__init__.py']
+examples = [p for p in examples if not os.path.basename(p).startswith('test_')]
+
+current_dir = None
+current_level = 2
+for ex in examples:
+    if os.path.dirname(ex) != current_dir:
+        current_dir = os.path.dirname(ex)
+        sanitized = current_dir.replace('/', '').replace('.', '')
+        print("  * [Examples: {}]({{{{< relref \"addons-examples#{}\">}}}})".format(current_dir, sanitized))
+
+    sanitized = ex.replace('/', '').replace('.', '')
+    print("    * [{}]({{{{< relref \"addons-examples#example-{}\">}}}})".format(os.path.basename(ex), sanitized))
+
+current_dir = None
+current_level = 2
+for ex in examples:
+    if os.path.dirname(ex) != current_dir:
+        current_dir = os.path.dirname(ex)
+        print("#" * current_level, current_dir)
+
+    print(textwrap.dedent("""
+        {} Example: {}
+        {{{{< example src="{}" lang="py" >}}}}
+    """.format("#" * (current_level + 1), ex, "examples/" + ex)))
diff --git a/docs/setup b/docs/setup.sh
index cb63841a..da30a3c9 100755
--- a/docs/setup
+++ b/docs/setup.sh
@@ -1,5 +1,11 @@
-#!/bin/sh
-set -e
+#!/usr/bin/env bash
+
+set -o errexit
+set -o pipefail
+set -o nounset
+# set -o xtrace
+
+# This is only needed once to provision a new fresh empty S3 bucket.
 
 aws configure set preview.cloudfront true
 aws --profile mitmproxy \
diff --git a/docs/src/assets/style.scss b/docs/src/assets/style.scss
index 26c22071..33e8863e 100644
--- a/docs/src/assets/style.scss
+++ b/docs/src/assets/style.scss
@@ -47,6 +47,7 @@ body > div {
         width: 100%;
         text-align: right;
     }
+    max-width: 70vw;
     margin-bottom: 1em;
 }
 
diff --git a/docs/src/content/concepts-certificates.md b/docs/src/content/concepts-certificates.md
index 4e9aa652..20b03dc6 100644
--- a/docs/src/content/concepts-certificates.md
+++ b/docs/src/content/concepts-certificates.md
@@ -36,12 +36,12 @@ documentation for some common platforms. The mitmproxy CA cert is located in
 `~/.mitmproxy` after it has been generated at the first start of mitmproxy.
 
 - [IOS](http://jasdev.me/intercepting-ios-traffic)
-  On iOS 10.3 and onwards, you also need to enable full trust for the mitmproxy
+  On recent iOS versions you also need to enable full trust for the mitmproxy
   root certificate:
     1. Go to Settings > General > About > Certificate Trust Settings.
     2. Under "Enable full trust for root certificates", turn on trust for
-        the mitmproxy certificate.
-- [IOS Simulator](https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore)
+       the mitmproxy certificate.
+- [iOS Simulator](https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore)
 - [Java](https://docs.oracle.com/cd/E19906-01/820-4916/geygn/index.html)
 - [Android/Android Simulator](http://wiki.cacert.org/FAQ/ImportRootCert#Android_Phones_.26_Tablets)
 - [Windows](https://web.archive.org/web/20160612045445/http://windows.microsoft.com/en-ca/windows/import-export-certificates-private-keys#1TC=windows-7)
diff --git a/docs/src/content/overview-getting-started.md b/docs/src/content/overview-getting-started.md
new file mode 100644
index 00000000..ff018c3b
--- /dev/null
+++ b/docs/src/content/overview-getting-started.md
@@ -0,0 +1,49 @@
+---
+title: "Getting Started"
+menu: "overview"
+menu:
+    overview:
+        weight: 3
+---
+
+# Getting Started
+
+You have already [installed]({{< relref "overview-installation">}}) mitmproxy on
+your machine.
+
+# Launch the tool you need
+
+You can start any of our three tools from the command line / terminal:
+
+  * [mitmproxy]({{< relref "tools-mitmproxy">}}) -> gives you an interactive TUI
+  * [mitmdump]({{< relref "tools-mitmdump">}}) -> gives you a plain and simple terminal output
+  * [mitmweb]({{< relref "tools-mitmweb">}}) -> gives you a browser-based GUI
+
+When we talk about "mitmproxy" we usually refer to any of the three tools - they
+are just different front-ends to the same core proxy.
+
+# Configure your browser or device
+
+For the basic setup as [regular proxy]({{< relref
+"concepts-modes#regular-proxy">}}), you need to configure your browser or device
+to route all web traffic through mitmproxy as HTTP proxy. Browser versions and
+configurations options frequently change, so we recommend to simply search the
+web on how to configure an HTTP proxy for your system. Some operating system
+have a global settings, some browser have their own, other applications use
+environment variables, etc.
+
+You can check that your web traffic is going through mitmproxy by browsing to
+http://mitm.it - it should present you with a [simple page]({{< relref
+"concepts-certificates/#quick-setup">}}) to install the mitmproxy Certificate
+Authority - which is also the next steps. Follow the instructions for your OS /
+system and install the CA (and make sure to enable it, some system require
+multiple steps!).
+
+# Verifying everything works
+
+At this point your running mitmproxy instance should already show the first HTTP
+flows from your client. You can test that all TLS-encrypted web traffic is
+working as expected by browsing to https://mitmproxy.org - it should show up as
+new flow and you can inspect it.
+
+Done.
diff --git a/docs/src/content/overview-installation.md b/docs/src/content/overview-installation.md
index 5b94adfc..1cdf62ad 100644
--- a/docs/src/content/overview-installation.md
+++ b/docs/src/content/overview-installation.md
@@ -34,20 +34,18 @@ the repository maintainers directly for issues with native packages.
 
 ## Windows
 
-
-All the mitmproxy tools are fully supported under 
-[WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/about). 
-We recommend to [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then
-follow the mitmproxy installation instructions for Linux.
+All the mitmproxy tools are fully supported under [WSL (Windows Subsystem for
+Linux)](https://docs.microsoft.com/en-us/windows/wsl/about). We recommend to
+[install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and
+then follow the mitmproxy installation instructions for Linux.
 
 We also distribute native Windows packages for all tools other than the
-mitmproxy console app, which only works under WSL. To install mitmproxy on Windows,
-download the installer from [mitmproxy.org](https://mitmproxy.org/).
+mitmproxy console app, which only works under WSL. To install mitmproxy on
+Windows, download the installer from [mitmproxy.org](https://mitmproxy.org/).
 After installation, you'll find shortcuts for mitmweb and mitmdump in the start
 menu. Both executables are added to your PATH and can be invoked from the
 command line.
 
-
 # Advanced Installation
 
 ## Development Setup
@@ -57,7 +55,6 @@ GitHub master branch, please see the our
 [README](https://github.com/mitmproxy/mitmproxy#installation)
 on GitHub.
 
-
 ## Installation from the Python Package Index (PyPI)
 
 If your mitmproxy addons require the installation of additional Python packages,
@@ -65,10 +62,10 @@ you can install mitmproxy from [PyPI](https://pypi.org/project/mitmproxy/).
 
 While there are plenty of options around[^1], we recommend the installation using pipx:
 
-[^1]: If you are familiar with the Python ecosystem, you may know that there are a million ways to install Python 
-    packages. Most of them (pip, virtualenv, pipenv, etc.) should just work, but we don't have the capacity to 
+[^1]: If you are familiar with the Python ecosystem, you may know that there are a million ways to install Python
+    packages. Most of them (pip, virtualenv, pipenv, etc.) should just work, but we don't have the capacity to
     provide support for it.
-    
+
 1. Install a recent version of Python (we require at least 3.6).
 2. Install [pipx](https://pipxproject.github.io/pipx/).
 3. `pipx install mitmproxy`
@@ -82,8 +79,10 @@ You can use the official mitmproxy images from
 
 ## Security Considerations for Binary Packages
 
-Our pre-compiled binary packages and Docker images include a self-contained Python 3 environment,  a recent version of 
-OpenSSL that support ALPN and HTTP/2, and other dependencies that would otherwise be cumbersome to compile and install.
+Our pre-compiled binary packages and Docker images include a self-contained
+Python 3 environment,  a recent version of OpenSSL that support ALPN and HTTP/2,
+and other dependencies that would otherwise be cumbersome to compile and
+install.
 
 Dependencies in the binary packages are frozen on release, and can't be updated
 in situ. This means that we necessarily capture any bugs or security issues that
@@ -92,4 +91,4 @@ dependencies (though we may do so if we become aware of a really serious issue).
 If you use our binary packages, please make sure you update regularly to ensure
 that everything remains current.
 
-As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks.
-\ No newline at end of file
+As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks.
diff --git a/docs/src/layouts/shortcodes/example.html b/docs/src/layouts/shortcodes/example.html
index d23cabb6..83a6075d 100644
--- a/docs/src/layouts/shortcodes/example.html
+++ b/docs/src/layouts/shortcodes/example.html
@@ -1,5 +1,4 @@
-
 <div class="example">
 {{ highlight (trim (readFile (.Get "src")) "\n\r") (.Get "lang") "" }}
 <div class="path">{{ (.Get "src" )}}</div>
-</div>
-\ No newline at end of file
+</div>
diff --git a/docs/upload-archive b/docs/upload-archive.sh
index 3aaeb9be..e35345e9 100755
--- a/docs/upload-archive
+++ b/docs/upload-archive.sh
@@ -1,5 +1,9 @@
-#!/bin/bash
-set -e
+#!/usr/bin/env bash
+
+set -o errexit
+set -o pipefail
+set -o nounset
+# set -o xtrace
 
 if [[ $# -eq 0 ]] ; then
     echo "Please supply a version, e.g. 'v3'"
diff --git a/docs/upload-stable b/docs/upload-stable.sh
index 5aea7479..a2f20f01 100755
--- a/docs/upload-stable
+++ b/docs/upload-stable.sh
@@ -1,5 +1,9 @@
-#!/bin/bash
-set -e
+#!/usr/bin/env bash
+
+set -o errexit
+set -o pipefail
+set -o nounset
+# set -o xtrace
 
 aws configure set preview.cloudfront true
 aws --profile mitmproxy \