docs: adjust docs layouts and add tables of contents

- add an auto-generated table of contents with markdown-toc
- docs pages now fill the whole page width; other pages are are 4/5ths wide as before
- clean up and reorganize some styles
- version dropdown moved to the left
- cleaned up the github edit link
- a couple of responsive cleanups
- add page title to HTML title attribute

Signed-off-by: Timothy Gerla <tim@gerla.net>

docs/website/assets/css/main.css

@@ -24,13 +24,8 @@ body {
   @apply flex flex-col min-h-screen;
 }
 
-.content {
-  flex: 1;
-}
-
 .c-rich-text a {
   color: #1a76c1;
-  font-weight: 400;
 }
 
 .c-rich-text a:hover {
@@ -38,7 +33,11 @@ body {
 }
 
 .c-rich-text ul {
-  @apply mb-4 list-outside pl-8
+  @apply mb-4 list-outside pl-8;
+}
+
+.c-rich-text ol {
+  @apply list-outside pl-4;
 }
 
 pre {
@@ -83,14 +82,6 @@ p a:hover {
   color: #12283a;
 }
 
-.kind-section #content,
-.section-docs #content {
-  @apply max-w-6xl mx-auto px-6;
-}
-.section-docs .page-heading {
-  @apply mb-1;
-}
-
 .header-anchor {
   @apply text-sm hidden align-top;
 }
@@ -107,7 +98,7 @@ h2:hover > a.header-anchor, h3:hover > a.header-anchor, h4:hover > a.header-anch
   the scroll lands with the header visible. 🤷‍♂️
 */
 
-h1::before, h2::before, h3::before {
+h1::before, h2::before, h3::before, h4::before {
   display: block;
   content: " ";
   margin-top: -100px;

docs/website/assets/css/tailwind.css

@@ -1,3 +1,14 @@
 @import 'tailwindcss/base';
 @import 'tailwindcss/components';
 @import 'tailwindcss/utilities';
+
+
+h1 {
+  @apply text-4xl;
+}
+h2 {
+  @apply text-2xl;
+}
+h3 {
+  @apply text-xl;
+}

docs/website/components/Content.vue

@@ -1,58 +1,22 @@
 <template>
-  <article class="max-w-3xl pt-1 pb-4 pl-6 pr-6 mx-auto c-rich-text">
+  <article class="c-rich-text">
     <div class="flex">
-      <h2 class="page-heading flex-grow">{{ doc.title }}</h2>
-      <a :href="gitPath" class="no-underline font-normal text-sm self-center"
-        ><img
-          src="/images/Git-Icon-Black.png"
-          height="14px"
-          width="14px"
-          class="inline-block mr-1"
-          alt=""
-        />
-        Edit this page
-      </a>
+      <h2 class="flex-grow">{{ doc.title }}</h2>
+      <GitHubLink
+        class="flex-grow-0 object-middle p-2 pt-4 md:pr-4"
+      ></GitHubLink>
     </div>
+
     <div v-html="doc.content" class="border-t pt-4"></div>
   </article>
 </template>
 
 <script>
+import GitHubLink from '~/components/GitHubLink.vue'
+
 export default {
   name: 'Content',
-
-  computed: {
-    doc() {
-      const sections = this.$store.state.sidebar.sections
-
-      // this is a hack to avoid breaking old (v0.3 and v0.4 only) deep links using '#' that look like:
-      //   /docs/v0.5/en/guides/cloud/digitalocean#creating-a-cluster-via-the-cli
-      // At 0.5, the # changed to a real path separator (/) and anchors ('#') are reserved for
-      // deep links to particular headings within the markdown file.
-      if (
-        this.$route.hash.startsWith('#v0.3') ||
-        this.$route.hash.startsWith('#v0.4')
-      ) {
-        return sections[this.$route.hash.substring(1)]
-      }
-
-      if (sections[this.$route.params.pathMatch])
-        return sections[this.$route.params.pathMatch]
-      else return sections[this.$store.state.sidebar.menu[0].path]
-    },
-    gitPath() {
-      const path =
-        'https://github.com/talos-systems/talos/edit/master/docs/website/content/'
-
-      return path + this.$route.params.pathMatch + '.md'
-    }
-  },
-
-  mounted() {
-    // if we hit the top-level, redirect to the first page in the doc set
-    if (!this.$route.params.pathMatch.includes('/')) {
-      this.$router.replace('/docs/' + this.$store.state.sidebar.menu[0].path)
-    }
-  }
+  components: { GitHubLink },
+  props: { doc: { type: Object, default() {} } }
 }
 </script>

docs/website/components/DocumentationDropdown.vue

@@ -1,6 +1,9 @@
 <template>
-  <div class="dropdown inline-block">
-    <button class="font-semibold py-2 pl-4 rounded inline-flex items-center">
+  <div>
+    <button
+      @click.prevent="active = !active"
+      class="font-semibold my-2 rounded inline-flex items-center"
+    >
       <span class="mr-1">{{ $store.state.sidebar.version }}</span>
       <svg
         id="dropdown-caret"
@@ -13,13 +16,12 @@
         />
       </svg>
     </button>
-    <ul class="dropdown-menu absolute pt-1 w-full shadow-md">
-      <li v-for="option in options" :key="option.version" class="">
-        <a
-          :href="option.url"
-          @click="handleClick(option)"
+    <ul v-show="active" class="pt-1 mb-4 w-full shadow-md">
+      <li v-for="option in options" :key="option.version">
+        <nuxt-link
+          :to="option.url"
           class="rounded-t py-2 px-4 block whitespace-no-wrap"
-          >{{ version(option) }}</a
+          >{{ version(option) }}</nuxt-link
         >
       </li>
     </ul>
@@ -36,15 +38,12 @@ export default {
         { version: 'v0.5', url: '/docs/v0.5', prerelease: true },
         { version: 'v0.4', url: '/docs/v0.4', prerelease: false },
         { version: 'v0.3', url: '/docs/v0.3', prerelease: false }
-      ]
+      ],
+      active: false
     }
   },
 
   methods: {
-    handleClick(option) {
-      this.$store.commit('sidebar/setVersion', option.version)
-    },
-
     version(option) {
       if (option.prerelease) {
         return `${option.version} (pre-release)`

docs/website/components/GitHubLink.vue

@@ -0,0 +1,41 @@
+<template>
+  <div class="text-gray-800">
+    <a :href="link"
+      ><svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="28"
+        height="28"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        class="feather feather-edit text-gray-800"
+      >
+        <title>Edit on GitHub</title>
+        <path
+          d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"
+        ></path>
+        <path
+          d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"
+        ></path>
+      </svg>
+    </a>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'GitHubLink',
+
+  computed: {
+    link() {
+      const path =
+        'https://github.com/talos-systems/talos/edit/master/docs/website/content/'
+
+      return path + this.$route.params.pathMatch + '.md'
+    }
+  }
+}
+</script>

docs/website/components/Header.vue

@@ -1,6 +1,6 @@
 <template>
   <header id="header">
-    <div class="flex flex-wrap w-4/5 mx-auto">
+    <div :class="{ 'w-4/5': narrowLogo }" class="flex flex-wrap mx-auto">
       <div class="flex py-2">
         <Logo></Logo>
       </div>
@@ -35,11 +35,18 @@ import EnterpriseLink from '~/components/EnterpriseLink.vue'
 
 export default {
   name: 'Header',
+
   components: {
     Logo,
     ProjectDropdown,
     CommunityDropdown,
     EnterpriseLink
+  },
+  props: {
+    narrowLogo: {
+      default: true,
+      type: Boolean
+    }
   }
 }
 </script>

docs/website/components/Sidebar.vue

@@ -1,6 +1,10 @@
 <template>
-  <div class="sidenav sticky py-4">
-    <div class="sidebar-heading mb-4">Documentation</div>
+  <nav id="sidenav" class="sidenav">
+    <div class="sidebar-heading">
+      Documentation
+    </div>
+    <DocumentationDropdown class="mb-4"></DocumentationDropdown>
+
     <ul>
       <li v-for="entry in $store.state.sidebar.menu" :key="entry.title">
         <span class="sidebar-category pt-4">{{ entry.title }}</span>
@@ -21,7 +25,7 @@
               <li
                 v-for="child in item.children"
                 :key="child.path"
-                class="sidebar-item my-2"
+                class="sidebar-item my-1"
               >
                 <nuxt-link :to="'/docs/' + child.path" class="block m-1">
                   <span class="p-2">{{ child.title }}</span>
@@ -32,19 +36,32 @@
         </ul>
       </li>
     </ul>
-  </div>
+  </nav>
 </template>
 
 <script>
+import DocumentationDropdown from '~/components/DocumentationDropdown.vue'
+
 export default {
-  name: 'Sidebar'
+  name: 'Sidebar',
+  components: {
+    DocumentationDropdown
+  }
 }
 </script>
 
 <style>
 .sidenav {
-  top: 7%;
-  @apply font-sans tracking-wide;
+  @apply font-sans tracking-wide bg-white;
+}
+
+.sidenav::before {
+  display: block;
+  content: ' ';
+  margin-top: -100px;
+  height: 100px;
+  visibility: hidden;
+  pointer-events: none;
 }
 
 .sidebar-heading {
@@ -56,7 +73,7 @@ export default {
 }
 
 .sidebar-item {
-  @apply text-gray-700 text-base text-sm;
+  @apply text-gray-700 text-sm;
 }
 
 .sidebar-subcategory {

docs/website/components/TableOfContents.vue

@@ -0,0 +1,28 @@
+<template>
+  <div>
+    <div class="text-gray-500 text-base font-bold uppercase">
+      Table of Contents
+    </div>
+    <nav class="text-sm">
+      <div id="toc" v-html="toc" class="pt-4 text-gray-700 text-sm"></div>
+    </nav>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'TableOfContents',
+  props: { toc: { type: String, default: '' } }
+}
+</script>
+
+<style>
+div#toc {
+  top: 90px;
+  @apply font-sans tracking-wide;
+}
+
+div#toc ul {
+  @apply pl-4;
+}
+</style>

docs/website/docgen.js

@@ -5,6 +5,7 @@ const fs = require('fs-extra')
 const glob = require('glob')
 const config = require('./docgen.config')
 const prism = require('markdown-it-prism')
+const mdToc = require('markdown-toc')
 const md = require('markdown-it')({ html: true, typographer: true })
   .use(require('markdown-it-anchor'), {
     permalink: true
@@ -192,7 +193,7 @@ const Docgen = {
       .replace('</p>\n', '')
 
     const markdownContent = md.render(frontmatterContent.body)
-
+    const toc = md.render(mdToc(frontmatterContent.body).content)
     // contentFilePath = /my_absolute_file/content/content-delivery/en/topics/introduction.md
 
     // contentPath = content-delivery/en/topics/introduction
@@ -220,7 +221,8 @@ const Docgen = {
       version: version, // content-delivery
       title: title, // title from frontmatter
       attributes: frontmatterContent.attributes, // all attributes from frontmatter
-      content: markdownContent // Markdown Content for left part of method section already as HTML
+      content: markdownContent, // Markdown Content for left part of method section already as HTML
+      toc: toc // table of contents
     }
 
     // check if version already exists in sections object

docs/website/layouts/default.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="flex flex-col min-h-screen">
-    <Header></Header>
+    <Header :narrowLogo="true"></Header>
     <main role="main" class="content">
       <nuxt />
     </main>

docs/website/layouts/doc.vue

@@ -0,0 +1,21 @@
+<template>
+  <div class="flex flex-col min-h-screen">
+    <Header :narrowLogo="false"></Header>
+    <main role="main" class="content">
+      <nuxt />
+    </main>
+    <Footer></Footer>
+  </div>
+</template>
+
+<script>
+import Header from '~/components/Header.vue'
+import Footer from '~/components/Footer.vue'
+
+export default {
+  components: {
+    Header,
+    Footer
+  }
+}
+</script>

docs/website/package-lock.json

@@ -2152,6 +2152,14 @@
       "resolved": "https://registry.npmjs.org/ansi-html/-/ansi-html-0.0.7.tgz",
       "integrity": "sha1-gTWEAhliqenm/QOflA0S9WynhZ4="
     },
+    "ansi-red": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/ansi-red/-/ansi-red-0.1.1.tgz",
+      "integrity": "sha1-jGOPnRCAgAo1PJwoyKgcpHBdlGw=",
+      "requires": {
+        "ansi-wrap": "0.1.0"
+      }
+    },
     "ansi-regex": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-4.1.0.tgz",
@@ -2165,6 +2173,11 @@
         "color-convert": "^1.9.0"
       }
     },
