Code to let us sort certain doc categories to top

astro/src/tools/docs/DocNavContext.ts

@@ -13,4 +13,5 @@ export interface Category {
   href: string;
   entries: DocNavEntry[];
   subcategories: Category[];
+  sortFunction: (a: Category, b: Category) => number;
 }

astro/src/tools/docs/categoriesToFloatToTop.json

@@ -0,0 +1,5 @@
+{
+   "get started" : {
+     "EXAMPLE REMOVE ALL CAPS TEXT TO TEST download and install" : true
+   }
+}

astro/src/tools/docs/getDocNavContext.ts

@@ -2,12 +2,36 @@ import { getCollection } from 'astro:content';
 import { getDocHref } from 'src/tools/docs/getDocHref';
 import { Category, DocNavContext } from 'src/tools/docs/DocNavContext';
 
+// all category names here will be sorted to the top of their category listing. 
+// if there is more than one under a given category, they'll be sorted alphabetically
+import categoriesToFloatToTop from 'src/tools/docs/categoriesToFloatToTop.json';
+
 const joinup = (...parts: string[]) => [...parts].join('/')
 
 const prepContext = (context: DocNavContext, subcategory: string, tertcategory: string, quatercategory: string): Category => {
   let subContext: Category = null;
   let tertContext: Category = null;
   let qautContext: Category = null;
+
+  for (const categoryName in categoriesToFloatToTop) {
+    if (context.category.name === categoryName) {
+      const secondaryKeys = Object.keys(categoriesToFloatToTop[categoryName]);
+      context.category.sortFunction = ( (a, b) => {
+
+        // if both are included, sort lexically
+        if (secondaryKeys.includes(a.name) && secondaryKeys.includes(b.name)) {
+          return a.name.localeCompare(b.name);
+        }
+
+        // if one should be sorted to the top, do so
+        if (secondaryKeys.includes(a.name)) return -1;
+        if (secondaryKeys.includes(b.name)) return 1;
+
+        // if neither are included, sort lexically
+        return a.name.localeCompare(b.name);
+      } )
+    }
+  }
   if (subcategory) {
     subContext = context.category.subcategories.find(sub => sub.name === subcategory);
     if (!subContext) {
@@ -66,7 +90,11 @@ const recursiveSort = (category: Category) => {
     });
   }
   if (category.subcategories.length > 0) {
-    category.subcategories.sort((a, b) => a.name.localeCompare(b.name));
+    if (category.sortFunction) {
+      category.subcategories.sort(category.sortFunction);
+    } else {
+      category.subcategories.sort((a, b) => a.name.localeCompare(b.name));
+    }
     category.subcategories.forEach(sub => recursiveSort(sub));
   }
 }
@@ -85,6 +113,7 @@ export const getDocNavContext = async (section: string) => {
   sectionDocs.forEach(doc => {
     const { subcategory, tertcategory, quatercategory, title, description, navOrder } = doc.data;
     const category = prepContext(context, subcategory, tertcategory, quatercategory);
+
     category.entries.push({
       title,
       description,