diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md
index 33a479b629d79..0f53e8cf4c846 100644
--- a/docs/docs/gatsby-link.md
+++ b/docs/docs/gatsby-link.md
@@ -93,10 +93,41 @@ render () {
 }
 ```
 
-You can also pass state to pages when you navigate e.g. `navigate("/a-path/", { state: { pleasant: "reasonably" }}`
-
 Note that `navigate` was previously named `navigateTo`. `navigateTo` is deprecated in Gatsby v2.
 
+## Passing state through Link and Navigate
+
+You can pass state to pages when you navigate, such as:
+
+```javascript
+navigate(`/a-path/`, { state: { pleasant: `reasonably` }}
+```
+
+You can also pass state to pages when you use `Link`:
+
+```jsx
+<Link
+  to="/another-page/"
+  activeStyle={{
+    color: "red",
+  }}
+  state={{
+    pleasant: "reasonably",
+  }}
+>
+```
+
+This is accessible from the `location` object on the new page:
+
+```javascript
+componentDidMount() {
+  const pleasant = this.props.location.state.pleasant
+  this.setState({
+    pleasant: pleasant
+  })
+}
+```
+
 ## Prefixed paths helper
 
 It is common to host sites in a sub-directory of a site. Gatsby lets you [set