Update docs

docs/api-reference.md

@@ -268,8 +268,12 @@ An "action" represents a type of change that occurred in the history stack.
 ## To
 
 A "to" value represents a destination location, but doesn't contain all the
-information that a normal [`location`](#location) object does.
+information that a normal [`location`](#location) object does. It is primarily
+used as the first argument to [`history.push`](#historypushto-to-state-state)
+and [`history.replace`](#historyreplaceto-to-state-state).
 
 <pre>
 type To = <a href="https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L32">Path</a> | <a href="https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L72">PathPieces</a>;
 </pre>
+
+See [the Navigation guide](navigation.md) for more information.

docs/blocking-transitions.md

@@ -1,6 +1,8 @@
 # Blocking Transitions
 
-`history` lets you block navigation away from the current page. For example, you
+`history` lets you block navigation away from the current page using the
+[`history.block(blocker:
+Blocker)`](api-reference.md#historyblockblocker-blocker) API. For example, you
 can make sure the user knows that if they leave the current page they will lose
 some unsaved changes they've made.
 
@@ -22,8 +24,9 @@ let unblock = history.block(tx => {
 });
 ```
 
-This example uses `window.confirm`, but you could also use your own custom
-confirm dialog if you'd rather.
+This example uses
+[`window.confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm),
+but you could also use your own custom confirm dialog if you'd prefer.
 
 ## Caveats
 

docs/getting-started.md

@@ -21,9 +21,13 @@ environment:
   non-browser environments, like [React
   Native](https://facebook.github.io/react-native/) or tests
 
-The main bundle exports one method for each environment: `createBrowserHistory`
-for browsers, `createHashHistory` for using hash history in browsers,  and
-`createMemoryHistory` for creating an in-memory history.
+The main bundle exports one method for each environment:
+[`createBrowserHistory`](api-reference.md#createbrowserhistory-window-window-)
+for browsers,
+[`createHashHistory`](api-reference.md#createhashhistory-window-window-) for
+using hash history in browsers,  and
+[`createMemoryHistory`](api-reference.md#creatememoryhistory-initialentries-initialentry-initialindex-number-)
+for creating an in-memory history.
 
 In addition to the main bundle, the library also includes `history/browser` and
 `history/hash` bundles that export singletons you can use to quickly get a
@@ -36,7 +40,11 @@ history instance for [the current
 Basic usage looks like this:
 
 ```js
-// Import the browser history singleton instance.
+// Create your own history instance.
+import { createBrowserHistory } from 'history';
+let history = createBrowserHistory();
+
+// ... or just import the browser history singleton instance.
 import history from 'history/browser';
 
 // Alternatively, if you're using hash history import
@@ -87,8 +95,8 @@ let history = createBrowserHistory({
 
 Each `history` object has the following properties:
 
-- `history.location` - The current location (see below)
-- `history.action` - The current navigation action (see below)
+- [`history.location`](api-reference.md#historylocation) - The current location (see below)
+- [`history.action`](api-reference.md#historyaction) - The current navigation action (see below)
 
 Additionally, memory history provides `history.index` that tells you the current
 index in the history stack.
@@ -106,26 +114,24 @@ history.listen(({ action, location }) => {
 });
 ```
 
-The `location` object implements a subset of [the `window.location`
+The [`location`](api-reference.md#location) object implements a subset of [the
+`window.location`
 interface](https://developer.mozilla.org/en-US/docs/Web/API/Location),
 including:
 
-- `location.pathname` - The path of the URL
-- `location.search` - The URL query string
-- `location.hash` - The URL hash fragment
-
-Locations may also have the following properties:
-
-- `location.state` - Some extra state for this location that does not reside in 
-  the URL
-- `location.key` - A unique string representing this location
+- [`location.pathname`](api-reference.md#locationpathname) - The path of the URL
+- [`location.search`](api-reference.md#locationsearch) - The URL query string
+- [`location.hash`](api-reference.md#locationhash) - The URL hash fragment
+- [`location.state`](api-reference.md#locationstate) - Some extra state for this
+  location that does not reside in the URL (may be `null`)
+- [`location.key`](api-reference.md#locationkey) - A unique string representing this location
 
-The `action` is one of `PUSH`, `REPLACE`, or `POP` depending on how the user got
-to the current URL.
+The [`action`](api-reference.md#action) is one of `Action.Push`, `Action.Replace`,
+or `Action.Pop` depending on how the user got to the current location.
 
-- A `PUSH` means one more entry was added to the history stack
-- A `REPLACE` means the current entry in the stack was replaced
-- A `POP` means we went to some other location already in the stack
+- `Action.Push` means one more entry was added to the history stack
+- `Action.Replace` means the current entry in the stack was replaced
+- `Action.Pop` means we went to some other location already in the stack
 
 ## Cleaning up
 

docs/navigation.md

@@ -3,18 +3,13 @@
 `history` objects may be used to programmatically change the current location
 using the following methods:
 
-- `history.push(path, [state])`
-- `history.replace(path, [state])`
-- `history.go(n)`
-- `history.back()`
-- `history.forward()`
+- [`history.push(to: To, state?: State)`](api-reference.md#historypushto-to-state-state)
+- [`history.replace(to: To, state?: State)`](api-reference.md#historyreplaceto-to-state-state)
+- [`history.go(delta: number)`](api-reference.md#historygodelta-number)
+- [`history.back()`](api-reference.md#historyback)
+- [`history.forward()`](api-reference.md#historyforward)
 
-When using `push` or `replace` you can either specify both the URL path and
-state as separate arguments or include everything in a single location-like
-object as the first argument.
-
-1. A URL path _or_
-2. A location-like object with `{ pathname, search, hash, state }`
+An example:
 
 ```js
 // Push a new entry onto the history stack.
@@ -24,12 +19,13 @@ history.push('/home');
 // and some state. Location state does not appear in the URL.
 history.push('/home?the=query', { some: 'state' });
 
-// If you prefer, use a single location-like object to specify both
-// the URL and state. This is equivalent to the example above.
+// If you prefer, use a location-like object to specify the URL.
+// This is equivalent to the example above.
 history.push({
   pathname: '/home',
-  search: '?the=query',
-  state: { some: 'state' }
+  search: '?the=query'
+}, {
+  some: state
 });
 
 // Go back to the previous history entry. The following