From 631b168e05fb02f67abf57c2e76e080edaaf4980 Mon Sep 17 00:00:00 2001
From: Jacob Marshall <me@jhqcat.com>
Date: Wed, 15 Jan 2025 18:17:35 +0000
Subject: [PATCH] docs: more cohesive documentation for linking and navigation,
 `Link` and `useRouter`  (#335)

---
 .../routes/documentation/components/link.mdx  | 25 ++++++++++++++++++-
 .../routing/link-and-navigation.mdx           | 20 +++++++++------
 2 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/apps/documentation/src/routes/documentation/components/link.mdx b/apps/documentation/src/routes/documentation/components/link.mdx
index 2dc1736e..1404aff9 100644
--- a/apps/documentation/src/routes/documentation/components/link.mdx
+++ b/apps/documentation/src/routes/documentation/components/link.mdx
@@ -11,4 +11,27 @@ import Breadcrumbs from '@/components/Breadcrumbs'
 
 # Link
 
-TODO
+Tuono provides a `Link` component for clientside navigation between pages of your app. `Link` prefetches pages from any links above the fold, allowing for faster navigations without a full reload.
+
+```typescript jsx
+import { Link } from 'tuono'
+
+export default function Page() {
+  return <Link href="/page2">My Other Page</Link>
+}
+```
+
+For navigating to pages outside of your app (other websites), you should use the `<a>` tag.
+
+> Additional considerations:
+>
+> - Any `Link` in the viewport is prefetched by default when it appears within the viewport.
+> - The corresponding data for server-rendered routes is fetched only when the `Link` is clicked.
+
+## Reference
+
+The `Link` component behaves similarly to the `<a>` HTML tag, with a few additional features controlled by the following props:
+
+- `href`: `string` (Required) - Relative path to the page in your application. Anchor names (links with hashtags) are also valid.
+- `preload`: `boolean` (Defaults to `true`) - Whether to preload the page if the link is within the viewport.
+- `scroll`: `boolean` (Defaults to `true`) - Whether to preserve scroll position between navigations.
diff --git a/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx b/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx
index 5fe1aad9..46b09c4a 100644
--- a/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx
+++ b/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx
@@ -16,7 +16,16 @@ The Tuono router facilitates client-side route transitions between pages, enhanc
 - Enabling smooth navigation in single-page applications (SPAs)
 - Preventing page reloads during site navigation
 
-How? Using the `Link` component provided from Tuono exports:
+Tuono provides two choices for navigation between pages of your app:
+
+- The `Link` component - used in place of an `<a>` tag
+- The `useRouter` hook - used to programmatically change routes, or to access data about the current route
+
+Use the `<a>` tag for navigating to other websites.
+
+## The `Link` component
+
+Tuono delivers this experience to users with the `Link` component provided from Tuono exports:
 
 ```tsx
 import { Link } from 'tuono'
@@ -44,17 +53,14 @@ The example above uses multiple links. Each one maps a path (`href`) to a known
 - `/about` → `src/routes/about.tsx`
 - `/blog/hello-world` → `src/routes/blog/[slug].tsx`
 
-> Additional considerations:
->
-> - Any `<Link />` in the viewport is prefetched by default when it appears within the viewport.
-> - The corresponding data for server-rendered routes is fetched only when the `<Link />` is clicked.
+> For more information about this component visit the [Link component API reference page](/documentation/components/link).
 
 ## The `useRouter` hook
 
 The Link component is not suitable for programmatic navigation.
 To handle this, the library provides the `useRouter` hook.
 
-For example, after a user submits a form and the API request succeeds, they can be redirected to another page.
+For example, after a user submits a form and the API request succeeds, they can be redirected to another page:
 
 ```tsx
 import { useRouter } from 'tuono'
@@ -72,4 +78,4 @@ export default function GoToAboutPage() {
 }
 ```
 
-> For more information about this hook visit the [dedicated API reference page](/documentation/hooks/use-router).
+> For more information about this hook visit the [useRouter API reference page](/documentation/hooks/use-router).