From 78b7253bb45a48c3e98e7c5f542962ce411a125b Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Fri, 7 Aug 2026 20:24:07 -0400
Subject: [PATCH 1/3] feat: cross links

Signed-off-by: avivkeller <me@aviv.sh>
---
 .changeset/crosslinks.md                      |  5 ++
 packages/react/src/html/index.mjs             |  7 +-
 packages/react/src/html/types.d.ts            |  2 +-
 .../src/html/ui/components/Layout/index.jsx   | 75 ++++++++++++++-----
 .../ui/components/Layout/index.module.css     | 13 ++++
 www/doc-kit.config.mjs                        |  1 +
 6 files changed, 81 insertions(+), 22 deletions(-)
 create mode 100644 .changeset/crosslinks.md
 create mode 100644 packages/react/src/html/ui/components/Layout/index.module.css

diff --git a/.changeset/crosslinks.md b/.changeset/crosslinks.md
new file mode 100644
index 00000000..3b85ef02
--- /dev/null
+++ b/.changeset/crosslinks.md
@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+Adds support for cross-links, opt-in with `showCrossLinks: true`
\ No newline at end of file
diff --git a/packages/react/src/html/index.mjs b/packages/react/src/html/index.mjs
index 461e6387..4f09bf6b 100644
--- a/packages/react/src/html/index.mjs
+++ b/packages/react/src/html/index.mjs
@@ -74,7 +74,12 @@ export default {
     components: {},
 
     // The SideBar and NavBar navigation items
-    navigation: {},
+    // along with other navigational settings (e.g. showCrossLinks)
+    navigation: {
+      // Whether or not to show the CrossLink component at the bottom of the
+      // default layout.
+      showCrossLinks: false,
+    },
 
     // When omitted, the Vite adapter is loaded lazily during generation.
     bundler: undefined,
diff --git a/packages/react/src/html/types.d.ts b/packages/react/src/html/types.d.ts
index c0ac4cfd..b79297f8 100644
--- a/packages/react/src/html/types.d.ts
+++ b/packages/react/src/html/types.d.ts
@@ -77,7 +77,7 @@ export type Configuration = {
   navigation: {
     sidebar?: ComponentProps<typeof SideBar>['groups'];
     navbar?: ComponentProps<typeof NavBar>['navItems'];
-    // TODO(@avivkeller): `navigation.showCrossLinks`
+    showCrossLinks?: boolean;
   };
   // Optional bundler adapter. When omitted, the Vite adapter is loaded lazily.
   bundler?: WebBundler;
diff --git a/packages/react/src/html/ui/components/Layout/index.jsx b/packages/react/src/html/ui/components/Layout/index.jsx
index 7b0c243c..3980559c 100644
--- a/packages/react/src/html/ui/components/Layout/index.jsx
+++ b/packages/react/src/html/ui/components/Layout/index.jsx
@@ -1,8 +1,11 @@
+import CrossLink from '@node-core/ui-components/Common/BaseCrossLink';
 import TableOfContents from '@node-core/ui-components/Common/TableOfContents';
 import Article from '@node-core/ui-components/Containers/Article';
 
 import Banner from '../Banner';
+import styles from './index.module.css';
 
+import { navigation } from '#theme/config';
 import Footer from '#theme/Footer';
 import MetaBar from '#theme/Metabar';
 import NavBar from '#theme/Navigation';
@@ -17,25 +20,57 @@ import SideBar from '#theme/Sidebar';
  *
  * @param {{ metadata: import('../../types').SerializedMetadata, headings: Array, readingTime: string, children: import('preact').ComponentChildren }} props
  */
-export default ({ metadata, headings, readingTime, children }) => (
-  <>
-    <Banner />
-    <NavBar metadata={metadata} />
-    <Article>
-      <SideBar metadata={metadata} />
-      <div>
+export default ({ metadata, headings, readingTime, children }) => {
+  const crossLinkItems = navigation.sidebar.flatMap(({ items }) => items);
+
+  const currentItem = crossLinkItems.findIndex(
+    ({ link }) => link === metadata.path
+  );
+
+  const [previousCrossLink, nextCrossLink] = [
+    crossLinkItems[currentItem - 1],
+    crossLinkItems[currentItem + 1],
+  ];
+
+  return (
+    <>
+      <Banner />
+      <NavBar metadata={metadata} />
+      <Article>
+        <SideBar metadata={metadata} />
         <div>
-          <TableOfContents headings={headings} summaryTitle="On this page" />
-          <br />
-          <main>{children}</main>
+          <div>
+            <TableOfContents headings={headings} summaryTitle="On this page" />
+            <br />
+            <main>{children}</main>
+            <div className={styles.crossLinks}>
+              {(previousCrossLink && (
+                <CrossLink
+                  type="previous"
+                  label="Previous"
+                  text={previousCrossLink.label}
+                  link={previousCrossLink.link}
+                />
+              )) || <div />}
+
+              {nextCrossLink && (
+                <CrossLink
+                  type="next"
+                  label="Next"
+                  text={nextCrossLink.label}
+                  link={nextCrossLink.link}
+                />
+              )}
+            </div>
+          </div>
+          <MetaBar
+            metadata={metadata}
+            headings={headings}
+            readingTime={readingTime}
+          />
         </div>
-        <MetaBar
-          metadata={metadata}
-          headings={headings}
-          readingTime={readingTime}
-        />
-      </div>
-    </Article>
-    <Footer />
-  </>
-);
+      </Article>
+      <Footer />
+    </>
+  );
+};
diff --git a/packages/react/src/html/ui/components/Layout/index.module.css b/packages/react/src/html/ui/components/Layout/index.module.css
new file mode 100644
index 00000000..6ca6a459
--- /dev/null
+++ b/packages/react/src/html/ui/components/Layout/index.module.css
@@ -0,0 +1,13 @@
+.crossLinks {
+  margin-top: 1rem;
+  display: grid;
+  width: 100%;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+}
+
+@media (max-width: 767px) {
+  .crossLinks {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
\ No newline at end of file
diff --git a/www/doc-kit.config.mjs b/www/doc-kit.config.mjs
index 14e3164e..3e2733a3 100644
--- a/www/doc-kit.config.mjs
+++ b/www/doc-kit.config.mjs
@@ -76,6 +76,7 @@ export default {
     pathsToCopy: [{ [join(ROOT, 'content')]: '.' }],
 
     navigation: {
+      withCrossLinks: true,
       sidebar: [
         {
           groupName: 'Start',

From a65afa6548b937725071725ee10a81c602197f71 Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Fri, 7 Aug 2026 20:24:56 -0400
Subject: [PATCH 2/3] fixup!

---
 .changeset/crosslinks.md                                      | 2 +-
 packages/react/src/html/ui/components/Layout/index.module.css | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.changeset/crosslinks.md b/.changeset/crosslinks.md
index 3b85ef02..a633e0d5 100644
--- a/.changeset/crosslinks.md
+++ b/.changeset/crosslinks.md
@@ -2,4 +2,4 @@
 '@doc-kit/generator-react': patch
 ---
 
-Adds support for cross-links, opt-in with `showCrossLinks: true`
\ No newline at end of file
+Adds support for cross-links, opt-in with `showCrossLinks: true`
diff --git a/packages/react/src/html/ui/components/Layout/index.module.css b/packages/react/src/html/ui/components/Layout/index.module.css
index 6ca6a459..b321db3d 100644
--- a/packages/react/src/html/ui/components/Layout/index.module.css
+++ b/packages/react/src/html/ui/components/Layout/index.module.css
@@ -10,4 +10,4 @@
   .crossLinks {
     grid-template-columns: minmax(0, 1fr);
   }
-}
\ No newline at end of file
+}

From eb59116b9b126577d2ab4fbe125dbee611346a45 Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Fri, 7 Aug 2026 20:29:24 -0400
Subject: [PATCH 3/3] fixup!

---
 .../src/html/ui/components/Layout/index.jsx   | 42 ++++++++++---------
 www/doc-kit.config.mjs                        |  2 +-
 2 files changed, 24 insertions(+), 20 deletions(-)

diff --git a/packages/react/src/html/ui/components/Layout/index.jsx b/packages/react/src/html/ui/components/Layout/index.jsx
index 3980559c..6308aa74 100644
--- a/packages/react/src/html/ui/components/Layout/index.jsx
+++ b/packages/react/src/html/ui/components/Layout/index.jsx
@@ -21,7 +21,9 @@ import SideBar from '#theme/Sidebar';
  * @param {{ metadata: import('../../types').SerializedMetadata, headings: Array, readingTime: string, children: import('preact').ComponentChildren }} props
  */
 export default ({ metadata, headings, readingTime, children }) => {
-  const crossLinkItems = navigation.sidebar.flatMap(({ items }) => items);
+  const crossLinkItems = navigation.showCrossLinks
+    ? (navigation.sidebar?.flatMap(({ items }) => items) ?? [])
+    : [];
 
   const currentItem = crossLinkItems.findIndex(
     ({ link }) => link === metadata.path
@@ -43,25 +45,27 @@ export default ({ metadata, headings, readingTime, children }) => {
             <TableOfContents headings={headings} summaryTitle="On this page" />
             <br />
             <main>{children}</main>
-            <div className={styles.crossLinks}>
-              {(previousCrossLink && (
-                <CrossLink
-                  type="previous"
-                  label="Previous"
-                  text={previousCrossLink.label}
-                  link={previousCrossLink.link}
-                />
-              )) || <div />}
+            {(previousCrossLink || nextCrossLink) && (
+              <div className={styles.crossLinks}>
+                {(previousCrossLink && (
+                  <CrossLink
+                    type="previous"
+                    label="Previous"
+                    text={previousCrossLink.label}
+                    link={previousCrossLink.link}
+                  />
+                )) || <div />}
 
-              {nextCrossLink && (
-                <CrossLink
-                  type="next"
-                  label="Next"
-                  text={nextCrossLink.label}
-                  link={nextCrossLink.link}
-                />
-              )}
-            </div>
+                {nextCrossLink && (
+                  <CrossLink
+                    type="next"
+                    label="Next"
+                    text={nextCrossLink.label}
+                    link={nextCrossLink.link}
+                  />
+                )}
+              </div>
+            )}
           </div>
           <MetaBar
             metadata={metadata}
diff --git a/www/doc-kit.config.mjs b/www/doc-kit.config.mjs
index 3e2733a3..e4796c87 100644
--- a/www/doc-kit.config.mjs
+++ b/www/doc-kit.config.mjs
@@ -76,7 +76,7 @@ export default {
     pathsToCopy: [{ [join(ROOT, 'content')]: '.' }],
 
     navigation: {
-      withCrossLinks: true,
+      showCrossLinks: true,
       sidebar: [
         {
           groupName: 'Start',