From bcf7e5b5abccbc8747f8fb169bebb24ec0ac31a9 Mon Sep 17 00:00:00 2001
From: Valerio Ageno <51341197+Valerioageno@users.noreply.github.com>
Date: Sun, 8 Dec 2024 10:18:20 +0100
Subject: [PATCH] docs: add link and navigation page content (#211)

Co-authored-by: Valerio Ageno <valerio.ageno@qonto.com>
Co-authored-by: Marco Pasqualetti <marco.pasqualetti@live.com>
---
 .../mdx-provider/mdx-code/mdx-code.tsx        |  2 +-
 .../src/components/sidebar/config.ts          | 10 +--
 .../routing/link-and-navigation.mdx           | 63 ++++++++++++++++++-
 3 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/apps/documentation/src/components/mdx-provider/mdx-code/mdx-code.tsx b/apps/documentation/src/components/mdx-provider/mdx-code/mdx-code.tsx
index cf7a9525..0a3d5a57 100644
--- a/apps/documentation/src/components/mdx-provider/mdx-code/mdx-code.tsx
+++ b/apps/documentation/src/components/mdx-provider/mdx-code/mdx-code.tsx
@@ -4,5 +4,5 @@ import { Code } from '@mantine/core'
 export default function MdxCode(
   props: HTMLAttributes<HTMLPreElement>,
 ): JSX.Element {
-  return <Code {...props} style={{ fontSize: 14 }} />
+  return <Code {...props} style={{ fontSize: 'inherit' }} />
 }
diff --git a/apps/documentation/src/components/sidebar/config.ts b/apps/documentation/src/components/sidebar/config.ts
index 58367e01..ad8cd663 100644
--- a/apps/documentation/src/components/sidebar/config.ts
+++ b/apps/documentation/src/components/sidebar/config.ts
@@ -111,6 +111,11 @@ export const sidebarElements: Array<SidebarElement> = [
         label: 'Defining routes',
         href: '/documentation/routing/defining-routes',
       },
+      {
+        type: 'element',
+        label: 'Link and navigation',
+        href: '/documentation/routing/link-and-navigation',
+      },
       {
         type: 'element',
         label: 'Pages',
@@ -131,11 +136,6 @@ export const sidebarElements: Array<SidebarElement> = [
         label: 'Layouts',
         href: '/documentation/routing/layouts',
       },
-      {
-        type: 'element',
-        label: 'Link and navigation',
-        href: '/documentation/routing/link-and-navigation',
-      },
       {
         type: 'element',
         label: 'Redirecting',
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 35c07f1c..86c4a1e5 100644
--- a/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx
+++ b/apps/documentation/src/routes/documentation/routing/link-and-navigation.mdx
@@ -11,4 +11,65 @@ import Breadcrumbs, { Element } from '@/components/breadcrumbs'
 
 # Link and navigation
 
-Todo
+The Tuono router facilitates client-side route transitions between pages, enhancing the user experience by:
+
+- Enabling smooth navigation in single-page applications (SPAs)
+- Preventing page reloads during site navigation
+
+How? Using the `Link` component provided from Tuono exports:
+
+```tsx
+import { Link } from 'tuono'
+
+export default function HomePage() {
+  return (
+    <ul>
+      <li>
+        <Link href="/">Home</Link>
+      </li>
+      <li>
+        <Link href="/about">About Us</Link>
+      </li>
+      <li>
+        <Link href="/blog/hello-world">Blog Post</Link>
+      </li>
+    </ul>
+  )
+}
+```
+
+The example above uses multiple links. Each one maps a path (`href`) to a known route:
+
+- `/` → `src/routes/index.tsx`
+- `/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.
+
+## 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.
+
+```tsx
+import { useRouter } from 'tuono'
+
+export default function GoToAboutPage() {
+  const router = useRouter()
+
+  return (
+    <ProfileForm
+      onUpdateSuccess={() => {
+        router.push('/profile')
+      }}
+    />
+  )
+}
+```
+
+> For more information about this hook visit the [dedicated API reference page](/documentation/hooks/use-router).