various docs improvements

- add clickable anchors for headers
- add "outdated" warning for archived docs
- add "edit on github" button
- beautify template

15 files changed, 141 insertions, 96 deletions

diff --git a/docs/build-archive b/docs/build-archive
new file mode 100755
index 00000000..bd11d86e
--- /dev/null
+++ b/docs/build-archive
@@ -0,0 +1,5 @@
+#!/bin/sh
+set -e
+
+cd src
+DOCS_ARCHIVE=true hugo
diff --git a/docs/build b/docs/build-current
index 53721eb1..a78acab4 100755
--- a/docs/build
+++ b/docs/build-current
@@ -1,4 +1,5 @@
 #!/bin/sh
 set -e
 
-cd src; hugo
+cd src
+hugo
diff --git a/docs/ci b/docs/ci
index b2f2252f..107e8370 100755
--- a/docs/ci
+++ b/docs/ci
@@ -3,7 +3,7 @@ set -e
 
 # This script gets run from CI to render and upload docs
 
-./build
+./build-current
 
 # Only upload if we have defined credentials - we only have these defined for
 # trusted commits (i.e. not PRs).
diff --git a/docs/src/content/_index.md b/docs/src/content/_index.md
index a977e2db..44d41611 100644
--- a/docs/src/content/_index.md
+++ b/docs/src/content/_index.md
@@ -1,5 +1,6 @@
 ---
 title: "Introduction"
+layout: single
 menu:
     overview:
         weight: 1
diff --git a/docs/src/layouts/_default/single.html b/docs/src/layouts/_default/single.html
index 4a8baf53..801b6341 100644
--- a/docs/src/layouts/_default/single.html
+++ b/docs/src/layouts/_default/single.html
@@ -1,10 +1,12 @@
-{{ partial "header.html" . }}
-<div class="columns">
-    <div class="column is-one-quarter sidebody">
-        {{ partial "sidebar.html" . }}
+{{ partial "header" . }}
+<div class="columns container is-marginless">
+    <div id="sidebar" class="column is-one-quarter">
+        {{ partial "sidebar" . }}
     </div>
-    <div class="column content mainbody">
-        {{.Content}}
+    <div id="main" class="column content">
+        {{ partial "outdated" . }}
+        {{ partial "edit-on-github" . }}
+        {{ partial "add-anchors" .Content}}
     </div>
 </div>
 {{ partial "footer.html" . }}
diff --git a/docs/src/layouts/index.html b/docs/src/layouts/index.html
deleted file mode 100644
index 4a8baf53..00000000
--- a/docs/src/layouts/index.html
+++ /dev/null
@@ -1,10 +0,0 @@
-{{ partial "header.html" . }}
-<div class="columns">
-    <div class="column is-one-quarter sidebody">
-        {{ partial "sidebar.html" . }}
-    </div>
-    <div class="column content mainbody">
-        {{.Content}}
-    </div>
-</div>
-{{ partial "footer.html" . }}
diff --git a/docs/src/layouts/partials/add-anchors.html b/docs/src/layouts/partials/add-anchors.html
new file mode 100644
index 00000000..f7050f7f
--- /dev/null
+++ b/docs/src/layouts/partials/add-anchors.html
@@ -0,0 +1 @@
+{{ . | replaceRE "(<h[1-9] id=\"(.+?)\".*?>)(.+?</h[1-9]>)" "${1}<a class=\"anchor\" href=\"#${2}\">#&nbsp;&nbsp;</a>${3}" | safeHTML }}
diff --git a/docs/src/layouts/partials/edit-on-github.html b/docs/src/layouts/partials/edit-on-github.html
new file mode 100644
index 00000000..d2c3098c
--- /dev/null
+++ b/docs/src/layouts/partials/edit-on-github.html
@@ -0,0 +1,9 @@
+{{ if and .IsPage (not (getenv "DOCS_ARCHIVE")) }}
+<a class="button is-small is-outlined is-link is-pulled-right"
+   target="_blank"
+   href="https://github.com/mitmproxy/mitmproxy/blob/master/docs/src/content/{{ .File.Path }}"
+>
+    Edit on GitHub
+</a>
+{{ end }}
+
diff --git a/docs/src/layouts/partials/outdated.html b/docs/src/layouts/partials/outdated.html
new file mode 100644
index 00000000..5b3dd6ed
--- /dev/null
+++ b/docs/src/layouts/partials/outdated.html
@@ -0,0 +1,9 @@
+{{- if (getenv "DOCS_ARCHIVE") -}}
+<article class="message is-warning">
+    <div class="message-body">
+        You are not viewing the most up to date version of the documentation.
+        Click <a href="https://docs.mitmproxy.org/stable{{ .Page.URL }}">here</a>
+        to view the latest version.
+    </div>
+</article>
+{{- end -}}
diff --git a/docs/src/layouts/partials/sidebar.html b/docs/src/layouts/partials/sidebar.html
index ef853fc6..5ea41c12 100644
--- a/docs/src/layouts/partials/sidebar.html
+++ b/docs/src/layouts/partials/sidebar.html
@@ -1,24 +1,22 @@
-<div class="sidebar">
-    <div class="brand">
-        <img src='{{"logo-docs.png" | relURL}}' alt="mitmproxy docs">
-    </div>
-    <div class="version">
-        <span class="tag is-info is-rounded is-medium">v3.x</span>
-    </div>
-    <aside class="menu">
-        <p class="menu-label"> Overview </p>
-        {{ partial "sidemenu" (dict "ctx" . "menuname" "overview") }}
+<div class="brand">
+    <a href="https://mitmproxy.org/">
+        <img src='{{"logo-docs.png" | relURL}}' alt="mitmproxy docs"/>
+    </a>
 