+    "ansi-wrap": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/ansi-wrap/-/ansi-wrap-0.1.0.tgz",
+      "integrity": "sha1-qCJQ3bABXponyoLoLqYDu/pF768="
+    },
     "anymatch": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-2.0.0.tgz",
@@ -2279,6 +2292,14 @@
       "resolved": "https://registry.npmjs.org/atob/-/atob-2.1.2.tgz",
       "integrity": "sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg=="
     },
+    "autolinker": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/autolinker/-/autolinker-0.28.1.tgz",
+      "integrity": "sha1-BlK0kYgYefB3XazgzcoyM5QqTkc=",
+      "requires": {
+        "gulp-header": "^1.7.1"
+      }
+    },
     "autoprefixer": {
       "version": "9.7.4",
       "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-9.7.4.tgz",
@@ -2315,6 +2336,11 @@
         "resolve": "^1.12.0"
       }
     },
+    "babel-helper-vue-jsx-merge-props": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/babel-helper-vue-jsx-merge-props/-/babel-helper-vue-jsx-merge-props-2.0.3.tgz",
+      "integrity": "sha512-gsLiKK7Qrb7zYJNgiXKpXblxbV5ffSwR0f5whkPAaBAR4fhi6bwRZxX9wBlIc5M/v8CCkXUbXZL4N/nSE97cqg=="
+    },
     "babel-loader": {
       "version": "8.1.0",
       "resolved": "https://registry.npmjs.org/babel-loader/-/babel-loader-8.1.0.tgz",
@@ -3200,6 +3226,11 @@
         "q": "^1.1.2"
       }
     },
