Merge pull request #239 from filecoin-project/feat/154

feat: documentation navigation refactor

Author: cwaring

docs/.vuepress/config.js

@@ -1 +1,6 @@
-module.exports = []
+module.exports = [
+  { text: 'Get Started', link: '/' },
+  { text: 'Mine', link: '/mine/' },
+  { text: 'Build', link: '/build/' },
+  { text: 'Reference', link: '/reference/' }
+]

docs/.vuepress/nav/en.js

@@ -0,0 +1,78 @@
+<template>
+  <nav v-if="bread.length > 1" class="breadcrumbs fixed">
+    <div class="nav-wrapper">
+      <router-link
+        class="breadcrumb"
+        v-for="crumb in bread"
+        :key="crumb.path"
+        :to="crumb.path"
+        >{{ crumb.title }}</router-link
+      >
+    </div>
+  </nav>
+</template>
+
+<script>
+export default {
+  name: 'Breadcrumbs',
+  computed: {
+    bread() {
+      const parts = this.$page.path.split('/')
+      if (!parts[parts.length - 1].length) {
+        parts.pop()
+      }
+      let link = ''
+      const crumbs = []
+      for (let i = 0; i < parts.length; i++) {
+        link += parts[i]
+        const page = this.$site.pages.find(
+          el => el.path === link || el.path === link + '/'
+        )
+        link += '/'
+        if (page != null) {
+          crumbs.push({
+            path: page.path,
+            title: page.frontmatter.breadcrumb || page.title
+          })
+        }
+      }
+      return crumbs
+    }
+  }
+}
+</script>
+
+<style lang="stylus" scoped>
+nav
+  border-bottom 1px solid #eaecef
+  font-size 0.9em
+  padding: 1.5rem 2rem
+
+  @media (min-width: $MQNarrow)
+    margin: 0 2.5rem
+    padding: 1.5rem 0
+
+  &.fixed
+    position fixed
+    z-index 5
+    background-color #fff
+    width 100%
+    max-width 740px
+    display flex
+.breadcrumb
+  margin-right: 0.5em
+  color: $sidebarTextColor;
+  opacity: 0.7;
+  font-weight 600
+  transition: opacity 0.5s;
+  &:not(:first-child)::before
+    margin-right: 0.5em
+    content "/"
+    font-family inherit
+    font-size inherit
+
+  &:last-child
+  &:hover
+    opacity 1
+    color: $accentColor
+</style>

docs/.vuepress/theme/components/Breadcrumbs.vue

@@ -1,7 +1,7 @@
 <template>
   <main class="page">
     <slot name="top" />
-
+    <Breadcrumbs />
     <Content v-if="!isHome" class="theme-default-content" />
     <Home v-else-if="isHome" />
     <div class="content-footer" v-if="!isContentStatus && !isHome">
@@ -26,6 +26,7 @@
 import PageEdit from '@parent-theme/components/PageEdit.vue'
 import PageNav from '@parent-theme/components/PageNav.vue'
 
+import Breadcrumbs from './Breadcrumbs.vue'
 import Feedback from './Feedback.vue'
 import LegacyCallout from './LegacyCallout.vue'
 import Analytics from './Analytics.vue'
