docs: Relink and fix broken links

Documentation/admin_guide.md

@@ -18,8 +18,6 @@ Using an out-of-date data directory can lead to inconsistency as the member had
 For maximum safety, if an etcd member suffers any sort of data corruption or loss, it must be removed from the cluster.
 Once removed the member can be re-added with an empty data directory.
 
-[remove-a-member]: runtime-configuration.md#remove-a-member
-
 ### Contents
 
 The data directory has two sub-directories in it:
@@ -29,9 +27,6 @@ The data directory has two sub-directories in it:
 
 If `--wal-dir` flag is set, etcd will write the write ahead log files to the specified directory instead of data directory.
 
-[wal-pkg]: http://godoc.org/github.com/coreos/etcd/wal
-[snap-pkg]: http://godoc.org/github.com/coreos/etcd/snap
-
 ## Cluster Management
 
 ### Lifecycle
@@ -65,7 +60,7 @@ cluster is healthy
 
 #### Runtime Metrics
 
-etcd uses [Prometheus](http://prometheus.io/) for metrics reporting in the server. You can read more through the runtime metrics [doc](metrics.md).
+etcd uses [Prometheus][prometheus] for metrics reporting in the server. You can read more through the runtime metrics [doc][metrics].
 
 ### Debugging
 
@@ -94,7 +89,7 @@ Debug variables are exposed for real-time debugging purposes. Developers who are
 
 `file_descriptor_limit` is the max number of file descriptors etcd can utilize.
 
-`memstats` is well explained [here](http://golang.org/pkg/runtime/#MemStats).
+`memstats` is explained in detail in the [Go runtime documentation][golang-memstats].
 
 `raft.status` is useful when you want to debug low level raft issues if you are familiar with raft internals. In most cases, you do not need to check `raft.status`.
 
@@ -130,7 +125,7 @@ As you can see, adding another member to bring the size of cluster up to an odd
 
 #### Changing Cluster Size
 
-After your cluster is up and running, adding or removing members is done via [runtime reconfiguration](runtime-configuration.md#cluster-reconfiguration-operations), which allows the cluster to be modified without downtime. The `etcdctl` tool has a `member list`, `member add` and `member remove` commands to complete this process.
+After your cluster is up and running, adding or removing members is done via [runtime reconfiguration][runtime-reconfig], which allows the cluster to be modified without downtime. The `etcdctl` tool has `member list`, `member add` and `member remove` commands to complete this process.
 
 ### Member Migration
 
@@ -138,10 +133,10 @@ When there is a scheduled machine maintenance or retirement, you might want to m
 
 The data directory contains all the data to recover a member to its point-in-time state. To migrate a member:
 
-* Stop the member process
-* Copy the data directory of the now-idle member to the new machine
-* Update the peer URLs for that member to reflect the new machine according to the [runtime configuration] [change peer url]
-* Start etcd on the new machine, using the same configuration and the copy of the data directory
+* Stop the member process.
+* Copy the data directory of the now-idle member to the new machine.
+* Update the peer URLs for the replaced member to reflect the new machine according to the [runtime reconfiguration instructions][update-member].
+* Start etcd on the new machine, using the same configuration and the copy of the data directory.
 
 This example will walk you through the process of migrating the infra1 member to a new machine:
 
@@ -212,8 +207,6 @@ etcd -name infra1 \
 -advertise-client-urls http://10.0.1.13:2379,http://127.0.0.1:2379
 ```
 
-[change peer url]: runtime-configuration.md#update-a-member
-
 ### Disaster Recovery
 
 etcd is designed to be resilient to machine failures. An etcd cluster can automatically recover from any number of temporary failures (for example, machine reboots), and a cluster of N members can tolerate up to _(N-1)/2_ permanent failures (where a member can no longer access the cluster, due to hardware failure or disk corruption). However, in extreme circumstances, a cluster might permanently lose enough members such that quorum is irrevocably lost. For example, if a three-node cluster suffered two simultaneous and unrecoverable machine failures, it would be normally impossible for the cluster to restore quorum and continue functioning.
@@ -260,9 +253,9 @@ Once you have verified that etcd has started successfully, shut it down and move
 
 #### Restoring the cluster
 
-Now that if the node is running successfully, you should [change its advertised peer URLs](runtime-configuration.md#update-a-member), as the `--force-new-cluster` has set the peer URL to the default (listening on localhost).
+Now that the node is running successfully, [change its advertised peer URLs][update-member], as the `--force-new-cluster` option has set the peer URL to the default listening on localhost.
 
-You can then add more nodes to the cluster and restore resiliency. See the [add a new member](runtime-configuration.md#add-a-new-member) guide for more details. **NB:** If you are trying to restore your cluster using old failed etcd nodes, please make sure you have stopped old etcd instances and removed their old data directories specified by the data-dir configuration parameter.
+You can then add more nodes to the cluster and restore resiliency. See the [add a new member][add-a-member] guide for more details. **NB:** If you are trying to restore your cluster using old failed etcd nodes, please make sure you have stopped old etcd instances and removed their old data directories specified by the data-dir configuration parameter.
 
 ### Client Request Timeout
 
@@ -293,6 +286,18 @@ If timeout happens several times continuously, administrators should check statu
 
 #### Maximum OS threads
 
-By default, etcd uses the default configuration of the Go 1.4 runtime, which means that at most one operating system thread will be used to execute code simultaneously. (Note that this default behavior [has changed in Go 1.5](https://golang.org/doc/go1.5#runtime)).
+By default, etcd uses the default configuration of the Go 1.4 runtime, which means that at most one operating system thread will be used to execute code simultaneously. (Note that this default behavior [has changed in Go 1.5][golang1.5-runtime]).
+
+When using etcd in heavy-load scenarios on machines with multiple cores it will usually be desirable to increase the number of threads that etcd can utilize. To do this, simply set the environment variable GOMAXPROCS to the desired number when starting etcd. For more information on this variable, see the [Go runtime documentation][golang-runtime].
 
-When using etcd in heavy-load scenarios on machines with multiple cores it will usually be desirable to increase the number of threads that etcd can utilize. To do this, simply set the environment variable `GOMAXPROCS` to the desired number when starting etcd. For more information on this variable, see the Go [runtime](https://golang.org/pkg/runtime) documentation.
+[add-a-member]: runtime-configuration.md#add-a-new-member
+[golang1.5-runtime]: https://golang.org/doc/go1.5#runtime
+[golang-memstats]: https://golang.org/pkg/runtime/#MemStats
+[golang-runtime]: https://golang.org/pkg/runtime
+[metrics]: metrics.md
+[prometheus]: http://prometheus.io/
+[remove-a-member]: runtime-configuration.md#remove-a-member
+[runtime-reconfig]: runtime-configuration.md#cluster-reconfiguration-operations
+[snap-pkg]: http://godoc.org/github.com/coreos/etcd/snap
+[update-a-member]: runtime-configuration.md#update-a-member
+[wal-pkg]: http://godoc.org/github.com/coreos/etcd/wal

Documentation/api.md

@@ -78,12 +78,9 @@ X-Raft-Index: 5398
 X-Raft-Term: 1
 ```
 
-- `X-Etcd-Index` is the current etcd index as explained above. When request is a watch on key space, `X-Etcd-Index` is the current etcd index when the watch starts, which means that the watched event may happen after `X-Etcd-Index`.
-- `X-Raft-Index` is similar to the etcd index but is for the underlying raft protocol
-- `X-Raft-Term` is an integer that will increase whenever an etcd master election happens in the cluster. If this number is increasing rapidly, you may need to tune the election timeout. See the [tuning][tuning] section for details.
-
-[tuning]: tuning.md
-
+* `X-Etcd-Index` is the current etcd index as explained above. When request is a watch on key space, `X-Etcd-Index` is the current etcd index when the watch starts, which means that the watched event may happen after `X-Etcd-Index`.
+* `X-Raft-Index` is similar to the etcd index but is for the underlying raft protocol.
+* `X-Raft-Term` is an integer that will increase whenever an etcd master election happens in the cluster. If this number is increasing rapidly, you may need to tune the election timeout. See the [tuning][tuning] section for details.
 
 ### Get the value of a key
 
@@ -544,7 +541,7 @@ etcd can be used as a centralized coordination service in a cluster, and `Compar
 
 This command will set the value of a key only if the client-provided conditions are equal to the current conditions.
 
-_Note that `CompareAndSwap` does not work with [directories](#listing-a-directory). If an attempt is made to `CompareAndSwap` a directory, a 102 "Not a file" error will be returned._
+*Note that `CompareAndSwap` does not work with [directories][directories]. If an attempt is made to `CompareAndSwap` a directory, a 102 "Not a file" error will be returned.*
 
 The current comparable conditions are:
 
@@ -631,7 +628,7 @@ We successfully changed the value from "one" to "two" since we gave the correct
 
 This command will delete a key only if the client-provided conditions are equal to the current conditions.
 
-_Note that `CompareAndDelete` does not work with [directories](#listing-a-directory). If an attempt is made to `CompareAndDelete` a directory, a 102 "Not a file" error will be returned._
+*Note that `CompareAndDelete` does not work with [directories]. If an attempt is made to `CompareAndDelete` a directory, a 102 "Not a file" error will be returned.*
 
 The current comparable conditions are:
 
@@ -1128,4 +1125,6 @@ curl http://127.0.0.1:2379/v2/stats/store
 
 See the [members API][members-api] for details on the cluster management.
 
+[directories]: #listing-a-directory
 [members-api]: members_api.md
+[tuning]: tuning.md

Documentation/auth_api.md

@@ -40,7 +40,7 @@ Specific settings for the cluster as a whole. This can include adding and removi
 ## v2 Auth
 
 ### Basic Auth
-We only support [Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication) for the first version. Client needs to attach the basic auth to the HTTP Authorization Header. 
+We only support [Basic Auth][basic-auth] for the first version. Client needs to attach the basic auth to the HTTP Authorization Header.
 
 ### Authorization field for operations
 Added to requests to /v2/keys, /v2/auth
@@ -508,3 +508,4 @@ PUT /v2/keys/rkt/RktData
 
 Reads and writes outside the prefixes granted will fail with a 401 Unauthorized.
 
+[basic-auth]: https://en.wikipedia.org/wiki/Basic_access_authentication

Documentation/authentication.md

@@ -8,7 +8,7 @@ Authentication -- having users and roles in etcd -- was added in etcd 2.1. This
 
 etcd before 2.1 was a completely open system; anyone with access to the API could change keys. In order to preserve backward compatibility and upgradability, this feature is off by default.
 
-For a full discussion of the RESTful API, see [the authentication API documentation](auth_api.md)
+For a full discussion of the RESTful API, see [the authentication API documentation][auth-api]
 
 ## Special Users and Roles
 
@@ -177,3 +177,5 @@ $ etcdctl -u user get foo
 ```
 
 Otherwise, all `etcdctl` commands remain the same. Users and roles can still be created and modified, but require authentication by a user with the root role.
+
+[auth-api]: auth_api.md

Documentation/benchmarks/README.md

@@ -2,12 +2,17 @@
 
 etcd benchmarks will be published regularly and tracked for each release below:
 
-- [etcd v2.1.0-alpha](./etcd-2-1-0-alpha-benchmarks.md)
-- [etcd v2.2.0-rc](./etcd-2-2-0-rc-benchmarks.md)
-- [etcd v3 demo](./etcd-3-demo-benchmarks.md)
+- [etcd v2.1.0-alpha][2.1]
+- [etcd v2.2.0-rc][2.2]
+- [etcd v3 demo][3.0]
 
 # Memory Usage Benchmarks
 
 It records expected memory usage in different scenarios.
 
-- [etcd v2.2.0-rc](./etcd-2-2-0-rc-memory-benchmarks.md)
+- [etcd v2.2.0-rc][2.2-mem]
+
+[2.1]: etcd-2-1-0-alpha-benchmarks.md
+[2.2]: etcd-2-2-0-rc-benchmarks.md
+[2.2-mem]: etcd-2-2-0-rc-memory-benchmarks.md
+[3.0]: etcd-3-demo-benchmarks.md

Documentation/benchmarks/etcd-2-1-0-alpha-benchmarks.md

@@ -14,7 +14,7 @@ GCE n1-highcpu-2 machine type
 
 ## Testing
 
-Bootstrap another machine and use benchmark tool [boom](https://github.com/rakyll/boom) to send requests to each etcd member.
+Bootstrap another machine and use the [boom HTTP benchmark tool][boom] to send requests to each etcd member. Check the [benchmark hacking guide][hack-benchmark] for detailed instructions.
 
 ## Performance
 
@@ -47,3 +47,6 @@ Bootstrap another machine and use benchmark tool [boom](https://github.com/rakyl
 | 64                | 256               | all servers        | 3260      | 123.8 |
 | 256               | 64                | all servers        | 1033      | 121.5 |
 | 256               | 256               | all servers        | 3061      | 119.3 |
+
+[boom]: https://github.com/rakyll/boom
+[hack-benchmark]: /hack/benchmark/

Documentation/benchmarks/etcd-2-2-0-rc-benchmarks.md

@@ -20,11 +20,11 @@ Go Version: go1.4.2
 Go OS/Arch: linux/amd64
 ```
 
-Also, we use 3 etcd 2.1.0 alpha-stage members to form cluster to get base performance. etcd's commit head is at [c7146bd5](https://github.com/coreos/etcd/commits/c7146bd5f2c73716091262edc638401bb8229144), which is the same as the one that we use in [etcd 2.1 benchmark](./etcd-2-1-0-benchmarks.md).
+Also, we use 3 etcd 2.1.0 alpha-stage members to form cluster to get base performance. etcd's commit head is at [c7146bd5][c7146bd5], which is the same as the one that we use in [etcd 2.1 benchmark][etcd-2.1-benchmark].
 
 ## Testing
 
-Bootstrap another machine and use benchmark tool [boom](https://github.com/rakyll/boom) to send requests to each etcd member. Check [here](../../hack/benchmark/) for instructions.
+Bootstrap another machine and use the [boom HTTP benchmark tool][boom] to send requests to each etcd member. Check the [benchmark hacking guide][hack-benchmark] for detailed instructions.
 
 ## Performance
 
@@ -65,3 +65,8 @@ Bootstrap another machine and use benchmark tool [boom](https://github.com/rakyl
 - write QPS to leader is increased by 20~30%. This is because we decouple raft main loop and entry apply loop, which avoids them blocking each other.
 
 - write QPS to all servers is increased by 30~80% because follower could receive latest commit index earlier and commit proposals faster.
+
+[boom]: https://github.com/rakyll/boom
+[c7146bd5]: https://github.com/coreos/etcd/commits/c7146bd5f2c73716091262edc638401bb8229144
+[etcd-2.1-benchmark]: etcd-2-1-0-alpha-benchmarks.md
+[hack-benchmark]: /hack/benchmark/

Documentation/benchmarks/etcd-3-demo-benchmarks.md

@@ -14,7 +14,7 @@ GCE n1-highcpu-2 machine type
 
 ## Testing
 
-Use [etcd v3 benchmark tool](../../tools/v3benchmark/).
+Use [etcd v3 benchmark tool][etcd-v3-benchmark].
 
 ## Performance
 
@@ -38,3 +38,5 @@ The performance is nearly the same as the one with empty server handler.
 
 The performance with empty server handler is not affected by one put. So the
 performance downgrade should be caused by storage package.
+
+[etcd-v3-benchmark]: /tools/benchmark/

Documentation/benchmarks/etcd-3-watch-memory-benchmark.md

@@ -51,7 +51,7 @@ GCE n1-standard-2 machine type
 
 ## Overall memory usage
 
-The overall memory usage captures how much [RSS](https://en.wikipedia.org/wiki/Resident_set_size) etcd consumes with the client watchers. The result is not very accurate and might vary around 10%. It is still very meaningful, since the goal is to learn about the rough memory usage and the pattern (find out `c1`, `c2` and `c3`).
+The overall memory usage captures how much [RSS][rss] etcd consumes with the client watchers. While the result may vary by as much as 10%, it is still meaningful, since the goal is to learn about the rough memory usage and the pattern of allocations.
 
 With the benchmark result, we can calculate roughly that `c1 = 17kb`, `c2 = 18kb` and `c3 = 350bytes`. So each additional client connection consumes 17kb of memory and each additional stream consumes 18kb of memory, and each additional watching only cause 350bytes. A single etcd server can maintain millions of watchings with a few GB of memory in normal case.
 
@@ -74,3 +74,4 @@ With the benchmark result, we can calculate roughly that `c1 = 17kb`, `c2 = 18kb
 | 2k | 50 | 100 |  10M | 4672MB |
 | 5k | 50 | 100 |  50M |  *OOM* |
 
+[rss]: https://en.wikipedia.org/wiki/Resident_set_size

Documentation/branch_management.md

@@ -2,12 +2,12 @@
 
 ## Guide
 
-- New development occurs on the [master branch](https://github.com/coreos/etcd/tree/master)
-- Master branch should always have a green build!
-- Backwards-compatible bug fixes should target the master branch and subsequently be ported to stable branches
-- Once the master branch is ready for release, it will be tagged and become the new stable branch.
+* New development occurs on the [master branch][master].
+* Master branch should always have a green build!
+* Backwards-compatible bug fixes should target the master branch and subsequently be ported to stable branches.
+* Once the master branch is ready for release, it will be tagged and become the new stable branch.
 
-The etcd team has adopted a _rolling release model_ and supports one stable version of etcd.
+The etcd team has adopted a *rolling release model* and supports one stable version of etcd.
 
 ### Master branch
 
@@ -22,3 +22,5 @@ Before the release of the next stable version, feature PRs will be frozen. We wi
 All branches with prefix `release-` are considered _stable_ branches.
 
 After every minor release (http://semver.org/), we will have a new stable branch for that release. We will keep fixing the backwards-compatible bugs for the latest stable release, but not previous releases. The _patch_ release, incorporating any bug fixes, will be once every two weeks, given any patches.
+
+[master]: https://github.com/coreos/etcd/tree/master

Documentation/clustering.md

@@ -4,7 +4,7 @@
 
 Starting an etcd cluster statically requires that each member knows another in the cluster. In a number of cases, you might not know the IPs of your cluster members ahead of time. In these cases, you can bootstrap an etcd cluster with the help of a discovery service.
 
-Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration](runtime-configuration.md). To better understand the design behind runtime reconfiguration, we suggest you read [this](runtime-reconf-design.md).
+Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration][runtime-conf]. To better understand the design behind runtime reconfiguration, we suggest you read [the runtime configuration design document][runtime-reconf-design].
 
 This guide will cover the following mechanisms for bootstrapping an etcd cluster:
 
@@ -38,7 +38,7 @@ Note that the URLs specified in `initial-cluster` are the _advertised peer URLs_
 
 If you are spinning up multiple clusters (or creating and destroying a single cluster) with same configuration for testing purpose, it is highly recommended that you specify a unique `initial-cluster-token` for the different clusters. By doing this, etcd can generate unique cluster IDs and member IDs for the clusters even if they otherwise have the exact same configuration. This can protect you from cross-cluster-interaction, which might corrupt your clusters.
 
-etcd listens on [`listen-client-urls`](configuration.md#-listen-client-urls) to accept client traffic. etcd member advertises the URLs specified in [`advertise-client-urls`](configuration.md#-advertise-client-urls) to other members, proxies, clients. Please make sure the `advertise-client-urls` are reachable from intended clients. A common mistake is setting `advertise-client-urls` to localhost or leave it as default when you want the remote clients to reach etcd.
+etcd listens on [`listen-client-urls`][conf-listen-client] to accept client traffic. etcd member advertises the URLs specified in [`advertise-client-urls`][conf-adv-client] to other members, proxies, clients. Please make sure the `advertise-client-urls` are reachable from intended clients. A common mistake is setting `advertise-client-urls` to localhost or leave it as default when you want the remote clients to reach etcd.
 
 On each machine you would start etcd with these flags:
 
@@ -70,7 +70,7 @@ $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
   --initial-cluster-state new
 ```
 
-The command line parameters starting with `--initial-cluster` will be ignored on subsequent runs of etcd. You are free to remove the environment variables or command line flags after the initial bootstrap process. If you need to make changes to the configuration later (for example, adding or removing members to/from the cluster), see the [runtime configuration](runtime-configuration.md) guide.
+The command line parameters starting with `--initial-cluster` will be ignored on subsequent runs of etcd. You are free to remove the environment variables or command line flags after the initial bootstrap process. If you need to make changes to the configuration later (for example, adding or removing members to/from the cluster), see the [runtime configuration][runtime-conf] guide.
 
 ### Error Cases
 
@@ -124,15 +124,13 @@ There two methods that can be used for discovery:
 
 ### etcd Discovery
 
-To better understand the design about discovery service protocol, we suggest you read [this](discovery_protocol.md).
+To better understand the design about discovery service protocol, we suggest you read [this][discovery-proto].
 
 #### Lifetime of a Discovery URL
 
 A discovery URL identifies a unique etcd cluster. Instead of reusing a discovery URL, you should always create discovery URLs for new clusters.
 
-Moreover, discovery URLs should ONLY be used for the initial bootstrapping of a cluster. To change cluster membership after the cluster is already running, see the [runtime reconfiguration][runtime] guide.
-
-[runtime]: runtime-configuration.md
+Moreover, discovery URLs should ONLY be used for the initial bootstrapping of a cluster. To change cluster membership after the cluster is already running, see the [runtime reconfiguration][runtime-conf] guide.
 
 #### Custom etcd Discovery Service
 
@@ -189,9 +187,6 @@ This will create the cluster with an initial expected size of 3 members. If you
 
 If you bootstrap an etcd cluster using discovery service with more than the expected number of etcd members, the extra etcd processes will [fall back][fall-back] to being [proxies][proxy] by default.
 
-[fall-back]: proxy.md#fallback-to-proxy-mode-with-discovery-service
-[proxy]: proxy.md
-
 ```
 ETCD_DISCOVERY=https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
 ```
@@ -276,7 +271,7 @@ etcdserver: discovery token ignored since a cluster has already been initialized
 
 ### DNS Discovery
 
-DNS [SRV records](http://www.ietf.org/rfc/rfc2052.txt) can be used as a discovery mechanism.
+DNS [SRV records][rfc-srv] can be used as a discovery mechanism.
 The `-discovery-srv` flag can be used to set the DNS domain name where the discovery SRV records can be found.
 The following DNS SRV records are looked up in the listed order:
 
@@ -400,7 +395,7 @@ $ etcd --proxy on --discovery-srv example.com
 
 DNS SRV records can also be used to help clients discover the etcd cluster.
 
-The official [etcd/client](../client) supports [DNS Discovery](https://godoc.org/github.com/coreos/etcd/client#Discoverer).
+The official [etcd/client][client] supports [DNS Discovery][client-discoverer].
 
 `etcdctl` also supports DNS Discovery by specifying the `--discovery-srv` option.
 
@@ -426,3 +421,14 @@ To make understanding this feature easier, we changed the naming of some flags,
 |-bind-addr    |--listen-client-urls  |If specified, bind-addr will be used as the only client bind URL. Error if both flags specified.|
 |-peers      |none      |Deprecated. The --initial-cluster flag provides a similar concept with different semantics. Please read this guide on cluster startup.|
 |-peers-file    |none      |Deprecated. The --initial-cluster flag provides a similar concept with different semantics. Please read this guide on cluster startup.|
+
+[client]: /client
+[client-discoverer]: https://godoc.org/github.com/coreos/etcd/client#Discoverer
+[conf-adv-client]: configuration.md#-advertise-client-urls
+[conf-listen-client]: configuration.md#-listen-client-urls
+[discovery-proto]: discovery_protocol.md
+[fall-back]: proxy.md#fallback-to-proxy-mode-with-discovery-service
+[proxy]: proxy.md
+[rfc-srv]: http://www.ietf.org/rfc/rfc2052.txt
+[runtime-conf]: runtime-configuration.md
+[runtime-reconf-design]: runtime-reconf-design.md

Documentation/configuration.md

@@ -4,7 +4,7 @@ etcd is configurable through command-line flags and environment variables. Optio
 
 The format of environment variable for flag `--my-flag` is `ETCD_MY_FLAG`. It applies to all  flags.
 
-The [official etcd ports](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=etcd) are 2379 for client requests, and 2380 for peer communication. Some legacy code and documentation still references ports 4001 and 7001, but all new etcd use and discussion should adopt the assigned ports.
+The [official etcd ports][iana-ports] are 2379 for client requests, and 2380 for peer communication. Some legacy code and documentation still references ports 4001 and 7001, but all new etcd use and discussion should adopt the assigned ports.
 
 To start etcd automatically using custom settings at startup in Linux, using a [systemd][systemd-intro] unit is highly recommended.
 
@@ -16,7 +16,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + Human-readable name for this member.
 + default: "default"
 + env variable: ETCD_NAME
-+ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (Ex: `default=http://localhost:2380` or `default=http://localhost:2380,default=http://localhost:7001`). This needs to match the key used in the flag if you're using [static bootstrapping](clustering.md#static). When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice.
++ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (Ex: `default=http://localhost:2380` or `default=http://localhost:2380,default=http://localhost:7001`). This needs to match the key used in the flag if you're using [static bootstrapping][build-cluster]. When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice.
 
 ### --data-dir
 + Path to the data directory.
@@ -253,7 +253,7 @@ Follow the instructions when using these flags.
 ## Experimental Flags
 
 ### --experimental-v3demo
-+ Enable experimental [v3 demo API](rfc/v3api.proto).
++ Enable experimental [v3 demo API][rfc-v3].
 + default: false
 + env variable: ETCD_EXPERIMENTAL_V3DEMO
 
@@ -272,6 +272,11 @@ Follow the instructions when using these flags.
 [build-cluster]: clustering.md#static
 [reconfig]: runtime-configuration.md
 [discovery]: clustering.md#discovery
+[iana-ports]: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=etcd
 [proxy]: proxy.md
-[security]: security.md
+[reconfig]: runtime-configuration.md
 [restore]: admin_guide.md#restoring-a-backup
+[rfc-v3]: rfc/v3api.md
+[security]: security.md
+[systemd-intro]: http://freedesktop.org/wiki/Software/systemd/
+[tuning]: tuning.md#time-parameters

Documentation/discovery_protocol.md

@@ -32,7 +32,7 @@ You need to specify the expected cluster size for this discovery token. The size
 curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size -d value=${cluster_size}
 ```
 
-Usually the cluster size is 3, 5 or 7. Check [optimal cluster size](admin_guide.md#optimal-cluster-size) for more details.
+Usually the cluster size is 3, 5 or 7. Check [optimal cluster size][cluster-size] for more details.
 
 ### Bringing up etcd Processes
 
@@ -64,7 +64,7 @@ In etcd implementation, the member may check the cluster status even before regi
 ### Waiting for All Members
 
 
-The wait process is described in details [here](https://github.com/coreos/etcd/blob/master/Documentation/api.md#waiting-for-a-change).
+The wait process is described in detail in the [etcd API documentation][api].
 
 ```
 curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}?wait=true&waitIndex=${current_etcd_index}
@@ -94,7 +94,7 @@ Possible status codes:
 	generated discovery url
 ```
 
-The generation process in the service follows the step from [Creating a New Discovery Token](#creating-a-new-discovery-token) to [Specifying the Expected Cluster Size](#specifying-the-expected-cluster-size).
+The generation process in the service follows the steps from [Creating a New Discovery Token][new-discovery-token] to [Specifying the Expected Cluster Size][expected-cluster-size].
 
 ### Check Discovery Status
 
@@ -107,3 +107,8 @@ You can check the status for this discovery token, including the machines that h
 ### Open-source repository
 
 The repository is located at https://github.com/coreos/discovery.etcd.io. You could use it to build your own public discovery service.
+
+[api]: api.md#waiting-for-a-change
+[cluster-size]: admin_guide.md#optimal-cluster-size
+[expected-cluster-size]: #specifying-the-expected-cluster-size
+[new-discovery-token]: #creating-a-new-discovery-token

Documentation/faq.md

@@ -60,8 +60,7 @@ removed from the etcd cluster member list.
 This makes sense because it's usually an application level / administrative
 action to determine whether a reconfiguration should happen based on health. 
 
-For more information, refer to
-[Documentation/runtime-reconf-design.md](https://github.com/coreos/etcd/blob/master/Documentation/runtime-reconf-design.md).
+For more information, refer to the [runtime reconfiguration design document][runtime-reconf-design].
 
 ## 6) how does --endpoint work with etcdctl? 
 
@@ -80,3 +79,5 @@ the clusters. This is probably not what you want.
 
 Note: --peers flag is now deprecated and --endpoint should be used instead, 
 as it might confuse users to give etcdctl a peerURL.
+
+[runtime-reconf-design]: runtime-reconf-design.md

Documentation/metrics.md

@@ -2,15 +2,14 @@
 
 **NOTE: The metrics feature is considered experimental. We may add/change/remove metrics without warning in future releases.**
 
-etcd uses [Prometheus](http://prometheus.io/) for metrics reporting in the server. The metrics can be used for real-time monitoring and debugging.
+etcd uses [Prometheus][prometheus] for metrics reporting in the server. The metrics can be used for real-time monitoring and debugging.
 etcd only stores these data in memory. If a member restarts, metrics will reset.
 
 The simplest way to see the available metrics is to cURL the metrics endpoint `/metrics` of etcd. The format is described [here](http://prometheus.io/docs/instrumenting/exposition_formats/).
 
+Follow the [Prometheus getting started doc][prometheus-getting-started] to spin up a Prometheus server to collect etcd metrics.
 
-You can also follow the doc [here](http://prometheus.io/docs/introduction/getting_started/) to start a Prometheus server and monitor etcd metrics.
-
-The naming of metrics follows the suggested [best practice of Prometheus](http://prometheus.io/docs/practices/naming/). A metric name has an `etcd` prefix as its namespace and a subsystem prefix (for example `wal` and `etcdserver`).
+The naming of metrics follows the suggested [best practice of Prometheus][prometheus-naming]. A metric name has an `etcd` prefix as its namespace and a subsystem prefix (for example `wal` and `etcdserver`).
 
 etcd now exposes the following metrics:
 
@@ -25,7 +24,7 @@ etcd now exposes the following metrics:
 
 High file descriptors (`file_descriptors_used_total`) usage (near the file descriptors limitation of the process) indicates a potential out of file descriptors issue. That might cause etcd fails to create new WAL files and panics.
 
-[Proposal](glossary.md#proposal) durations (`proposal_durations_seconds`) give you a histogram about the proposal commit latency. Latency can be introduced into this process by network and disk IO.
+[Proposal][glossary-proposal] durations (`proposal_durations_seconds`) provides a histogram about the proposal commit latency. Latency can be introduced into this process by network and disk IO.
 
 Pending proposal (`pending_proposal_total`) gives you an idea about how many proposal are in the queue and waiting for commit. An increasing pending number indicates a high client load or an unstable cluster.
 
@@ -128,4 +127,8 @@ Example Prometheus queries that may be useful from these metrics (across all etc
  * `sum(rate(etcd_proxy_dropped_total{job="etcd"}[1m])) by (proxying_error)`
     
     Number of failed request on the proxy. This should be 0, spikes here indicate connectivity issues to etcd cluster.
- 
+
+[glossary-proposal]: glossary.md#proposal
+[prometheus]: http://prometheus.io/
+[prometheus-getting-started](http://prometheus.io/docs/introduction/getting_started/)
+[prometheus-naming]: http://prometheus.io/docs/practices/naming/

Documentation/production-users.md

@@ -46,4 +46,6 @@ CyCore Systems provides architecture and engineering for computing systems.  Thi
 - *Environment*: AWS, CoreOS, Kubernetes
 - *Backups*: None, all data can be recreated if necessary.
 
-Radius Intelligence uses Kubernetes running CoreOS to containerize and scale internal toolsets. Examples include running [JetBrains TeamCity](https://www.jetbrains.com/teamcity/) and internal AWS security and cost reporting tools. etcd clusters back these clusters as well as provide some basic environment bootstrapping configuration keys.
+Radius Intelligence uses Kubernetes running CoreOS to containerize and scale internal toolsets. Examples include running [JetBrains TeamCity][teamcity] and internal AWS security and cost reporting tools. etcd clusters back these clusters as well as provide some basic environment bootstrapping configuration keys.
+
+[teamcity]: https://www.jetbrains.com/teamcity/

Documentation/proxy.md

@@ -14,7 +14,7 @@ After establishing a list of peer URLs in this manner, the proxy retrieves the l
 
 While etcd proxies therefore do not need to be given the `advertise-client-urls` option, as they retrieve this configuration from the cluster, this implies that `initial-cluster` must be set correctly for every proxy, and the `advertise-client-urls` option must be set correctly for every non-proxy, first-order cluster peer. Otherwise, requests to any etcd proxy would be forwarded improperly. Take special care not to set the `advertise-client-urls` option to URLs that point to the proxy itself, as such a configuration will cause the proxy to enter a loop, forwarding requests to itself until resources are exhausted. To correct either case, stop etcd and restart it with the correct URLs.
 
-[This example Procfile](https://github.com/coreos/etcd/blob/master/Procfile) illustrates the difference in the etcd peer and proxy command lines used to configure and start a cluster with one proxy under the [goreman process management utility](https://github.com/mattn/goreman).
+[This example Procfile][procfile] illustrates the difference in the etcd peer and proxy command lines used to configure and start a cluster with one proxy under the [goreman process management utility][goreman].
 
 To summarize etcd proxy startup and peer discovery:
 
@@ -145,6 +145,9 @@ If you are running etcd under systemd, you should modify the service file with c
 sudo systemd restart etcd
 ```
 
-If you see an error, you can read the [add member troubleshooting doc](runtime-configuration.md#error-cases).
+If an error occurs, check the [add member troubleshooting doc][runtime-configuration].
 
 [discovery-service]: clustering.md#discovery
+[goreman]: https://github.com/mattn/goreman
+[procfile]: /Procfile
+[runtime-configuration]: runtime-configuration.md#error-cases-when-adding-members

Documentation/reporting_bugs.md

@@ -1,6 +1,6 @@
 # Reporting Bugs
 
-If you find bugs or documentation mistakes in etcd project, please let us know by [opening an issue](https://github.com/coreos/etcd/issues/new). We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check there that one does not already exist.
+If you find bugs or documentation mistakes in the etcd project, please let us know by [opening an issue][issue]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.
 
 To make your bug report accurate and easy to understand, please try to create bug reports that are:
 
@@ -14,7 +14,7 @@ To make your bug report accurate and easy to understand, please try to create bu
 
 - Scoped. One bug per report. Do not follow up with another bug inside one report.
 
-You might also want to read [Elika Etemad’s article on filing good bug reports](http://fantasai.inkedblade.net/style/talks/filing-good-bugs/) before creating a bug report.
+You might also want to read [Elika Etemad’s article on filing good bug reports][filing-good-bugs] before creating a bug report.
 
 We might ask you for further information to locate a bug. A duplicated bug report will be closed.
 
@@ -41,3 +41,5 @@ $ sudo journalctl -u etcd2
 
 Due to an upstream systemd bug, journald may miss the last few log lines when its process exit. If journalctl tells you that etcd stops without fatal or panic message, you could try `sudo journalctl -f -t etcd2` to get full log.
 
+[etcd-issue]: https://github.com/coreos/etcd/issues/new
+[filing-good-bugs]: http://fantasai.inkedblade.net/style/talks/filing-good-bugs/

Documentation/rfc/v3api.md

@@ -45,9 +45,9 @@ the size in the future a little bit or make it configurable.
 
 ## Protobuf Defined API
 
-[api protobuf](../../etcdserver/etcdserverpb/rpc.proto)
+[api protobuf][api-protobuf]
 
-[kv protobuf](../../storage/storagepb/kv.proto)
+[kv protobuf][kv-protobuf]
 
 ## Examples
 
@@ -206,3 +206,6 @@ WatchResponse {
     …
     
 ```
+
+[api-protobuf]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto
+[kv-protobuf]: https://github.com/coreos/etcd/blob/master/storage/storagepb/kv.proto

Documentation/runtime-configuration.md

@@ -4,13 +4,11 @@ etcd comes with support for incremental runtime reconfiguration, which allows us
 
 Reconfiguration requests can only be processed when the majority of the cluster members are functioning. It is **highly recommended** to always have a cluster size greater than two in production. It is unsafe to remove a member from a two member cluster. The majority of a two member cluster is also two. If there is a failure during the removal process, the cluster might not able to make progress and need to [restart from majority failure][majority failure].
 
-To better understand the design behind runtime reconfiguration, we suggest you read [this](runtime-reconf-design.md).
-
-[majority failure]: #restart-cluster-from-majority-failure
+To better understand the design behind runtime reconfiguration, we suggest you read [the runtime reconfiguration document][runtime-reconf].
 
 ## Reconfiguration Use Cases
 
-Let us walk through some common reasons for reconfiguring a cluster. Most of these just involve combinations of adding or removing a member, which are explained below under [Cluster Reconfiguration Operations](#cluster-reconfiguration-operations).
+Let's walk through some common reasons for reconfiguring a cluster. Most of these just involve combinations of adding or removing a member, which are explained below under [Cluster Reconfiguration Operations][cluster-reconf].
 
 ### Cycle or Upgrade Multiple Machines
 
@@ -18,33 +16,23 @@ If you need to move multiple members of your cluster due to planned maintenance
 
 It is safe to remove the leader, however there is a brief period of downtime while the election process takes place. If your cluster holds more than 50MB, it is recommended to [migrate the member's data directory][member migration].
 
-[member migration]: admin_guide.md#member-migration
-
 ### Change the Cluster Size
 
 Increasing the cluster size can enhance [failure tolerance][fault tolerance table] and provide better read performance. Since clients can read from any member, increasing the number of members increases the overall read throughput.
 
 Decreasing the cluster size can improve the write performance of a cluster, with a trade-off of decreased resilience. Writes into the cluster are replicated to a majority of members of the cluster before considered committed. Decreasing the cluster size lowers the majority, and each write is committed more quickly.
 
-[fault tolerance table]: admin_guide.md#fault-tolerance-table
-
 ### Replace A Failed Machine
 
 If a machine fails due to hardware failure, data directory corruption, or some other fatal situation, it should be replaced as soon as possible. Machines that have failed but haven't been removed adversely affect your quorum and reduce the tolerance for an additional failure.
 
 To replace the machine, follow the instructions for [removing the member][remove member] from the cluster, and then [add a new member][add member] in its place. If your cluster holds more than 50MB, it is recommended to [migrate the failed member's data directory][member migration] if you can still access it.
 
-[remove member]: #remove-a-member
-[add member]: #add-a-new-member
-
 ### Restart Cluster from Majority Failure
 
 If the majority of your cluster is lost or all of your nodes have changed IP addresses, then you need to take manual action in order to recover safely.
 The basic steps in the recovery process include [creating a new cluster using the old data][disaster recovery], forcing a single member to act as the leader, and finally using runtime configuration to [add new members][add member] to this new cluster one at a time.
 
-[add member]: #add-a-new-member
-[disaster recovery]: admin_guide.md#disaster-recovery
-
 ## Cluster Reconfiguration Operations
 
 Now that we have the use cases in mind, let us lay out the operations involved in each.
@@ -60,7 +48,7 @@ All changes to the cluster are done one at a time:
 * To decrease from 5 to 3 you will make two remove operations
 
 All of these examples will use the `etcdctl` command line tool that ships with etcd.
-If you want to use the members API directly you can find the documentation [here](members_api.md).
+If you want to use the members API directly you can find the documentation [here][member-api].
 
 ### Update a Member
 
@@ -115,10 +103,10 @@ It is safe to remove the leader, however the cluster will be inactive while a ne
 
 Adding a member is a two step process:
 
- * Add the new member to the cluster via the [members API](members_api.md#post-v2members) or the `etcdctl member add` command.
+ * Add the new member to the cluster via the [members API][member-api] or the `etcdctl member add` command.
  * Start the new member with the new cluster configuration, including a list of the updated members (existing members + the new member).
 
-Using `etcdctl` let's add the new member to the cluster by specifying its [name](configuration.md#-name) and [advertised peer URLs](configuration.md#-initial-advertise-peer-urls):
+Using `etcdctl` let's add the new member to the cluster by specifying its [name][conf-name] and [advertised peer URLs][conf-adv-peer]:
 
 ```sh
 $ etcdctl member add infra3 http://10.0.1.13:2380
@@ -182,3 +170,15 @@ As described in the above, the best practice of adding new members is to configu
 For avoiding this problem, etcd provides an option `-strict-reconfig-check`. If this option is passed to etcd, etcd rejects reconfiguration requests if the number of started members will be less than a quorum of the reconfigured cluster.
 
 It is recommended to enable this option. However, it is disabled by default because of keeping compatibility.
+
+[add member]: #add-a-new-member
+[cluster-reconf]: #cluster-reconfiguration-operations
+[conf-adv-peer]: configuration.md#-initial-advertise-peer-urls
+[conf-name]: configuration.md#-name
+[disaster recovery]: admin_guide.md#disaster-recovery
+[fault tolerance table]: admin_guide.md#fault-tolerance-table
+[majority failure]: #restart-cluster-from-majority-failure
+[member-api]: members_api.md
+[member migration]: admin_guide.md#member-migration
+[remove member]: #remove-a-member
+[runtime-reconf]: runtime-reconf-design.md

Documentation/runtime-reconf-design.md

@@ -6,7 +6,7 @@ Read on to learn about the design of etcd's runtime reconfiguration commands and
 
 ## Two Phase Config Changes Keep you Safe
 
-In etcd, every runtime reconfiguration has to go through [two phases](Documentation/runtime-configuration.md#add-a-new-member) for safety reasons. For example, to add a member you need to first inform cluster of new configuration and then start the new member.
+In etcd, every runtime reconfiguration has to go through [two phases][add-member] for safety reasons. For example, to add a member you need to first inform cluster of new configuration and then start the new member.
 
 Phase 1 - Inform cluster of new configuration
 
@@ -28,7 +28,7 @@ If a cluster permanently loses a majority of its members, a new cluster will nee
 
 It is entirely possible to force removing the failed members from the existing cluster to recover. However, we decided not to support this method since it bypasses the normal consensus committing phase, which is unsafe. If the member to remove is not actually dead or you force to remove different members through different members in the same cluster, you will end up with diverged cluster with same clusterID. This is very dangerous and hard to debug/fix afterwards. 
 
-If you have a correct deployment, the possibility of permanent majority lose is very low. But it is a severe enough problem that worth special care. We strongly suggest you to read the [disaster recovery documentation](admin_guide.md#disaster-recovery) and prepare for permanent majority lose before you put etcd into production.
+If you have a correct deployment, the possibility of permanent majority lose is very low. But it is a severe enough problem that worth special care. We strongly suggest you to read the [disaster recovery documentation][disaster-recovery] and prepare for permanent majority lose before you put etcd into production.
 
 ## Do Not Use Public Discovery Service For Runtime Reconfiguration
 
@@ -45,3 +45,6 @@ It seems that using public discovery service is a convenient way to do runtime r
 3. public discovery service has to keep tens of thousands of cluster configurations. Our public discovery service backend is not ready for that workload.
 
 If you want to have a discovery service that supports runtime reconfiguration, the best choice is to build your private one.
+
+[add-member]: runtime-configuration.md#add-a-new-member
+[disaster-recovery]: admin_guide.md#disaster-recovery

Documentation/security.md

@@ -4,7 +4,7 @@ etcd supports SSL/TLS as well as authentication through client certificates, bot
 
 To get up and running you first need to have a CA certificate and a signed key pair for one member. It is recommended to create and sign a new key pair for every member in a cluster.
 
-For convenience, the [cfssl](https://github.com/cloudflare/cfssl) tool provides an easy interface to certificate generation, and we provide an example using the tool [here](https://github.com/coreos/etcd/tree/master/hack/tls-setup). You can also examine this [alternative guide to generating self-signed key pairs](http://www.g-loaded.eu/2005/11/10/be-your-own-ca/).
+For convenience, the [cfssl] tool provides an easy interface to certificate generation, and we provide an example using the tool [here][tls-setup]. You can also examine this [alternative guide to generating self-signed key pairs][tls-guide].
 
 ## Basic setup
 
@@ -177,4 +177,9 @@ $ openssl ca -config openssl.cnf -policy policy_anything -extensions ssl_client
 ### With peer certificate authentication I receive "certificate is valid for 127.0.0.1, not $MY_IP"
 Make sure that you sign your certificates with a Subject Name your member's public IP address. The `etcd-ca` tool for example provides an `--ip=` option for its `new-cert` command.
 
-If you need your certificate to be signed for your member's FQDN in its Subject Name then you could use Subject Alternative Names (short IP SANs) to add your IP address. The `etcd-ca` tool provides `--domain=` option for its `new-cert` command, and openssl can make [it](http://wiki.cacert.org/FAQ/subjectAltName) too.
+If you need your certificate to be signed for your member's FQDN in its Subject Name then you could use Subject Alternative Names (short IP SANs) to add your IP address. The `etcd-ca` tool provides `--domain=` option for its `new-cert` command, and openssl can make [it][alt-name] too.
+
+[cfssl]: https://github.com/cloudflare/cfssl
+[tls-setup]: /hack/tls-setup
+[tls-guide]: https://github.com/coreos/docs/blob/master/os/generate-self-signed-certificates.md
+[alt-name]: http://wiki.cacert.org/FAQ/subjectAltName

Documentation/tuning.md

@@ -21,7 +21,7 @@ Adjusting these values is a trade off.
 The value of heartbeat interval is recommended to be around the maximum of average round-trip time (RTT) between members, normally around 0.5-1.5x the round-trip time.
 If heartbeat interval is too low, etcd will send unnecessary messages that increase the usage of CPU and network resources.
 On the other side, a too high heartbeat interval leads to high election timeout. Higher election timeout takes longer time to detect a leader failure.
-The easiest way to measure round-trip time (RTT) is to use [PING utility](https://en.wikipedia.org/wiki/Ping_(networking_utility)).
+The easiest way to measure round-trip time (RTT) is to use [PING utility][ping].
 
 The election timeout should be set based on the heartbeat interval and average round-trip time between members.
 Election timeouts must be at least 10 times the round-trip time so it can account for variance in your network.
@@ -71,3 +71,5 @@ $ etcd -snapshot-count=5000
 # Environment variables:
 $ ETCD_SNAPSHOT_COUNT=5000 etcd
 ```
+
+[ping]: https://en.wikipedia.org/wiki/Ping_(networking_utility)

Documentation/upgrade_2_1.md

@@ -10,7 +10,7 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
 
 ### Upgrade Requirements
 
-To upgrade an existing etcd deployment to 2.1, you must be running 2.0. If you’re running a version of etcd before 2.0, you must upgrade to [2.0](https://github.com/coreos/etcd/releases/tag/v2.0.13) before upgrading to 2.1.
+To upgrade an existing etcd deployment to 2.1, you must be running 2.0. If you’re running a version of etcd before 2.0, you must upgrade to [2.0][v2.0] before upgrading to 2.1.
 
 Also, to ensure a smooth rolling upgrade, your running cluster must be healthy. You can check the health of the cluster by using `etcdctl cluster-health` command. 
 
@@ -18,9 +18,9 @@ Also, to ensure a smooth rolling upgrade, your running cluster must be healthy.
 
 Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. 
 
-You might also want to [backup your data directory](admin_guide.md#backing-up-the-datastore) for a potential [downgrade](#downgrade).
+You might also want to [backup your data directory][backup-datastore] for a potential [downgrade](#downgrade).
 
-etcd 2.1 introduces a new [authentication](auth_api.md) feature, which is disabled by default. If your deployment depends on these, you may want to test the auth features before enabling them in production.
+etcd 2.1 introduces a new [authentication][auth] feature, which is disabled by default. If your deployment depends on these, you may want to test the auth features before enabling them in production.
 
 ### Mixed Versions
 
@@ -40,7 +40,7 @@ If you have even more data, this might take more time. If you have a data size l
 
 If all members have been upgraded to v2.1, the cluster will be upgraded to v2.1, and downgrade is **not possible**. If any member is still v2.0, the cluster will remain in v2.0, and you can go back to use v2.0 binary. 
 
-Please [backup your data directory](admin_guide.md#backing-up-the-datastore) of all etcd members if you want to downgrade the cluster, even if it is upgraded.
+Please [backup your data directory][backup-datastore] of all etcd members if you want to downgrade the cluster, even if it is upgraded.
 
 ### Upgrade Procedure
 
@@ -70,7 +70,7 @@ You will see similar error logging from other etcd processes in your cluster. Th
 2015/06/23 15:45:11 stream: stopping the stream server...
 ```
 
-You could [backup your data directory](https://github.com/coreos/etcd/blob/7f7e2cc79d9c5c342a6eb1e48c386b0223cf934e/Documentation/admin_guide.md#backing-up-the-datastore) for data safety.
+You could [backup your data directory][backup-datastore] for data safety.
 
 ```
 $ etcdctl backup \
@@ -110,3 +110,7 @@ When all members are upgraded, you will see the cluster is upgraded to 2.1 succe
 $ curl http://127.0.0.1:4001/version
 {"etcdserver":"2.1.x","etcdcluster":"2.1.0"}
 ```
+
+[auth]: auth_api.md
+[backup-datastore]: admin_guide.md#backing-up-the-datastore
+[v2.0]: https://github.com/coreos/etcd/releases/tag/v2.0.13

Documentation/upgrade_2_2.md

@@ -11,7 +11,7 @@ Before [starting an upgrade](#upgrade-procedure), read through the rest of this
 
 ### Upgrade Requirement
 
-To upgrade an existing etcd deployment to 2.2, you must be running 2.1. If you’re running a version of etcd before 2.1, you must upgrade to [2.1](https://github.com/coreos/etcd/releases/tag/v2.1.2) before upgrading to 2.2.
+To upgrade an existing etcd deployment to 2.2, you must be running 2.1. If you’re running a version of etcd before 2.1, you must upgrade to [2.1][v2.1] before upgrading to 2.2.
 
 Also, to ensure a smooth rolling upgrade, your running cluster must be healthy. You can check the health of the cluster by using `etcdctl cluster-health` command. 
 
@@ -19,7 +19,7 @@ Also, to ensure a smooth rolling upgrade, your running cluster must be healthy.
 
 Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. 
 
-You might also want to [backup your data directory](admin_guide.md#backing-up-the-datastore) for a potential [downgrade](#downgrade).
+You might also want to [backup the data directory][backup-datastore] for a potential [downgrade].
 
 ### Mixed Versions
 
@@ -37,7 +37,7 @@ Every etcd 2.2 member will do health checking across the cluster periodically. e
 
 If all members have been upgraded to v2.2, the cluster will be upgraded to v2.2, and downgrade is **not possible**. If any member is still v2.1, the cluster will remain in v2.1, and you can go back to use v2.1 binary. 
 
-Please [backup your data directory](admin_guide.md#backing-up-the-datastore) of all etcd members if you want to downgrade the cluster, even if it is upgraded.
+Please [backup the data directory][backup-datastore] of all etcd members if you want to downgrade the cluster, even if it is upgraded.
 
 ### Upgrade Procedure
 
@@ -85,7 +85,7 @@ You will also see logging output like this from the newly upgraded member, since
 
 ```
 
-You could [backup your data directory](https://github.com/coreos/etcd/blob/7f7e2cc79d9c5c342a6eb1e48c386b0223cf934e/Documentation/admin_guide.md#backing-up-the-datastore) for data safety.
+[Backup your data directory][backup-datastore] for data safety.
 
 ```
 $ etcdctl backup \
@@ -126,3 +126,7 @@ When all members are upgraded, you will see the cluster is upgraded to 2.2 succe
 $ curl http://127.0.0.1:4001/version
 {"etcdserver":"2.2.x","etcdcluster":"2.2.0"}
 ```
+
+[backup-datastore]: admin_guide.md#backing-up-the-datastore
+[downgrade]: #downgrade
+[v2.1]: https://github.com/coreos/etcd/releases/tag/v2.1.2