+    "coffee-script": {
+      "version": "1.12.7",
+      "resolved": "https://registry.npmjs.org/coffee-script/-/coffee-script-1.12.7.tgz",
+      "integrity": "sha512-fLeEhqwymYat/MpTPUjSKHVYYl0ec2mOyALEMLmzr5i1isuG+6jfI2j2d5oBO3VIzgUXgBVIcOT9uH1TFxBckw=="
+    },
     "collection-visit": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/collection-visit/-/collection-visit-1.0.0.tgz",
@@ -3332,6 +3363,14 @@
         }
       }
     },
+    "concat-with-sourcemaps": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/concat-with-sourcemaps/-/concat-with-sourcemaps-1.1.0.tgz",
+      "integrity": "sha512-4gEjHJFT9e+2W/77h/DS5SGUgwDaOwprX8L/gl5+3ixnzkVJJsZWDSelmN3Oilw3LNDZjZV0yqH1hLG3k6nghg==",
+      "requires": {
+        "source-map": "^0.6.1"
+      }
+    },
     "connect": {
       "version": "3.7.0",
       "resolved": "https://registry.npmjs.org/connect/-/connect-3.7.0.tgz",
@@ -3933,6 +3972,11 @@
         "minimist": "^1.1.1"
       }
     },
+    "diacritics-map": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/diacritics-map/-/diacritics-map-0.1.0.tgz",
+      "integrity": "sha1-bfwP+dAQAKLt8oZTccrDFulJd68="
+    },
     "diffie-hellman": {
       "version": "5.0.3",
       "resolved": "https://registry.npmjs.org/diffie-hellman/-/diffie-hellman-5.0.3.tgz",
@@ -4906,6 +4950,52 @@
         }
       }
     },