-        <p class="menu-label">Core concepts</p>
-        {{ partial "sidemenu" (dict "ctx" . "menuname" "concepts") }}
+</div>
+<nav class="menu">
+    <p class="menu-label"> Overview </p>
+    {{ partial "sidemenu" (dict "ctx" . "menuname" "overview") }}
 
-        <p class="menu-label"> Addon Development </p>
-        {{ partial "sidemenu" (dict "ctx" . "menuname" "addons") }}
+    <p class="menu-label">Core concepts</p>
+    {{ partial "sidemenu" (dict "ctx" . "menuname" "concepts") }}
 
-        <p class="menu-label"> HOWTOs </p>
-        {{ partial "sidemenu" (dict "ctx" . "menuname" "howto") }}
+    <p class="menu-label"> Addon Development </p>
+    {{ partial "sidemenu" (dict "ctx" . "menuname" "addons") }}
 
-        <p class="menu-label"> Tutorials </p>
-        {{ partial "sidemenu" (dict "ctx" . "menuname" "tutes") }}
-    </aside>
-</div>
\ No newline at end of file
+    <p class="menu-label"> HOWTOs </p>
+    {{ partial "sidemenu" (dict "ctx" . "menuname" "howto") }}
+
+    <p class="menu-label"> Tutorials </p>
+    {{ partial "sidemenu" (dict "ctx" . "menuname" "tutes") }}
+</nav>
diff --git a/docs/src/static/logo-docs.png b/docs/src/static/logo-docs.png
index b37dbd85..a46016dd 100644
--- a/docs/src/static/logo-docs.png
+++ b/docs/src/static/logo-docs.png
diff --git a/docs/src/themes/mitmproxydocs/static/css/style.css b/docs/src/themes/mitmproxydocs/static/css/style.css
index ccd0e3ff..db5a36cf 100644
--- a/docs/src/themes/mitmproxydocs/static/css/style.css
+++ b/docs/src/themes/mitmproxydocs/static/css/style.css
@@ -6717,9 +6717,17 @@ label.panel-block {
   background-color: whitesmoke;
   padding: 3rem 1.5rem 6rem; }
 
-.sidebody {
-  overflow-x: hidden;
-  overflow-y: scroll; }
+#sidebar {
+  background-color: #eee;
+  border-right: 1px solid #c1c1c1;
+  box-shadow: 0 0 20px rgba(50, 50, 50, 0.2) inset;
+  padding: 1.75rem; }
+  #sidebar .brand {
+    padding: 1rem 0;
+    text-align: center; }
+
+#main {
+  padding: 3rem; }
 
 .example {
   margin-bottom: 1em; }
@@ -6730,21 +6738,6 @@ label.panel-block {
     width: 100%;
     text-align: right; }
 
