diff --git a/_config.yml b/_config.yml
index cea599ae08..4d98e8efcd 100644
--- a/_config.yml
+++ b/_config.yml
@@ -15,52 +15,65 @@ defaults:
   - scope:
       path: "*"
     values:
-      root: "."
+      root: "../.."
   - scope:
       path: "*/*"
     values:
-      root: ".."
+      root: "../../.."
+  - scope:
+      path: "*/*/*"
+    values:
+      root: "../../../.."
 
-default_root: ".."
+default_root: "../../.."
 
 collections_dir: docs
 collections:
   install-and-build:
     output: true
+    permalink: docs/:collection/:slug
     caption: Install and build
     sidebar_index: 1
     frontpage: _install-and-build/Installing-Geth.md
   interface:
     output: true
+    permalink: docs/:collection/:slug
     caption: Interacting with Geth
     sidebar_index: 2
   support:
     output: true
+    permalink: docs/:collection/:slug
     caption: Issues and support
     sidebar_index: 3
   developers:
     output: true
+    permalink: docs/:collection/:slug
     caption: Developer docs
     sidebar_index: 4
   clef:
     output: true
+    permalink: docs/:collection/:slug
     caption: Clef
     sidebar_index: 5
     frontpage: _clef/Overview.md
   whisper:
     output: true
+    permalink: docs/:collection/:slug
     caption: Whisper
     sidebar_index: 6
     frontpage: _whisper/Whisper-Overview.md
   rpc:
     output: true
+    permalink: docs/:collection/:slug
     caption: JSON RPC APIs
     sidebar_index: 7
   doc:
     output: true
+    permalink: docs/:collection/:slug
     caption: Other
     sidebar_index: 8
   legacy:
     output: true
+    permalink: docs/:collection/:slug
     caption: Legacy content
     sidebar_index: 9
diff --git a/_data/navbar.yml b/_data/navbar.yml
index 4ad130e2ae..d85d1d6868 100644
--- a/_data/navbar.yml
+++ b/_data/navbar.yml
@@ -1,3 +1,3 @@
-Install: /install-and-build/Installing-Geth
+Install: /docs/install-and-build/installing-geth
 Downloads: /downloads
 Documentation: /docs
diff --git a/_includes/link.html b/_includes/link.html
index 07b7a54722..b66e4a17e1 100644
--- a/_includes/link.html
+++ b/_includes/link.html
@@ -1 +1 @@
-{% if page.root %}{% assign root=page.root %}{% else %}{% assign root=site.default_root %}{% endif %}{{ include.url | remove: ".html" | prepend: root | replace: '//', '/' }}
+{% if page.root %}{% assign root=page.root %}{% else %}{% assign root=site.default_root %}{% endif %}{{ include.url | remove: ".html" | prepend: root | replace: '//', '/' }}
\ No newline at end of file
diff --git a/_layouts/default.html b/_layouts/default.html
index 0d7bc47a43..34dd1b4487 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -26,7 +26,7 @@ common-js:
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
           </button>
-          <a class="navbar-brand" href="{% include link.html url='' %}/">Go Ethereum</a>
+          <a class="navbar-brand" href="{% include link.html url='' %}">Go Ethereum</a>
         </div>
         <div id="navbar" class="navbar-collapse collapse">
           <ul class="nav navbar-nav">