+    "expand-range": {
+      "version": "1.8.2",
+      "resolved": "https://registry.npmjs.org/expand-range/-/expand-range-1.8.2.tgz",
+      "integrity": "sha1-opnv/TNf4nIeuujiV+x5ZE/IUzc=",
+      "requires": {
+        "fill-range": "^2.1.0"
+      },
+      "dependencies": {
+        "fill-range": {
+          "version": "2.2.4",
+          "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-2.2.4.tgz",
+          "integrity": "sha512-cnrcCbj01+j2gTG921VZPnHbjmdAf8oQV/iGeV2kZxGSyfYjjTyY79ErsK1WJWMpw6DaApEX72binqJE+/d+5Q==",
+          "requires": {
+            "is-number": "^2.1.0",
+            "isobject": "^2.0.0",
+            "randomatic": "^3.0.0",
+            "repeat-element": "^1.1.2",
+            "repeat-string": "^1.5.2"
+          }
+        },
+        "is-number": {
+          "version": "2.1.0",
+          "resolved": "https://registry.npmjs.org/is-number/-/is-number-2.1.0.tgz",
+          "integrity": "sha1-Afy7s5NGOlSPL0ZszhbezknbkI8=",
+          "requires": {
+            "kind-of": "^3.0.2"
+          }
+        },
+        "isobject": {
+          "version": "2.1.0",
+          "resolved": "https://registry.npmjs.org/isobject/-/isobject-2.1.0.tgz",
+          "integrity": "sha1-8GVWEJaj8dou9GJy+BXIQNh+DIk=",
+          "requires": {
+            "isarray": "1.0.0"
+          }
+        },
+        "kind-of": {
+          "version": "3.2.2",
+          "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-3.2.2.tgz",
+          "integrity": "sha1-MeohpzS6ubuw8yRm2JOupR5KPGQ=",
+          "requires": {
+            "is-buffer": "^1.1.5"
+          }
+        }
+      }
+    },
     "express": {
       "version": "4.17.1",
       "resolved": "https://registry.npmjs.org/express/-/express-4.17.1.tgz",
@@ -6125,6 +6215,38 @@
       "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.2.tgz",
       "integrity": "sha512-IItsdsea19BoLC7ELy13q1iJFNmd7ofZH5+X/pJr90/nRoPEX0DJo1dHDbgtYWOhJhcCgMDTOw84RZ72q6lB+Q=="
     },
