finish router refrence

docs/router/src/reference/navigation/programmatic.md

@@ -3,68 +3,25 @@
 Sometimes we want our application to navigate to another page without having the
 user click on a link. This is called programmatic navigation.
 
-## Acquiring a [`Navigator`]
+## Using a Navigator
 
-To use programmatic navigation, we first have to acquire a [`Navigator`]. For
-that purpose we can use the [`use_navigate`] hook.
-
-```rust, no_run
-# // Hidden lines (like this one) make the documentation tests work.
-# extern crate dioxus;
-use dioxus::prelude::*;
-# extern crate dioxus_router;
-use dioxus_router::prelude::*;
-
-fn Content(cx: Scope) -> Element {
-    let nav = use_navigate(cx).expect("called inside a router");
-
-    // ...
-    # unimplemented!()
-}
-```
-
-## Triggering a Navigation
+We can get a navigator with the [`use_navigator`] hook. This hook returns a [`Navigator`].
 
 We can use the [`Navigator`] to trigger four different kinds of navigation:
 
 - `push` will navigate to the target. It works like a regular anchor tag.
 - `replace` works like `push`, except that it replaces the current history entry
-  instead of adding a new one. This means the prior page cannot be restored with
-  the browsers back button.
-- `Go back` works like the browsers back button.
-- `Go forward` works like the browsers forward button (the opposite of the back
-  button).
+  instead of adding a new one. This means the prior page cannot be restored with the browser's back button.
+- `Go back` works like the browser's back button.
+- `Go forward` works like the browser's forward button.
 
 ```rust, no_run
-# // Hidden lines (like this one) make the documentation tests work.
-# extern crate dioxus;
-# use dioxus::prelude::*;
-# extern crate dioxus_router;
-# use dioxus_router::prelude::*;
-#
-fn Content(cx: Scope) -> Element {
-    let nav = use_navigate(cx).expect("called inside a router");
-
-    // push
-    nav.push("/target");
-
-    // replace
-    nav.replace("/target");
-
-    // go back
-    nav.go_back();
-
-    // go forward
-    nav.go_forward();
-
-    // ...
-    # unimplemented!()
-}
+{{#include ../../../examples/navigator.rs:nav}}
 ```
 
 You might have noticed that, like [`Link`], the [`Navigator`]s `push` and
-`replace` functions take a [`NavigationTarget`]. This means we can use
-[`Internal`], [`Named`] and [`External`].
+`replace` functions take a [`NavigationTarget`]. This means we can use either
+[`Internal`], or [`External`] targets.
 
 ## External Navigation Targets
 
@@ -72,13 +29,4 @@ Unlike a [`Link`], the [`Navigator`] cannot rely on the browser (or webview) to
 handle navigation to external targets via a generated anchor element.
 
 This means, that under certain conditions, navigation to external targets can
-fail. See the chapter about
-[external navigation failures](../failures/external.md) for more details.
-
-[`External`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html#variant.External
-[`Internal`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html#variant.Internal
-[`Link`]: https://docs.rs/dioxus-router/latest/dioxus_router/components/fn.Link.html
-[`Named`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html#variant.Named
-[`NavigationTarget`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/navigation/enum.NavigationTarget.html
-[`Navigator`]: https://docs.rs/dioxus-router-core/latest/dioxus_router_core/hooks/struct.Navigator.html
-[`use_navigate`]: https://docs.rs/dioxus-router/latest/dioxus_router/hooks/fn.use_navigate.html
+fail.