-.sidebar {
-  background-color: #F1F1F1; }
-  .sidebar .version {
-    padding: 1em; }
-  .sidebar .brand {
-    background-color: #303030;
-    color: #c0c0c0;
-    padding: 1em;
-    top: 0; }
-  .sidebar .menu {
-    padding: 1em; }
-
-.mainbody {
-  padding: 3em; }
-
 code {
   color: #1a9f1a;
   font-size: 0.875em;
@@ -6754,5 +6747,25 @@ code {
   padding-top: 1em;
   border-top: 1px solid #c0c0c0; }
 
+h1 .anchor, h2 .anchor, h3 .anchor, h4 .anchor, h5 .anchor, h6 .anchor {
+  display: inline-block;
+  width: 0;
+  margin-left: -1.5rem;
+  margin-right: 1.5rem;
+  transition: all 100ms ease-in-out;
+  opacity: 0; }
+
+h1:hover .anchor, h2:hover .anchor, h3:hover .anchor, h4:hover .anchor, h5:hover .anchor, h6:hover .anchor {
+  opacity: 1; }
+
+h1:target, h2:target, h3:target, h4:target, h5:target, h6:target {
+  color: #C93312; }
+  h1:target .anchor, h2:target .anchor, h3:target .anchor, h4:target .anchor, h5:target .anchor, h6:target .anchor {
+    opacity: 1;
+    color: #C93312; }
+
+.footnotes p {
+  display: inline; }
+
 figure.has-border img {
   box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.25); }
diff --git a/docs/style/style.scss b/docs/style/style.scss
index 2db14100..2b0d2993 100644
--- a/docs/style/style.scss
+++ b/docs/style/style.scss
@@ -10,56 +10,72 @@ $family-sans-serif: BlinkMacSystemFont, -apple-system, "Segoe UI", "Roboto", "Ox
 @import "../node_modules/bulma/sass/components/_all";
 @import "../node_modules/bulma/sass/layout/_all";
 
-.sidebody {
-  overflow-x: hidden;
-  overflow-y: scroll;
-}
+#sidebar {
+    background-color: #eee;
+    border-right: 1px solid #c1c1c1;
+    box-shadow: 0 0 20px rgba(50, 50, 50, .2) inset;
+    padding: $column-gap + 1rem;
 
-.example {
-  .highlight {
-    margin: 0;
-  }
-  .path {
-    font-style: italic;
-    width: 100%;
-    text-align: right;
-  }
-  margin-bottom: 1em;
+    .brand {
+        padding: 1rem 0;
+        text-align: center;
+    }
 }
 
-.sidebar {
-  background-color: #F1F1F1;
-  .version {
-    padding: 1em;
-  }
-  .brand {
-    background-color: #303030;
-    color: #c0c0c0;
-    padding: 1em;
-    top: 0;
-  }
-  .menu {
-    padding: 1em;
-  }
+#main {
+    padding: 3rem;
 }
 
-.mainbody {
-  padding: 3em;
+.example {
+    .highlight {
+        margin: 0;
+    }
+    .path {
+        font-style: italic;
+        width: 100%;
+        text-align: right;
+    }
+    margin-bottom: 1em;
 }
 
 code {
-  color: #1a9f1a;
-  font-size: 0.875em;
-  font-weight: normal;
+    color: #1a9f1a;
+    font-size: 0.875em;
+    font-weight: normal;
 }
 
 .content {
-  h2 {
-    padding-top: 1em;
-    border-top: 1px solid #c0c0c0;
-  }
+    h2 {
+        padding-top: 1em;
+        border-top: 1px solid #c0c0c0;
+    }
+}
+
+h1, h2, h3, h4, h5, h6 {
+    .anchor {
+        display: inline-block;
+        width: 0;
+        margin-left: -1.5rem;
+        margin-right: 1.5rem;
+        transition: all 100ms ease-in-out;
+        opacity: 0;
+    }
+    &:hover .anchor {
+        opacity: 1;
+    }
+    &:target {
+        color: $primary;
+        .anchor {
+            opacity: 1;
+            color: $primary
+        }
+    }
+}
+
+.footnotes p {
+    display: inline;
 }
 
 figure.has-border img {
-  box-shadow: 0 0 20px 0 rgba(0,0,0,0.25);
+    box-shadow: 0 0 20px 0 rgba(0, 0, 0, 0.25);
 }
diff --git a/docs/upload-archive b/docs/upload-archive
index 1641c50a..7548dd5b 100755
--- a/docs/upload-archive
+++ b/docs/upload-archive
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 set -e
 
 if [[ $# -eq 0 ]] ; then
diff --git a/docs/upload-stable b/docs/upload-stable
index e7dbcad3..a0c4dfc8 100755
--- a/docs/upload-stable
+++ b/docs/upload-stable
@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 set -e
 
 aws configure set preview.cloudfront true