+    "gray-matter": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-2.1.1.tgz",
+      "integrity": "sha1-MELZrewqHe1qdwep7SOA+KF6Qw4=",
+      "requires": {
+        "ansi-red": "^0.1.1",
+        "coffee-script": "^1.12.4",
+        "extend-shallow": "^2.0.1",
+        "js-yaml": "^3.8.1",
+        "toml": "^2.3.2"
+      },
+      "dependencies": {
+        "extend-shallow": {
+          "version": "2.0.1",
+          "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+          "integrity": "sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8=",
+          "requires": {
+            "is-extendable": "^0.1.0"
+          }
+        }
+      }
+    },
+    "gulp-header": {
+      "version": "1.8.12",
+      "resolved": "https://registry.npmjs.org/gulp-header/-/gulp-header-1.8.12.tgz",
+      "integrity": "sha512-lh9HLdb53sC7XIZOYzTXM4lFuXElv3EVkSDhsd7DoJBj7hm+Ni7D3qYbb+Rr8DuM8nRanBvkVO9d7askreXGnQ==",
+      "requires": {
+        "concat-with-sourcemaps": "*",
+        "lodash.template": "^4.4.0",
+        "through2": "^2.0.0"
+      }
+    },
     "gzip-size": {
       "version": "5.1.1",
       "resolved": "https://registry.npmjs.org/gzip-size/-/gzip-size-5.1.1.tgz",
@@ -7025,6 +7147,14 @@
         "launch-editor": "^2.2.1"
       }
     },
