fix(docs): honor the next frontmatter override on Next cards

src/pages/docs/[slug].astro

@@ -6,14 +6,22 @@ import { getOrderedDocs, docHref, sidebarLabel } from "../../lib/docs-nav";
 
 export async function getStaticPaths() {
   const docs = await getOrderedDocs();
-  return docs.map((doc, index) => ({
-    params: { slug: doc.id },
-    props: {
-      doc,
-      prev: index > 0 ? docs[index - 1] : null,
-      next: index < docs.length - 1 ? docs[index + 1] : null,
-    },
-  }));
+  return docs.map((doc, index) => {
+    // A `next:` frontmatter slug overrides the sequence order.
+    const override = doc.data.next;
+    const nextDoc = override ? docs.find((entry) => entry.id === override) : undefined;
+    if (override && !nextDoc) {
+      throw new Error(`docs/${doc.id}: next "${override}" does not match any doc`);
+    }
+    return {
+      params: { slug: doc.id },
+      props: {
+        doc,
+        prev: index > 0 ? docs[index - 1] : null,
+        next: nextDoc ?? (index < docs.length - 1 ? docs[index + 1] : null),
+      },
+    };
+  });
 }
 
 type Props = InferGetStaticPropsType<typeof getStaticPaths>;