feat: cross links

.changeset/crosslinks.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': patch
+---
+
+Adds support for cross-links, opt-in with `showCrossLinks: true`

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,

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;

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,61 @@ 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.showCrossLinks
+    ? (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>
+            {(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>
+            )}
+          </div>
+          <MetaBar
+            metadata={metadata}
+            headings={headings}
+            readingTime={readingTime}
+          />
         </div>
-        <MetaBar
-          metadata={metadata}
-          headings={headings}
-          readingTime={readingTime}
-        />
-      </div>
-    </Article>
-    <Footer />
-  </>
-);
+      </Article>
+      <Footer />
+    </>
+  );
+};

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);
+  }
+}

www/doc-kit.config.mjs

@@ -76,6 +76,7 @@ export default {
     pathsToCopy: [{ [join(ROOT, 'content')]: '.' }],
 
     navigation: {
+      showCrossLinks: true,
       sidebar: [
         {
           groupName: 'Start',