+    "lazy-cache": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/lazy-cache/-/lazy-cache-2.0.2.tgz",
+      "integrity": "sha1-uRkKT5EzVGlIQIWfio9whNiCImQ=",
+      "requires": {
+        "set-getter": "^0.1.0"
+      }
+    },
     "leven": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/leven/-/leven-3.1.0.tgz",
@@ -7056,6 +7186,43 @@
         "uc.micro": "^1.0.1"
       }
     },
+    "list-item": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/list-item/-/list-item-1.1.1.tgz",
+      "integrity": "sha1-DGXQDih8tmPMs8s4Sad+iewmilY=",
+      "requires": {
+        "expand-range": "^1.8.1",
+        "extend-shallow": "^2.0.1",
+        "is-number": "^2.1.0",
+        "repeat-string": "^1.5.2"
+      },
+      "dependencies": {
+        "extend-shallow": {
+          "version": "2.0.1",
+          "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+          "integrity": "sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8=",
+          "requires": {
+            "is-extendable": "^0.1.0"
+          }
+        },
+        "is-number": {
+          "version": "2.1.0",
+          "resolved": "https://registry.npmjs.org/is-number/-/is-number-2.1.0.tgz",
+          "integrity": "sha1-Afy7s5NGOlSPL0ZszhbezknbkI8=",
+          "requires": {
+            "kind-of": "^3.0.2"
+          }
+        },
+        "kind-of": {
+          "version": "3.2.2",
+          "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-3.2.2.tgz",
+          "integrity": "sha1-MeohpzS6ubuw8yRm2JOupR5KPGQ=",
+          "requires": {
+            "is-buffer": "^1.1.5"
+          }
+        }
+      }
+    },
     "load-json-file": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/load-json-file/-/load-json-file-2.0.0.tgz",
@@ -7358,6 +7525,35 @@
         "prismjs": "1.19.0"
       }
     },
+    "markdown-link": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/markdown-link/-/markdown-link-0.1.1.tgz",
+      "integrity": "sha1-MsXGUZmmRXMWMi0eQinRNAfIx88="
+    },
+    "markdown-toc": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/markdown-toc/-/markdown-toc-1.2.0.tgz",
+      "integrity": "sha512-eOsq7EGd3asV0oBfmyqngeEIhrbkc7XVP63OwcJBIhH2EpG2PzFcbZdhy1jutXSlRBBVMNXHvMtSr5LAxSUvUg==",
+      "requires": {
+        "concat-stream": "^1.5.2",
+        "diacritics-map": "^0.1.0",
+        "gray-matter": "^2.1.0",
+        "lazy-cache": "^2.0.2",
+        "list-item": "^1.1.1",
+        "markdown-link": "^0.1.1",
+        "minimist": "^1.2.0",
+        "mixin-deep": "^1.1.3",
+        "object.pick": "^1.2.0",
+        "remarkable": "^1.7.1",
+        "repeat-string": "^1.6.1",
+        "strip-color": "^0.1.0"
+      }
+    },
+    "math-random": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/math-random/-/math-random-1.0.4.tgz",
+      "integrity": "sha512-rUxjysqif/BZQH2yhd5Aaq7vXMSx9NdEsQcyA07uEzIvxgI7zIr33gGsh+RU0/XjmQpCW7RsVof1vlkvQVCK5A=="
+    },
     "md5.js": {
       "version": "1.3.5",
       "resolved": "https://registry.npmjs.org/md5.js/-/md5.js-1.3.5.tgz",
@@ -9593,6 +9789,23 @@
       "resolved": "https://registry.npmjs.org/querystring-es3/-/querystring-es3-0.2.1.tgz",
       "integrity": "sha1-nsYfeQSYdXB9aUFFlv2Qek1xHnM="
     },