diff --git a/docs/_clef/Overview.md b/docs/_clef/Overview.md
index 2c31055ba5..f38949f71b 100644
--- a/docs/_clef/Overview.md
+++ b/docs/_clef/Overview.md
@@ -24,9 +24,9 @@ or a separate VM in a [QubesOS](https://www.qubes-os.org/) type os setup.
 
 Check out 
 
-* the [tutorial](Tutorial) for some concrete examples on how the signer works.
-* the [setup docs](Setup) for some information on how to configure it to work on QubesOS or USBArmory. 
-* more info about [rules](Rules)
+* the [tutorial](tutorial) for some concrete examples on how the signer works.
+* the [setup docs](setup) for some information on how to configure it to work on QubesOS or USBArmory. 
+* more info about [rules](rules)
 * the [data types](datatypes) for detailed information on the json types used in the communication between
   clef and an external UI 
 
@@ -65,7 +65,7 @@ Clef relies on __sign-what-you-see__. To provide as much context as possible,
 One setup scenario is to use virtualization, e.g. within QubesOS, where to 
 Clef is deployed on a non-networked machine (`ethvault` below)
 
-![](./qubes/clef_qubes_qrexec.png)
+![](clef_qubes_qrexec.png)
 
 
 Another option is to deploy Clef on a separate physical device, e.g. USB Armory, 
diff --git a/docs/_clef/Setup.md b/docs/_clef/Setup.md
index 1ced8e9a03..f4b083780d 100644
--- a/docs/_clef/Setup.md
+++ b/docs/_clef/Setup.md
@@ -40,7 +40,7 @@ There are two ways that this can be achieved: integrated via Qubes or integrated
 Qubes provdes a facility for inter-qubes communication via `qrexec`. A qube can request to make a cross-qube RPC request 
 to another qube. The OS then asks the user if the call is permitted. 
 
-![Example](qubes/qrexec-example.png)
+![Example](qrexec-example.png)
 
 A policy-file can be created to allow such interaction. On the `target` domain, a service is invoked which can read the
 `stdin` from the `client` qube. 
@@ -49,11 +49,11 @@ This is how [Split GPG](https://www.qubes-os.org/doc/split-gpg/) is implemented.
 
 ##### Server
 
-![Clef via qrexec](qubes/clef_qubes_qrexec.png)
+![Clef via qrexec](clef_qubes_qrexec.png)
 
 On the `target` qubes, we need to define the rpc service.
 
-[qubes.Clefsign](qubes/qubes.Clefsign):
+[qubes.Clefsign](qubes.Clefsign):
 
 ```bash
 #!/bin/bash
@@ -97,7 +97,7 @@ with minimal requirements.
 On the `client` qube, we need to create a listener which will receive the request from the Dapp, and proxy it. 
 
 
-[qubes-client.py](qubes/client/qubes-client.py):
+[qubes-client.py](qubes-client.py):
 
 ```python
 
@@ -140,11 +140,11 @@ $ cat newaccnt.json| qrexec-client-vm debian-work qubes.Clefsign
 
 This should pop up first a dialog to allow the IPC call:
 
-![one](qubes/qubes_newaccount-1.png)
+![one](qubes_newaccount-1.png)
 
 Followed by a GTK-dialog to approve the operation
 
-![two](qubes/qubes_newaccount-2.png)
+![two](qubes_newaccount-2.png)
 
 To test the full flow, we use the client wrapper. Start it on the `client` qube:
 ```
@@ -182,7 +182,7 @@ However, it comes with a couple of drawbacks:
 The second way to set up Clef on a qubes system is to allow networking, and have Clef listen to a port which is accessible
 form other qubes. 
 
-![Clef via http](qubes/clef_qubes_http.png)
+![Clef via http](clef_qubes_http.png)
 
 
 
diff --git a/docs/_clef/apis.md b/docs/_clef/apis.md
index d1bfb481e6..1bfad02ab9 100644
--- a/docs/_clef/apis.md
+++ b/docs/_clef/apis.md
@@ -280,7 +280,7 @@ Response
 ### account_signTypedData
 
 #### Sign data
-   Signs a chunk of structured data conformant to [EIP712]([EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md)) and returns the calculated signature.
+   Signs a chunk of structured data conformant to [EIP712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) and returns the calculated signature.
 
 #### Arguments
   - account [address]: account to sign with
diff --git a/docs/_doc/Connecting-to-the-network.md b/docs/_doc/Connecting-to-the-network.md
index c28b61ea3f..fba3ae1535 100644
--- a/docs/_doc/Connecting-to-the-network.md
+++ b/docs/_doc/Connecting-to-the-network.md
@@ -144,7 +144,7 @@ the following into `<datadir>/geth/static-nodes.json`:
 ]
 ```
 
-You can also add static nodes at runtime via the js console using [`admin.addPeer()`](../interface/JavaScript-Console#addpeer):
+You can also add static nodes at runtime via the js console using [`admin.addPeer()`](../interface/javascript-console#addpeer):
 
 ```js
 admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
diff --git a/docs/_doc/Ethereum-Specification.md b/docs/_doc/Ethereum-Specification.md
index 96006f391a..66bb0b3c9b 100644
--- a/docs/_doc/Ethereum-Specification.md
+++ b/docs/_doc/Ethereum-Specification.md
@@ -15,7 +15,7 @@ Specifications of all ethereum technologies, languages, protocols, etc.
 
 - [JavaScript API](https://github.com/ethereum/wiki/wiki/JavaScript-API#a)
 - [Generic JSON RPC](https://github.com/ethereum/wiki/JSON-RPC)
-- [JSRE admin API](../interface/JavaScript-Console#console-api)
+- [JSRE admin API](../interface/javascript-console#console-api)
 - [RLP](https://github.com/ethereum/wiki/wiki/RLP)
 - [ÐΞVp2p Wire Protocol](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol)
 - [Web3 Secret Storage](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition)
diff --git a/docs/_doc/Ethereum-on-Android.md b/docs/_doc/Ethereum-on-Android.md
index d433d340af..4184a1cc5e 100644
--- a/docs/_doc/Ethereum-on-Android.md
+++ b/docs/_doc/Ethereum-on-Android.md
@@ -3,7 +3,7 @@ title: Ethereum on Android
 ---
 Building Geth for Android is a non trivial task, as it requires cross compiling external C dependencies ([GNU Arithmetic Library](https://gmplib.org/)); internal C dependencies ([ethash](https://github.com/ethereum/ethash)); as well as the entire CGO enabled Go code-base to Android. This is further complicated by the Position Independent Executables (PIE) security feature introduced since Android 4.1 Jelly Bean, requiring different compiler and linker options based on the target Android platform version.
 
-To cope with all the build issues, the [`xgo`](https://github.com/karalabe/xgo) CGO enabled Go cross compiler is used, which assembles an entire multi-platform cross compiler suite into a single mega docker container. Details about using `xgo` can be found in the project's [README](https://github.com/karalabe/xgo/blob/master/README.md), with Ethereum specifics on the go-ethereum cross compilation [wiki page](Cross-compiling-Ethereum).
+To cope with all the build issues, the [`xgo`](https://github.com/karalabe/xgo) CGO enabled Go cross compiler is used, which assembles an entire multi-platform cross compiler suite into a single mega docker container. Details about using `xgo` can be found in the project's [README](https://github.com/karalabe/xgo/blob/master/README.md), with Ethereum specifics on the [go-ethereum cross compilation](../developers/cross-compiling-ethereum).
 
 TL;DR
 
diff --git a/docs/_doc/Japanese-Contracts-and-Transactions.md b/docs/_doc/Japanese-Contracts-and-Transactions.md
index f9857b8eb2..9ffa175618 100644
--- a/docs/_doc/Japanese-Contracts-and-Transactions.md
+++ b/docs/_doc/Japanese-Contracts-and-Transactions.md
@@ -13,7 +13,7 @@ Both types of accounts have an ether balance.
 
 Transactions can be fired from from both types of accounts, though contracts only fire transactions in response to other transactions that they have received. Therefore, all action on ethereum block chain is set in motion by transactions fired from externally controlled accounts.
 
-The simplest transactions are ether transfer transactions. But before we go into that you should read up on [accounts](../how-to/Managing-your-accounts) and perhaps on [mining](../how-to/Mining).
+The simplest transactions are ether transfer transactions. But before we go into that you should read up on [accounts](../interface/managing-your-accounts) and perhaps on [mining](../legacy/mining).
 
 ## Ether transfer
 
diff --git a/docs/_doc/Setting-up-monitoring-on-local-cluster.md b/docs/_doc/Setting-up-monitoring-on-local-cluster.md
index 435803b85b..4f2541efa5 100644
--- a/docs/_doc/Setting-up-monitoring-on-local-cluster.md
+++ b/docs/_doc/Setting-up-monitoring-on-local-cluster.md
@@ -1,7 +1,7 @@
 ---
 title: Setting up monitoring on local cluster
 ---
-This page describes how to set up a monitoring site, [like this one](http://eth-netstats.herokuapp.com/), for your private network. It builds upon [this wiki article](Setting-up-private-network-or-local-cluster) and assumes you've created a local cluster using [this script (gethcluster.sh)](https://github.com/ethersphere/eth-utils).
+This page describes how to set up a monitoring site, [like this one](http://eth-netstats.herokuapp.com/), for your private network. It builds upon [this page](setting-up-private-network-or-local-cluster) and assumes you've created a local cluster using [this script (gethcluster.sh)](https://github.com/ethersphere/eth-utils).
 
 The monitoring system consists of two components:
 
diff --git a/docs/_doc/Setting-up-private-network-or-local-cluster.md b/docs/_doc/Setting-up-private-network-or-local-cluster.md
index a1897d5bcb..2488c4f509 100644
--- a/docs/_doc/Setting-up-private-network-or-local-cluster.md
+++ b/docs/_doc/Setting-up-private-network-or-local-cluster.md
@@ -4,7 +4,7 @@ title: Setting up private network or local cluster
 This page describes how to set up a local cluster of nodes, advise how to make it private, and how to hook up your nodes on the eth-netstat network monitoring app. 
 A fully controlled ethereum network is useful as a backend for network integration testing (core developers working on issues related to networking/blockchain synching/message propagation, etc or DAPP developers testing multi-block and multi-user scenarios).
 
-We assume you are able to build `geth` following the [build instructions](../install-and-build/Building-Ethereum)
+We assume you are able to build `geth` following the [build instructions](../install-and-build/build-from-source)
 
 ## Setting up multiple nodes
 
@@ -115,5 +115,5 @@ I0216 10:01:40.094089 p2p/discover/udp.go:227] Listening, enode://890b6b5367ef60
 
 [This page](https://github.com/ethereum/wiki/wiki/Network-Status) describes how to use the [The Ethereum (centralised) network status monitor (known sometimes as "eth-netstats")](http://stats.ethdev.com) to monitor your nodes.
 
-[This page](Setting-up-monitoring-on-local-cluster) or [this README](https://github.com/ethersphere/eth-utils) 
+[This page](../doc/setting-up-monitoring-on-local-cluster) or [this README](https://github.com/ethersphere/eth-utils) 
 describes how you set up your own monitoring service for a (private or public) local cluster.
\ No newline at end of file
diff --git a/docs/_install-and-build/Backup--restore.md b/docs/_install-and-build/Backup--restore.md
index 293877e247..ce896ccd1f 100644
--- a/docs/_install-and-build/Backup--restore.md
+++ b/docs/_install-and-build/Backup--restore.md
@@ -23,9 +23,9 @@ The default data directory locations are platform specific:
 
 Accounts are stored in the `keystore` subdirectory. The contents of this directories should be transportable between nodes, platforms, implementations (C++, Go, Python).
 
-To configure the location of the data directory, the `--datadir` parameter can be specified. See [CLI Options](../interface/Command-Line-Options) for more details.
+To configure the location of the data directory, the `--datadir` parameter can be specified. See [CLI Options](../interface/command-line-options) for more details.
 
-_**Note:** The [Ethash DAG](../how-to/Mining#ethash-dag) is stored at `~/.ethash` (Mac/Linux) or `%APPDATA%\Ethash` (Windows) so that it can be reused by all clients. You can store this in a different location by using a symbolic link._
+_**note:** the [ethash dag](../legacy/mining#ethash-dag) is stored at `~/.ethash` (Mac/Linux) or `%APPDATA%\Ethash` (Windows) so that it can be reused by all clients. You can store this in a different location by using a symbolic link._
 
 ## Upgrades
 
diff --git a/docs/_install-and-build/Build-from-Source.md b/docs/_install-and-build/Build-from-Source.md
index 7075b2e1d2..60b88c6dcf 100644
--- a/docs/_install-and-build/Build-from-Source.md
+++ b/docs/_install-and-build/Build-from-Source.md
@@ -1,7 +1,8 @@
+---
+title: Build from source
+---
 <!-- TODO: Maybe move? -->
 
-## Build from source
-
 Go Ethereum (as its name implies) is written in [Go](https://golang.org), and as such to build from source code you need to have at least Go 1.7 installed (preferably the latest version, currently at 1.9.2). This guide does not go into details on how to install Go itself, for that please read the [Go installation instructions](https://golang.org/doc/install).
 
 Assuming you have Go installed, you can download our project via:
diff --git a/docs/_install-and-build/Developers-Guide.md b/docs/_install-and-build/Developers-Guide.md
index 52a25cc6d4..1136ff7aaf 100644
--- a/docs/_install-and-build/Developers-Guide.md
+++ b/docs/_install-and-build/Developers-Guide.md
@@ -2,7 +2,7 @@
 title: Developers' guide
 ---
 **NOTE: These instructions are for people who want to contribute Go source code changes.
-If you just want to run ethereum, use the normal [Installation Instructions](Installing-Geth)**
+If you just want to run ethereum, use the normal [Installation Instructions](installing-geth)**
 
 This document is the entry point for developers of the Go implementation of Ethereum. Developers here refer to the hands-on: who are interested in build, develop, debug, submit a bug report or pull request or contribute code to go-ethereum.
 
@@ -49,7 +49,7 @@ go-ethereum exectuables can be built individually. To build just geth, use:
 go install -v ./cmd/geth
 ```
 
-Read about cross compilation of go-ethereum [here](../doc/Cross-compiling-Ethereum).
+read about cross compilation of go-ethereum [here](../developers/cross-compiling-ethereum).
 
 ### Git flow
 
@@ -84,7 +84,7 @@ for more see [go test flags](http://golang.org/cmd/go/#hdr-Description_of_testin
 ### Metrics and monitoring
 
 `geth` can do node behaviour monitoring, aggregation and show performance metric charts. 
-Read about [metrics and monitoring](../doc/Metrics-and-Monitoring)
+read about [metrics and monitoring](../doc/metrics-and-monitoring)
 
 ### Getting Stack Traces
 
@@ -126,7 +126,7 @@ PRs need to be based on and opened against the `master` branch (unless by explic
 agreement, you contribute to a complex feature branch).
 
 Your PR will be reviewed according to the [Code Review
-Guidelines](../doc/Code-Review-Guidelines).
+guidelines](../developers/code-review-guidelines).
 
 We encourage a PR early approach, meaning you create the PR the earliest even without the
 fix/feature. This will let core devs and other volunteers know you picked up an issue.
@@ -134,8 +134,8 @@ These early PRs should indicate 'in progress' status.
 
 ## Dev Tutorials (mostly outdated)
 
-* [Private networks, local clusters and monitoring](../doc/Setting-up-private-network-or-local-cluster)
+* [private networks, local clusters and monitoring](../doc/setting-up-private-network-or-local-cluster)
 
-* [P2P 101](../doc/Peer-to-Peer): a tutorial about setting up and creating a p2p server and p2p sub protocol.
+* [p2p 101](../developers/peer-to-peer): a tutorial about setting up and creating a p2p server and p2p sub protocol.
 
-* [How to Whisper](../doc/How-to-Whisper): an introduction to whisper.
+* [how to whisper](../whisper/whisper-overview): an introduction to whisper.
diff --git a/docs/_interface/JavaScript-Console.md b/docs/_interface/JavaScript-Console.md
index 0387b68581..f70e51d488 100644
--- a/docs/_interface/JavaScript-Console.md
+++ b/docs/_interface/JavaScript-Console.md
@@ -3,7 +3,7 @@ title: JavaScript console
 ---
 Ethereum implements a **javascript runtime environment** (JSRE) that can be used in either interactive (console) or non-interactive (script) mode.
  
-Ethereum's Javascript console exposes the full [web3 JavaScript Dapp API](https://github.com/ethereum/wiki/wiki/JavaScript-API) and the [admin API](JavaScript-Console#javascript-console-api).
+Ethereum's Javascript console exposes the full [web3 JavaScript Dapp API](https://github.com/ethereum/wiki/wiki/JavaScript-API) and the [admin API](#javascript-console-api).
 
 ## Interactive use: the JSRE REPL  Console
 
@@ -18,7 +18,7 @@ The attach node accepts an endpoint in case the geth node is running with a non
     $ geth attach http://191.168.1.1:8545
     $ geth attach ws://191.168.1.1:8546
 
-Note that by default the geth node doesn't start the http and weboscket service and not all functionality is provided over these interfaces due to security reasons. These defaults can be overridden when the `--rpcapi` and `--wsapi` arguments when the geth node is started, or with [admin.startRPC](Management-APIs#admin_startrpc) and [admin.startWS](Management-APIs#admin_startws).
+Note that by default the geth node doesn't start the http and weboscket service and not all functionality is provided over these interfaces due to security reasons. These defaults can be overridden when the `--rpcapi` and `--wsapi` arguments when the geth node is started, or with [admin.startRPC](management-apis#admin_startrpc) and [admin.startWS](management-apis#admin_startws).
 
 If you need log information, start with:
 
@@ -74,4 +74,4 @@ In addition to the full functionality of JS (as per ECMA5), the ethereum JSRE is
 
 Beside the official [DApp API](https://github.com/ethereum/wiki/JSON-RPC) interface the go ethereum node has support for additional management API's. These API's are offered using [JSON-RPC](http://www.jsonrpc.org/specification) and follow the same conventions as used in the DApp API. The go ethereum package comes with a console client which has support for all additional API's.
 
-[The management API has its own wiki page](Management-APIs).
+[The management API has its own page](management-apis).
diff --git a/docs/_interface/Management-APIs.md b/docs/_interface/Management-APIs.md
index 81caa2b838..5ca5836fd2 100644
--- a/docs/_interface/Management-APIs.md
+++ b/docs/_interface/Management-APIs.md
@@ -58,7 +58,7 @@ These additional APIs follow the same conventions as the official DApp APIs. Web
 [extended](https://github.com/ethereum/web3.js/pull/229) and used to consume these additional APIs. 
 
 The different functions are split into multiple smaller logically grouped APIs. Examples are given
-for the [JavaScript console](JavaScript-Console) but
+for the [JavaScript console](javascript-console) but
 can easily be converted to an RPC request.
 
 **2 examples:**
diff --git a/docs/_interface/Managing-your-accounts.md b/docs/_interface/Managing-your-accounts.md
index bda5590836..ea420d3767 100644
--- a/docs/_interface/Managing-your-accounts.md
+++ b/docs/_interface/Managing-your-accounts.md
@@ -27,7 +27,7 @@ or import). Without it you are not able to unlock your account.
 Note that exporting your key in unencrypted format is NOT supported.
 
 Keys are stored under `<DATADIR>/keystore`. Make sure you backup your keys regularly! See
-[DATADIR backup & restore](../doc/Backup--restore)
+[DATADIR backup & restore](../install-and-build/backup-restore)
 for more information. If a custom datadir and keystore option are given the keystore
 option takes preference over the datadir option.
 
@@ -62,7 +62,7 @@ OPTIONS:
   --keystore                       Directory for the keystore (default = inside the datadir)
 ```
 
-Accounts can also be managed via the [Javascript Console](../interface/JavaScript-Console)
+Accounts can also be managed via the [Javascript Console](../interface/javascript-console)
 
 ## Examples
 ### Interactive use
@@ -335,7 +335,7 @@ That can then be executed with:
 
 Since this function will disappear after restarting geth, it can be helpful to store
 commonly used functions to be recalled later. The
-[loadScript](../interface/JavaScript-Console#loadscript)
+[loadScript](../interface/javascript-console#loadscript)
 function makes this very easy.
 
 First, save the `checkAllBalances()` function definition to a file on your computer. For
diff --git a/docs/_legacy/Contract-Tutorial.md b/docs/_legacy/Contract-Tutorial.md
index b8876170ec..c1128a1537 100644
--- a/docs/_legacy/Contract-Tutorial.md
+++ b/docs/_legacy/Contract-Tutorial.md
@@ -112,7 +112,7 @@ If you have the SolC Solidity Compiler installed,  you need now reformat by remo
 
 #### Linking your compiler in Geth
 
-Now [go back to the console](../doc/geth) and type this command to install solC, replacing _path/to/solc_ to the path that you got on the last command you did:
+Now [go back to the console](../interface/javascript-console) and type this command to install solC, replacing _path/to/solc_ to the path that you got on the last command you did:
 
     admin.setSolc("path/to/solc")
 
diff --git a/docs/_legacy/Mining.md b/docs/_legacy/Mining.md
index 8761fc23bf..5c711ed842 100644
--- a/docs/_legacy/Mining.md
+++ b/docs/_legacy/Mining.md
@@ -15,11 +15,11 @@ The C++ implementation of Ethereum also offers a GPU miner, both as part of Eth
 
 _**NOTE:** Ensure your blockchain is fully synchronised with the main chain before starting to mine, otherwise you will not be mining on the main chain._
 
-When you start up your ethereum node with `geth` it is not mining by default. To start it in mining mode, you use the `--mine` [command line option](../interface/Command-Line-Options). The `-minerthreads` parameter can be used to set the number parallel mining threads (defaulting to the total number of processor cores). 
+When you start up your ethereum node with `geth` it is not mining by default. To start it in mining mode, you use the `--mine` [command line option](../interface/command-line-options). The `-minerthreads` parameter can be used to set the number parallel mining threads (defaulting to the total number of processor cores). 
 
 `geth --mine --minerthreads=4`
 
-You can also start and stop CPU mining at runtime using the [console](../interface/JavaScript-Console#adminminerstart). `miner.start` takes an optional parameter for the number of miner threads. 
+You can also start and stop CPU mining at runtime using the [console](../interface/javascript-console#adminminerstart). `miner.start` takes an optional parameter for the number of miner threads. 
 
 ```
 > miner.start(8)
@@ -30,7 +30,7 @@ true
 
 Note that mining for real ether only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the eth blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel your intention with `miner.stop()`.
 
-In order to earn ether you must have your **etherbase** (or **coinbase**) address set. This etherbase defaults to your [primary account](Managing-your-accounts). If you don't have an etherbase address, then `geth --mine` will not start up.
+In order to earn ether you must have your **etherbase** (or **coinbase**) address set. This etherbase defaults to your [primary account](../interface/managing-your-accounts). If you don't have an etherbase address, then `geth --mine` will not start up.
 
 You can set your etherbase on the command line:
 
@@ -46,7 +46,7 @@ miner.setEtherbase(eth.accounts[2])
 
 Note that your etherbase does not need to be an address of a local account, just an existing one. 
 
-There is an option [to add extra Data](../interface/JavaScript-Console#adminminersetextra) (32 bytes only) to your mined blocks. By convention this is interpreted as a unicode string, so you can set your short vanity tag.
+There is an option [to add extra Data](../interface/javascript-console#adminminersetextra) (32 bytes only) to your mined blocks. By convention this is interpreted as a unicode string, so you can set your short vanity tag.
 
 ```
 miner.setExtra("ΞTHΞЯSPHΞЯΞ")
@@ -66,7 +66,7 @@ Header:
 
 See also [this proposal](https://github.com/ethereum/wiki/wiki/Extra-Data)
 
-You can check your hashrate with [miner.hashrate](../interface/JavaScript-Console#adminminerhashrate), the result is in H/s (Hash operations per second). 
+You can check your hashrate with [miner.hashrate](../interface/javascript-console#adminminerhashrate), the result is in H/s (Hash operations per second). 
 
 ```
 > miner.hashrate
@@ -235,7 +235,7 @@ ethminer -G  // -G for GPU, -M for benchmark
 tail -f geth.log
 ```
 
-`ethminer` communicates with geth on port 8545 (the default RPC port in geth). You can change this by giving the [`--rpcport` option](https://github.com/ethereum/go-ethereum/Command-Line-Options) to `geth`.
+`ethminer` communicates with geth on port 8545 (the default RPC port in geth). You can change this by giving the [`--rpcport` option](../interface/command-line-options) to `geth`.
 Ethminer will find get on any port. Note that you need to set the CORS header with `--rpccorsdomain localhost`. You can also set port on `ethminer` with `-F http://127.0.0.1:3301`. Setting the ports is necessary if you want several instances mining on the same computer,  although this is somewhat pointless. If you are testing on a private cluster, we recommend you use CPU mining instead. 
 
 Also note that you do **not** need to give `geth` the `--mine` option or start the miner in the console unless you want to do CPU mining on TOP of GPU mining. 
diff --git a/docs/_legacy/Swarm---TODO.md b/docs/_legacy/Swarm---TODO.md
index d979d20437..9ce1d0301b 100644
--- a/docs/_legacy/Swarm---TODO.md
+++ b/docs/_legacy/Swarm---TODO.md
@@ -31,7 +31,7 @@ title: Swarm TODO
 
 ## APIs
 - DAPP API - js integration (Fabian, Alex)
-- mist dapp storage scheme, url->hash mapping (Fabian, Alex) [URL scheme](URL-Scheme)
+- mist dapp storage scheme, url->hash mapping (Fabian, Alex) [URL scheme](../doc/url-scheme)
 
 # Discuss alternatives 
 
diff --git a/docs/_legacy/Swarm---distributed-preimage-archive.md b/docs/_legacy/Swarm---distributed-preimage-archive.md
index 6c648c459e..4bd685f63f 100644
--- a/docs/_legacy/Swarm---distributed-preimage-archive.md
+++ b/docs/_legacy/Swarm---distributed-preimage-archive.md
@@ -10,15 +10,15 @@ title: Swarm - distributed preimage archive
 - http://www.amazon.co.uk/Swarmwise-Tactical-Manual-Changing-World/dp/1463533152/
 
 ## Docs & specs
-- [Swarm TODO](Swarm---TODO)
+- [Swarm TODO](./swarm-todo)
 - Dani & Viktor on public wiki: https://github.com/ethereum/wiki/wiki/Distributed-Preimage-Archive
 - Dani on swarm hash: https://github.com/ethereum/wiki/wiki/Swarm-Hash
 - Dani on incentive system: https://github.com/ethersphere/swarm/blob/master/doc/incentives.md 
-- [The swarm smart contract](Swarm-Contract)
+- [The swarm smart contract](./swarm-contract)
 - gav on url-hint https://github.com/ethereum/wiki/wiki/URL-Hint-Protocol
 - Gav on public wiki: https://github.com/ethereum/cpp-ethereum/wiki/Swarm
 - network (DEVp2p)
-  - [Peer-to-Peer](Peer-to-Peer)
+  - [Peer-to-Peer](../developers/peer-to-peer)
   - on kademlia: https://github.com/ethereum/wiki/wiki/Cademlia-Peer-Selection
 
 ## Talks
diff --git a/docs/_legacy/geth.md b/docs/_legacy/geth.md
index 77c89fb29a..a29961c795 100644
--- a/docs/_legacy/geth.md
+++ b/docs/_legacy/geth.md
@@ -18,20 +18,20 @@ By installing and running `geth`, you can take part in the ethereum frontier liv
 Supported Platforms are Linux, Mac Os and Windows.
 
 We support two types of installation: binary or scripted install for users. 
-See [Install instructions](../install-and-build/Building-Ethereum) for binary and scripted installs.
+See [Install instructions](../install-and-build/build-from-source) for binary and scripted installs.
 
-Developers and community enthusiast are advised to read the [Developers' Guide](../install-and-build/Developers-Guide), which contains detailed instructions for manual build from source (on any platform) as well as detailed tips on testing, monitoring, contributing, debugging and submitting pull requests on github.
+Developers and community enthusiast are advised to read the [Developers' Guide](../install-and-build/developers-guide), which contains detailed instructions for manual build from source (on any platform) as well as detailed tips on testing, monitoring, contributing, debugging and submitting pull requests on github.
 
 ## Interfaces
 
-* Javascript Console: `geth` can be launched with an interactive console, that provides a javascript runtime environment exposing a javascript API to interact with your node. [Javascript Console API](../interface/JavaScript-Console) includes the `web3` javascript Ðapp API as well as an additional admin API. 
+* Javascript Console: `geth` can be launched with an interactive console, that provides a javascript runtime environment exposing a javascript API to interact with your node. [Javascript Console API](../interface/javascript-console) includes the `web3` javascript Ðapp API as well as an additional admin API. 
 * JSON-RPC server: `geth` can be launched with a json-rpc server that exposes the [JSON-RPC API](https://github.com/ethereum/wiki/JSON-RPC)
-* [Command line options](../interface/Command-Line-Options) documents command line parameters as well as subcommands.
+* [Command line options](../interface/command-line-options) documents command line parameters as well as subcommands.
 
 ## Basic Use Case Documentation
 
-* [Managing accounts](../how-to/Managing-your-accounts)
-* [Mining](../how-to/Mining)
+* [Managing accounts](../interface/managing-your-accounts)
+* [Mining](../legacy/mining)
 
 **Note** buying and selling ether through exchanges is not discussed here. 
 
diff --git a/docs/_support/FAQ.md b/docs/_support/FAQ.md
index 9879bc79b4..c47dd6138c 100644
--- a/docs/_support/FAQ.md
+++ b/docs/_support/FAQ.md
@@ -10,7 +10,7 @@ title: FAQ
 
 **Q.**  I would like to run multiple geth instances but got the error "Fatal: blockchain db err: resource temporarily unavailable".
 
-**A.**  Geth uses a datadir to store the blockchain, accounts and some additional information. This directory cannot be shared between running instances. If you would like to run multiple instances follow [these](../doc/Setting-up-private-network-or-local-cluster) instructions.
+**A.**  Geth uses a datadir to store the blockchain, accounts and some additional information. This directory cannot be shared between running instances. If you would like to run multiple instances follow [these](../doc/setting-up-private-network-or-local-cluster) instructions.
 
 ---
 
diff --git a/docs/_whisper/How-to-Whisper.md b/docs/_whisper/How-to-Whisper.md
index fd057c6b0f..18fdd56e93 100644
--- a/docs/_whisper/How-to-Whisper.md
+++ b/docs/_whisper/How-to-Whisper.md
@@ -3,7 +3,7 @@ title: How to Whisper
 ---
 Whisper is a pure identity-based messaging system. Whisper provides a low-level (non-application-specific) but easily-accessible API without being based upon or prejudiced by the low-level hardware attributes and characteristics, particularly the notion of singular endpoints.
 
-This tutorial assumes you've read [p2p 101](Peer-to-Peer). If you haven't read it I suggest you read it. This tutorial will guide you to setting up a full p2p server with whisper capabilities.
+This tutorial assumes you've read [p2p 101](../developers/peer-to-peer). If you haven't read it I suggest you read it. This tutorial will guide you to setting up a full p2p server with whisper capabilities.
 
 Let's quickly cover some of whisper's basic functionality and discuss it in greater detail later.
 
diff --git a/docs/index.md b/docs/index.md
index e150feafa1..a3ee78bba8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,13 +9,13 @@ This is the documentation for the official Ethereum golang implementation. For g
 
 Main entry points:
 
-* [Installation Instructions](../install-and-build/Building-Ethereum)
-* [Management APIs](../interface/Management-APIs)
-* [Managing Accounts](../interface/Managing-your-accounts)
-* [Command Line Options](../interface/Command-Line-Options)
-* [JavaScript Console](../interface/JavaScript-Console)
-* [Private Network](../doc/Private-network)
-* [Developers' Guide](../install-and-build/Developers-Guide)
-* [Whisper v6](../doc/Whisper)
+* [Installation Instructions](./install-and-build/installing-geth)
+* [Management APIs](./interface/management-apis)
+* [Managing Accounts](./interface/managing-your-accounts)
+* [Command Line Options](./interface/command-line-options)
+* [JavaScript Console](./interface/javascript-console)
+* [Private Network](./doc/private-network)
+* [Developers' Guide](./install-and-build/developers-guide)
+* [Whisper v6](./whisper/whisper-overview)
 
 Sidebar lists all pages.
diff --git a/install.md b/install.md
index 9ed5a8885a..f67fd4cd43 100644
--- a/install.md
+++ b/install.md
@@ -3,4 +3,4 @@ title: Install
 root: ..
 permalink: /install/
 ---
-See [Installing Geth](../doc/Installing-Geth).
\ No newline at end of file
+See [Installing Geth](../docs/install-and-build/installing-geth).
\ No newline at end of file