feat(nav): add display names and section flag

__tests__/buildNav.test.js

@@ -13,3 +13,22 @@ test('generates navigation tree', () => {
   const install = guide.children.find(c => c.name === 'install.md');
   expect(install.path).toBe('/guide/install.html');
 });
+
+test('adds display names and section flags', () => {
+  const pages = [
+    { file: '02-api.md', data: { title: 'API', order: 2 } },
+    { file: '01-guide/index.md', data: { title: 'Guide', order: 1 } },
+    { file: '01-guide/setup.md', data: { title: 'Setup', order: 2 } },
+    { file: 'index.md', data: { title: 'Home', order: 10 } }
+  ];
+  const nav = buildNav(pages);
+  expect(nav[0].name).toBe('index.md');
+  const guide = nav.find(n => n.name === '01-guide');
+  expect(guide.displayName).toBe('Guide');
+  expect(guide.isSection).toBe(true);
+  const api = nav.find(n => n.name === '02-api.md');
+  expect(api.displayName).toBe('API');
+  // alphabetical within same order
+  expect(nav[1].name).toBe('01-guide');
+  expect(nav[2].name).toBe('02-api.md');
+});

src/generator/index.js

@@ -8,6 +8,12 @@ const { lexer } = marked;
 const loadConfig = require('../config/loadConfig');
 const loadPlugins = require('../config/loadPlugins');
 
+function formatName(name) {
+  return name
+    .replace(/^\d+[-_]?/, '')
+    .replace(/\.md$/, '');
+}
+
 async function readDirRecursive(dir) {
   const entries = await fs.promises.readdir(dir, { withFileTypes: true });
   const files = [];
@@ -64,12 +70,33 @@ function buildNav(pages) {
     }
   }
 
-  function sort(node) {
+  function finalize(node, isRoot = false) {
-    if (!node.children) return;
+    if (node.page && node.page.title) {
-    node.children.sort((a, b) => (a.order || 0) - (b.order || 0));
+      node.displayName = node.page.title;
-    node.children.forEach(sort);
+    } else if (node.name) {
+      node.displayName = formatName(node.name);
+    }
+    if (node.children) {
+      node.children.forEach(c => finalize(c));
+      node.children.sort((a, b) => {
+        const orderDiff = (a.order || 0) - (b.order || 0);
+        if (orderDiff !== 0) return orderDiff;
+        return (a.displayName || '').localeCompare(b.displayName || '');
+      });
+      node.isSection = node.children.length > 0;
+    } else {
+      node.isSection = false;
+    }
+    if (isRoot && node.children) {
+      const idx = node.children.findIndex(c => c.name === 'index.md');
+      if (idx > 0) {
+        const [first] = node.children.splice(idx, 1);
+        node.children.unshift(first);
+      }
+    }
   }
-  sort(tree);
+
+  finalize(tree, true);
   return tree.children || [];
 }