+    "randomatic": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/randomatic/-/randomatic-3.1.1.tgz",
+      "integrity": "sha512-TuDE5KxZ0J461RVjrJZCJc+J+zCkTb1MbH9AQUq68sMhOMcy9jLcb3BrZKgp9q9Ncltdg4QVqWrH02W2EFFVYw==",
+      "requires": {
+        "is-number": "^4.0.0",
+        "kind-of": "^6.0.0",
+        "math-random": "^1.0.1"
+      },
+      "dependencies": {
+        "is-number": {
+          "version": "4.0.0",
+          "resolved": "https://registry.npmjs.org/is-number/-/is-number-4.0.0.tgz",
+          "integrity": "sha512-rSklcAIlf1OmFdyAqbnWTLVelsQ58uvZ66S/ZyawjWqIviTWCjg2PzVGw8WUA+nNuPTqb4wgA+NszrJ+08LlgQ=="
+        }
+      }
+    },
     "randombytes": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/randombytes/-/randombytes-2.1.0.tgz",
@@ -9855,6 +10068,15 @@
       "resolved": "https://registry.npmjs.org/relateurl/-/relateurl-0.2.7.tgz",
       "integrity": "sha1-VNvzd+UUQKypCkzSdGANP/LYiKk="
     },
+    "remarkable": {
+      "version": "1.7.4",
+      "resolved": "https://registry.npmjs.org/remarkable/-/remarkable-1.7.4.tgz",
+      "integrity": "sha512-e6NKUXgX95whv7IgddywbeN/ItCkWbISmc2DiqHJb0wTrqZIexqdco5b8Z3XZoo/48IdNVKM9ZCvTPJ4F5uvhg==",
+      "requires": {
+        "argparse": "^1.0.10",
+        "autolinker": "~0.28.0"
+      }
+    },
     "remove-trailing-separator": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/remove-trailing-separator/-/remove-trailing-separator-1.1.0.tgz",
@@ -10159,6 +10381,14 @@
       "integrity": "sha1-BF+XgtARrppoA93TgrJDkrPYkPc=",
       "dev": true
     },
+    "set-getter": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/set-getter/-/set-getter-0.1.0.tgz",
+      "integrity": "sha1-12nBgsnVpR9AkUXy+6guXoboA3Y=",
+      "requires": {
+        "to-object-path": "^0.3.0"
+      }
+    },
     "set-value": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/set-value/-/set-value-2.0.1.tgz",
@@ -10651,6 +10881,11 @@
       "integrity": "sha1-IzTBjpx1n3vdVv3vfprj1YjmjtM=",
       "dev": true
     },
+    "strip-color": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/strip-color/-/strip-color-0.1.0.tgz",
+      "integrity": "sha1-EG9l09PmotlAHKwOsM6LinArT3s="
+    },
     "strip-final-newline": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz",
@@ -11138,6 +11373,11 @@
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.0.tgz",
       "integrity": "sha512-yaOH/Pk/VEhBWWTlhI+qXxDFXlejDGcQipMlyxda9nthulaxLZUNcUqFxokp0vcYnvteJln5FNQDRrxj3YcbVw=="
     },
+    "toml": {
+      "version": "2.3.6",
+      "resolved": "https://registry.npmjs.org/toml/-/toml-2.3.6.tgz",
+      "integrity": "sha512-gVweAectJU3ebq//Ferr2JUY4WKSDe5N+z0FvjDncLGyHmIDoxgY/2Ie4qfEIDm4IS7OA6Rmdm7pdEEdMcV/xQ=="
+    },
     "toposort": {
       "version": "1.0.7",
       "resolved": "https://registry.npmjs.org/toposort/-/toposort-1.0.7.tgz",
@@ -11557,6 +11797,14 @@
         "lodash": "^4.17.11"
       }
     },