@@ -37,6 +38,7 @@ export default {
   components: {
     PageEdit,
     PageNav,
+    Breadcrumbs,
     Feedback,
     LegacyCallout,
     Analytics,
@@ -54,18 +56,32 @@ export default {
   },
   methods: {
     smoothScroll: function () {
-      var root = document.getElementsByTagName('html')[0]
+      const root = document.getElementsByTagName('html')[0]
       // only enable smooth-scrolling on pages shorter that 15000 px
       return root.scrollHeight < 15000
         ? root.classList.add('smooth-scroll')
         : root.classList.remove('smooth-scroll')
+    },
+    htmlRouteClass: function () {
+      // patch to apply a root class for styling elements
+      // any path that isn't a primary nav item will add the route-index class
+      const root = document.getElementsByTagName('html')[0]
+      const path = this.$page.path
+      const navItems = this.$themeConfig.locales['/'].nav
+        .slice(1)
+        .map(a => a.link)
+      navItems.some(i => path.includes(i))
+        ? root.classList.remove('route-index')
+        : root.classList.add('route-index')
     }
   },
   mounted: function () {
     this.smoothScroll()
+    this.htmlRouteClass()
   },
   updated: function () {
     this.smoothScroll()
+    this.htmlRouteClass()
   }
 }
 </script>
@@ -76,6 +92,10 @@ export default {
   display: block;
 }
 
+.breadcrumbs.fixed + .theme-default-content {
+  padding-top: 6em;
+}
+
 .content-footer {
   padding-top: 0;
   max-width: $contentWidth;

docs/.vuepress/theme/components/Page.vue

@@ -1,14 +1,24 @@
 @media (min-width: $MQNarrow) {
-	header.navbar .links {
+	header.navbar {
 		display: flex;
-		flex-direction: row-reverse;
 
-		input, .suggestions {
-			width: 10em;
+		.home-link {
+			padding-right: 4rem;
 		}
 
-		input:focus, .suggestions {
-			width: 20em;
+		.links {
+			position: static;
+			flex: 1 1 auto;
+			justify-content: space-between;
+			flex-direction: row-reverse;
+
+			input, .suggestions {
+				width: 10em;
+			}
+
+			input:focus, .suggestions {
+				width: 20em;
+			}
 		}
 	}
 }

docs/.vuepress/theme/styles/header.styl

@@ -5,9 +5,9 @@
 @import 'sidebar';
 @import 'video';
 
-// stop sidebar taking up horizontal width and adjusting layout position
 html {
-	margin-left: calc(100vw - 100%);
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
 }
 
 // apply scrolling by default excluding firefox due to trigger issues

docs/.vuepress/theme/styles/index.styl

@@ -3,37 +3,40 @@ ul > li > a.sidebar-link {
 	font-weight: 500;
 }
 
-ul.sidebar-links > li > a {
-	color: inherit;
+header.navbar .nav-links {
+	display: none;
 }
 
-.sidebar {
-	.sidebar-heading {
-		font-weight: 700 !important;
-	}
+#app .sidebar {
+	.nav-links {
+		display: block !important;
 
-	.sidebar-group .arrow {
-		display: none;
+		.nav-item {
+			margin-left: 0;
+			font-size: 1em;
+		}
 	}
 
-	.sidebar-group.is-sub-group a.sidebar-link {
-		margin-bottom: 0.2rem;
+	.sidebar-group-items {
+		font-size: 1em !important;
+
+		> li .sidebar-link {
+			font-size: 0.95em !important;
+		}
 	}
 
-	.sidebar-group.is-sub-group {
-		margin-bottom: 0.5rem;
+	> .sidebar-links > li > a.sidebar-link, .sidebar-heading {
+		font-weight: bold !important;
+		font-size: 1em;
 	}
 
-	.sidebar-links.sidebar-group-items li:last-child .sidebar-group.is-sub-group {
-		margin-bottom: 0;
+	.sidebar-group.is-sub-group a.sidebar-link {
+		margin-bottom: 0.2rem;
 	}
 
 	.sidebar-group.is-sub-group > .sidebar-heading:not(.clickable) {
-		opacity: 1;
-		font-weight: bold;
 		text-transform: uppercase;
 		font-size: 0.8rem;
-		letter-spacing: 0.05em;
 		line-height: 2em;
 	}
 }
@@ -43,23 +46,77 @@ ul.sidebar-links > li > a {
 }
 
 // sidebar scrollbar style
-.sidebar::-webkit-scrollbar {
+.sidebar-links::-webkit-scrollbar {
 	width: 5px;
 	position: fixed;
 	right: 0;
 }
 
-.sidebar::-webkit-scrollbar-thumb {
+.sidebar-links::-webkit-scrollbar-thumb {
 	background: transparent;
 	transition: background-color 2s;
 }
 
-.sidebar::-webkit-scrollbar-thumb:hover, .sidebar:hover::-webkit-scrollbar-thumb {
+.sidebar-links::-webkit-scrollbar-thumb:hover, .sidebar-links:hover::-webkit-scrollbar-thumb {
 	background: $borderColor;
 }
 
 @media (max-width: $MQMobile) {
 	.sidebar {
 		width: 80vw;
 	}
+}
+
+// style selected sidebar item based on route class
+html.route-index {
+	.sidebar .nav-links .nav-item:first-child {
+		a.nav-link {
+			color: $accentColor;
+		}
+	}
+}
+
+@media (min-width: $MQMobile) {
+	aside.sidebar {
+		display: flex;
+		flex-direction: column;
+		height: 100vh;
+		overflow: hidden;
+
+		> .sidebar-links {
+			padding: 1rem 0;
+
+			a {
+				&.active {
+					opacity: 1;
+
+					a {
+						opacity: 1;
+					}
+				}
+
+				opacity: 0.7;
+				transition: opacity 0.5s;
+			}
+
+			&:hover a {
+				opacity: 1;
+			}
+
+			overflow: auto;
+			padding-bottom: 6em;
+		}
+
+		.nav-links, .nav-links a {
+			display: block;
+		}
+
+		.nav-item > a:not(.external) {
+			&:hover, &.router-link-active {
+				margin-bottom: 0px;
+				border-bottom: none;
+				color: $accentColor;
+			}
+		}
+	}
 }

docs/.vuepress/theme/styles/sidebar.styl

@@ -2,6 +2,7 @@
 title: Filecoin Documentation
 description: The homepage for Filecoin documentation.
 homepage: true
+breadcrumb: Home
 ---
 
 # Filecoin Documentation

docs/README.md

@@ -1,6 +1,7 @@
 ---
 title: Mining in Filecoin
 description: An overview of everything mining-related on the Filecoin network.
+breadcrumb: Mine
 ---
 
 # Mining in Filecoin
@@ -67,11 +68,11 @@ In Filecoin, miners earn two different types of rewards for their efforts: stora
 **Block rewards** are large sums that are given to the miner credited for a new block. Unlike storage fees, these rewards do not come from an associated client; rather, the network "prints" new FIL as both an inflationary measure and an incentive to miners advancing the chain. All active miners on the network have a chance at recieving a block reward, their chance at such being directly proportional to the amount of storage space currently being contributed to the network.
 
 ### WinningPoSt
+
 WinningPoSt is the mechanism by which storage miners are rewarded for their contributions. In the Filecoin network, time is discretized into a series of epochs – the blockchain’s height corresponds to the number of elapsed epochs. At the beginning of each epoch, a small number of storage miners are elected to mine new blocks (Filecoin utilizes tipsets, which permit multiple blocks to be mined at the same height). Each elected miner who successfully creates a block is granted FIL, as well as the opportunity to charge other nodes fees to include messages in the block.
 
 To further incentivize the storage of “useful” data over simple capacity commitments, storage miners have the additional opportunity to compete for special deals offered by verified clients. Such clients are certified with respect to their intent to offer deals involving the storage of meaningful data, and the power a storage miner earns for these deals is augmented by a multiplier. The total amount of power a given storage miner has, after accounting for this multiplier, is known as **quality-adjusted power**.
 
-
 ## Uptime, slashing and penalties
 
 "Slashing" is a feature present in most blockchain protocols, and is used to penalise miners that either fail to provide reliable uptime or act maliciously against the network.