+    "vue-feather-icons": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/vue-feather-icons/-/vue-feather-icons-5.0.0.tgz",
+      "integrity": "sha512-uvi2l3i0aeRRzG3vX24/AH+8BkcXkSJboAv8XkUZ6aPkEC9n6LXDcKp5/ho+3moVQ9wlga3N6BjL89pmkHBzPw==",
+      "requires": {
+        "babel-helper-vue-jsx-merge-props": "^2.0.2"
+      }
+    },
     "vue-hot-reload-api": {
       "version": "2.3.4",
       "resolved": "https://registry.npmjs.org/vue-hot-reload-api/-/vue-hot-reload-api-2.3.4.tgz",

docs/website/package.json

@@ -18,9 +18,11 @@
     "markdown-it": "^10.0.0",
     "markdown-it-anchor": "^5.2.7",
     "markdown-it-prism": "^2.0.5",
+    "markdown-toc": "^1.2.0",
     "nuxt": "^2.12.0",
     "nuxt-webfontloader": "^1.1.0",
-    "prismjs": "^1.19.0"
+    "prismjs": "^1.19.0",
+    "vue-feather-icons": "^5.0.0"
   },
   "devDependencies": {
     "@nuxtjs/eslint-config": "^1.0.1",

docs/website/pages/docs/_.vue

@@ -1,16 +1,21 @@
 <template>
   <div>
-    <div id="content" class="content mb-4 section-docs">
-      <div class="flex justify-between">
-        <div class="c-rich-text"></div>
-        <DocumentationDropdown></DocumentationDropdown>
-      </div>
+    <div class="px-6 mb-4 section-docs">
       <div class="flex flex-wrap">
-        <div class="md:w-1/5 mt-1">
+        <div class="md:w-1/5 py-4">
           <Sidebar></Sidebar>
+          <div class="sidebar-sticky pt-1">
+            <a href="#sidenav"
+              ><chevrons-up-icon class="inline align-middle"></chevrons-up-icon>
+              Back to Top</a
+            >
           </div>
-        <div class="md:w-4/5 mt-1">
-          <Content></Content>
+        </div>
+        <div class="w-full md:w-3/5">
+          <Content :doc="doc" class="md:px-4"></Content>
+        </div>
+        <div class="md:w-1/5">
+          <TableOfContents :toc="doc.toc" class="py-4"></TableOfContents>
         </div>
       </div>
     </div>
@@ -18,25 +23,46 @@
 </template>
 
 <script>
+import { ChevronsUpIcon } from 'vue-feather-icons'
 import axios from 'axios'
-import DocumentationDropdown from '~/components/DocumentationDropdown.vue'
 import Sidebar from '~/components/Sidebar.vue'
 import Content from '~/components/Content.vue'
+import TableOfContents from '~/components/TableOfContents.vue'
 
 export default {
   name: 'Doc',
+  layout: 'doc',
   components: {
-    DocumentationDropdown,
     Sidebar,
-    Content
+    Content,
+    TableOfContents,
+    ChevronsUpIcon
   },
 
   head() {
     return {
-      bodyAttrs: {
-        class: 'kind-section section-docs'
+      title: this.doc.title + ' - Talos Documentation'
+    }
   },
-      title: 'Talos Documentation'
+
+  computed: {
+    doc() {
+      const sections = this.$store.state.sidebar.sections
+
+      // this is a hack to avoid breaking old (v0.3 and v0.4 only) deep links using '#' that look like:
+      //   /docs/v0.5/en/guides/cloud/digitalocean#creating-a-cluster-via-the-cli
+      // At 0.5, the # changed to a real path separator (/) and anchors ('#') are reserved for
+      // deep links to particular headings within the markdown file.
+      if (
+        this.$route.hash.startsWith('#v0.3') ||
+        this.$route.hash.startsWith('#v0.4')
+      ) {
+        return sections[this.$route.hash.substring(1)]
+      }
+
+      if (sections[this.$route.params.pathMatch])
+        return sections[this.$route.params.pathMatch]
+      else return sections[this.$store.state.sidebar.menu[0].path]
     }
   },
 
@@ -68,8 +94,20 @@ export default {
     store.commit('sidebar/setVersion', version)
     store.commit('sidebar/setSections', sections)
     store.commit('sidebar/setMenu', menu)
+  },
+
+  mounted() {
+    // if we hit the top-level, redirect to the first page in the doc set
+    if (!this.$route.params.pathMatch.includes('/')) {
+      this.$router.replace('/docs/' + this.$store.state.sidebar.menu[0].path)
+    }
   }
 }
 </script>
 
-<style></style>
+<style scoped>
+.sidebar-sticky {
+  position: sticky;
+  top: 88px;
+}
+</style>