@life-and-dev/mdsite 0.4.0 → 0.5.1

package/mdsite-nuxt/app/components/AppFooter.vue

@@ -1,5 +1,6 @@
 <template>
   <v-app-bar
+    v-if="hasFooterEntries"
     location="bottom"
     height="56"
     class="app-footer"
@@ -7,30 +8,21 @@
   >
     <v-container class="d-flex justify-center align-center">
       <div class="footer-links">
-        <v-btn
-          v-if="hasAboutPage"
-          :href="aboutLink"
-          variant="text"
-          color="on-surface-appbar"
-          class="footer-link"
-        >
-          About
-        </v-btn>
-
-        <v-divider v-if="hasAboutPage && hasDisclaimerPage" vertical class="mx-2" />
-
-        <v-btn
-          v-if="hasDisclaimerPage"
-          :href="disclaimerLink"
-          variant="text"
-          color="on-surface-appbar"
-          class="footer-link"
-        >
-          Disclaimer
-        </v-btn>
-
-        <v-divider v-if="showEditDivider" vertical class="mx-2" />
-
+        <template v-for="(link, index) in footerHrefs" :key="link.path">
+          <v-btn
+            :href="link.path"
+            variant="text"
+            color="on-surface-appbar"
+            class="footer-link"
+          >
+            {{ link.title }}
+          </v-btn>
+          <v-divider
+            v-if="index < footerHrefs.length - 1 || editUrl"
+            vertical
+            class="mx-2"
+          />
+        </template>
         <v-btn
           v-if="editUrl"
           :href="editUrl"
@@ -49,25 +41,29 @@
 
 <script setup lang="ts">
 import { useSourceEdit } from '~/composables/useSourceEdit';
-import { useSearchIndex } from '~/composables/useSearchIndex'
+import { useFooter } from '~/composables/useFooter'
 import { withBasePath } from '../../utils/base-url'
 
 const appBaseURL = useRuntimeConfig().app.baseURL
 const { getEditUrl } = useSourceEdit()
-const { loadSearchIndex } = useSearchIndex()
-const footerPagePaths = ref<string[]>([])
+const { links: footerLinks, loadFooter } = useFooter()
 
-// Generate links to root content files
-const aboutLink = computed(() => withBasePath('/about', appBaseURL))
-const disclaimerLink = computed(() => withBasePath('/disclaimer', appBaseURL))
 const editUrl = computed(() => getEditUrl())
-const hasAboutPage = computed(() => footerPagePaths.value.includes('/about'))
-const hasDisclaimerPage = computed(() => footerPagePaths.value.includes('/disclaimer'))
-const showEditDivider = computed(() => editUrl.value && (hasAboutPage.value || hasDisclaimerPage.value))
+
+// Render the bar only after the footer JSON has loaded and contains at least
+// one entry. While loading (links === null) or when the array is empty, the
+// whole bar (including the Edit button) is hidden.
+const hasFooterEntries = computed(() =>
+  footerLinks.value !== null && footerLinks.value.length > 0
+)
+
+const footerHrefs = computed(() => (footerLinks.value ?? []).map(link => ({
+  path: withBasePath(link.path, appBaseURL),
+  title: link.title
+})))
 
 onMounted(async () => {
-  const searchIndex = await loadSearchIndex()
-  footerPagePaths.value = searchIndex.map(entry => entry.path)
+  await loadFooter()
 })
 </script>
 

package/mdsite-nuxt/app/components/AppTableOfContents.vue

@@ -1,11 +1,20 @@
 <template>
-  <div class="toc-sidebar" ref="tocContainer">
+  <!--
+    Guard at the root: the consuming composable's `shouldShowTOC` already
+    requires `tocItems.length >= TOC_MIN_HEADINGS (3)`, so by the time we
+    reach this template a usable TOC is guaranteed. Render nothing otherwise.
+  -->
+  <div
+    v-if="tocItems.length >= 3"
+    class="toc-sidebar"
+    ref="tocContainer"
+  >
     <!-- Header -->
     <h3 v-if="showHeader" class="toc-header">On This Page</h3>
     <v-divider v-if="showHeader" class="mb-2" />
 
     <!-- TOC Items -->
-    <nav v-if="tocItems.length >= 2" class="toc-nav">
+    <nav class="toc-nav">
       <TocItem
         v-for="item in tocItems"
         :key="item.id"
@@ -15,11 +24,6 @@
       />
     </nav>
 
-    <!-- Empty state -->
-    <div v-else class="toc-empty">
-      <p class="text-caption text-center">No table of contents available</p>
-    </div>
-
     <!-- Fade gradient for overflow -->
     <div v-if="showFade" class="fade-gradient" />
   </div>
@@ -122,16 +126,6 @@ watch(() => props.tocItems, () => {
   scrollbar-width: none;
 }
 
-.toc-empty {
-  flex: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  padding: 32px 16px;
-  color: rgb(var(--v-theme-on-surface-rail));
-  opacity: 0.6;
-}
-
 .fade-gradient {
   position: absolute;
   bottom: 0;

package/mdsite-nuxt/app/composables/useFooter.ts

@@ -0,0 +1,46 @@
+import type { FooterLink } from '../../scripts/generate-indices'
+import { withBasePath } from '../../utils/base-url'
+
+/**
+ * Fetch and cache footer links from the pre-built JSON file.
+ * Uses useState to prevent duplicate fetches across component instances.
+ */
+export function useFooter() {
+  const appBaseURL = useRuntimeConfig().app.baseURL
+  const links = useState<FooterLink[] | null>('footer-links', () => null)
+  const isLoading = useState<boolean>('footer-links-loading', () => false)
+
+  /**
+   * Load footer links from the pre-built JSON file.
+   * Cached result prevents duplicate fetches.
+   */
+  async function loadFooter(): Promise<FooterLink[]> {
+    if (links.value !== null) {
+      return links.value
+    }
+
+    if (isLoading.value) {
+      return []
+    }
+
+    isLoading.value = true
+
+    try {
+      const data = await $fetch<FooterLink[]>(withBasePath('/_footer.json', appBaseURL))
+      links.value = data
+      return data
+    } catch (error) {
+      console.error('Error loading footer links:', error)
+      links.value = []
+      return []
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  return {
+    links,
+    isLoading,
+    loadFooter
+  }
+}

package/mdsite-nuxt/app/composables/useNavigationTree.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Unit tests for the navigation tree visibility helpers.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { countClickableMenuItems, shouldShowNavigation } from './useNavigationTree'
+import type { TreeNode } from './useNavigationTree'
+
+// Build a clickable link node. Defaults to no children.
+function link(id: string, path: string, children: TreeNode[] = []): TreeNode {
+  return { id, title: id, path, order: 0, children, parent: undefined, isPrimary: true }
+}
+
+function separator(id: string): TreeNode {
+  return { id, title: '---', path: '#', order: 0, children: [], isSeparator: true }
+}
+
+function header(id: string): TreeNode {
+  return { id, title: id, path: '#', order: 0, children: [], isHeader: true }
+}
+
+describe('useNavigationTree visibility', () => {
+  describe('countClickableMenuItems', () => {
+    it('returns 0 for an empty array', () => {
+      expect(countClickableMenuItems([])).toBe(0)
+    })
+
+    it('counts only non-separator, non-header top-level nodes', () => {
+      const nodes = [link('home', '/'), separator('sep-1'), header('hdr-1')]
+      expect(countClickableMenuItems(nodes)).toBe(1)
+    })
+
+    it('recursively counts children of submenus', () => {
+      const nodes = [
+        link('home', '/'),
+        link('docs', '/docs', [link('a', '/docs/a'), link('b', '/docs/b')])
+      ]
+      // home (1) + docs parent (1) + a (1) + b (1) = 4
+      expect(countClickableMenuItems(nodes)).toBe(4)
+    })
+
+    it('does not recurse into separators or headers', () => {
+      const nodes = [
+        link('home', '/'),
+        link('section', '/section', [link('child', '/section/child')])
+      ]
+      // home (1) + section (1) + child (1) = 3
+      expect(countClickableMenuItems(nodes)).toBe(3)
+    })
+  })
+
+  describe('shouldShowNavigation', () => {
+    it('returns false for an empty menu', () => {
+      expect(shouldShowNavigation([])).toBe(false)
+    })
+
+    it('returns false when there is only 1 clickable item', () => {
+      expect(shouldShowNavigation([link('home', '/')])).toBe(false)
+    })
+
+    it('returns true when there are 2+ clickable items at the top level', () => {
+      expect(shouldShowNavigation([
+        link('home', '/'),
+        link('about', '/about')
+      ])).toBe(true)
+    })
+
+    it('returns true when the only top-level item has multiple children', () => {
+      // One top-level folder with 2+ nested pages still needs a navigation sidebar
+      expect(shouldShowNavigation([
+        link('docs', '/docs', [
+          link('a', '/docs/a'),
+          link('b', '/docs/b')
+        ])
+      ])).toBe(true)
+    })
+  })
+})

package/mdsite-nuxt/app/composables/useNavigationTree.ts

@@ -27,6 +27,33 @@ function getCacheKey(): string {
   return `navigation-tree-${hourTimestamp}`
 }
 
+/**
+ * Recursively count the number of navigable (clickable) menu nodes.
+ * Excludes separators and headers. A parent link with children counts as
+ * one clickable node, plus all of its clickable descendants.
+ */
+export function countClickableMenuItems(nodes: TreeNode[]): number {
+  let count = 0
+  for (const node of nodes) {
+    if (!node.isSeparator && !node.isHeader) {
+      count++
+    }
+    if (node.children?.length) {
+      count += countClickableMenuItems(node.children)
+    }
+  }
+  return count
+}
+
+/**
+ * Decide whether the left navigation drawer should be shown.
+ * Shown only when there is more than one clickable menu item to render
+ * (recursive count across the entire menu tree).
+ */
+export function shouldShowNavigation(nodes: TreeNode[]): boolean {
+  return countClickableMenuItems(nodes) > 1
+}
+
 /**
  * Build hierarchical navigation tree from @nuxt/content collection
  */
@@ -117,9 +144,18 @@ export function useNavigationTree() {
     return node.parent.children.filter(child => child.path !== nodePath)
   }
 
+  /**
+   * Whether more than one clickable menu item exists in the tree.
+   * Used to gate the left navigation drawer and the hamburger toggle button.
+   */
+  const hasMultipleMenuItems = computed(() =>
+    tree.value !== null && shouldShowNavigation(tree.value.children)
+  )
+
   return {
     tree,
     isLoading,
+    hasMultipleMenuItems,
     loadTree,
     findNodeByPath,
     findPrimaryNodeByPath,

package/mdsite-nuxt/app/composables/useTableOfContents.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Unit tests for the TOC visibility thresholds.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { computeShouldShowTOC, TOC_MIN_HEADINGS, TOC_MIN_LINES } from './useTableOfContents'
+
+describe('useTableOfContents threshold', () => {
+  it('exposes the expected minimum constants', () => {
+    expect(TOC_MIN_HEADINGS).toBe(3)
+    expect(TOC_MIN_LINES).toBe(15)
+  })
+
+  describe('computeShouldShowTOC', () => {
+    it('returns false when headings < 3', () => {
+      expect(computeShouldShowTOC(0, 100)).toBe(false)
+      expect(computeShouldShowTOC(1, 100)).toBe(false)
+      expect(computeShouldShowTOC(2, 100)).toBe(false)
+    })
+
+    it('returns false when lines < 15 (and headings >= 3)', () => {
+      expect(computeShouldShowTOC(3, 0)).toBe(false)
+      expect(computeShouldShowTOC(5, 14)).toBe(false)
+    })
+
+    it('returns true when headings >= 3 and lines >= 15', () => {
+      expect(computeShouldShowTOC(3, 15)).toBe(true)
+      expect(computeShouldShowTOC(5, 100)).toBe(true)
+    })
+
+    it('returns true when headings >= 3 and lineCount is null (not yet measured)', () => {
+      expect(computeShouldShowTOC(3, null)).toBe(true)
+    })
+  })
+})

package/mdsite-nuxt/app/composables/useTableOfContents.ts

@@ -5,6 +5,23 @@ export interface TocItem {
   element?: HTMLElement
 }
 
+/** Minimum number of headings required to show the TOC. */
+export const TOC_MIN_HEADINGS = 3
+/** Minimum number of non-empty lines in the rendered content required to show the TOC. */
+export const TOC_MIN_LINES = 15
+
+/**
+ * Pure helper that decides whether the TOC should be shown.
+ * Returns true when the page has enough headings AND enough content lines.
+ * A null lineCount (not yet measured) is treated as "not too short" so the
+ * TOC is not hidden by the line threshold before measurement completes.
+ */
+export function computeShouldShowTOC(headingsCount: number, lineCount: number | null): boolean {
+  if (headingsCount < TOC_MIN_HEADINGS) return false
+  if (lineCount !== null && lineCount < TOC_MIN_LINES) return false
+  return true
+}
+
 /**
  * Generate and manage table of contents from page headings
  */
@@ -12,6 +29,7 @@ export function useTableOfContents() {
   const tocItems = ref<TocItem[]>([])
   const activeId = ref<string>('')
   const observer = ref<IntersectionObserver | null>(null)
+  const lineCount = ref<number | null>(null)
 
   /**
    * Generate TOC from a content container element
@@ -28,14 +46,23 @@ export function useTableOfContents() {
     }
 
     if (!container) {
+      // Reset line count when no container is provided so a stale value
+      // does not gate TOC visibility after the container is unmounted.
+      lineCount.value = null
       return
     }
 
+    // Measure line count of the rendered content (non-empty lines).
+    // Always update this even when there are too few headings so the value
+    // stays in sync with the latest rendered content.
+    const text = container.innerText || ''
+    lineCount.value = text.split('\n').filter(l => l.trim().length > 0).length
+
     // Find only H2 and H3 headings (skip H1 as it's the page title)
     const headings = container.querySelectorAll('article h2, article h3, .content-body h2, .content-body h3')
 
-    if (headings.length < 2) {
-      // Hide TOC if less than 2 headings
+    if (headings.length < TOC_MIN_HEADINGS) {
+      // Hide TOC if fewer than the minimum required headings
       tocItems.value = []
       return
     }
@@ -118,9 +145,9 @@ export function useTableOfContents() {
   }
 
   /**
-   * Check if TOC should be shown (2+ headings)
+   * Check if TOC should be shown based on heading count and content line count.
    */
-  const shouldShowTOC = computed(() => tocItems.value.length >= 2)
+  const shouldShowTOC = computed(() => computeShouldShowTOC(tocItems.value.length, lineCount.value))
 
   /**
    * Clean up observer on unmount
@@ -134,6 +161,7 @@ export function useTableOfContents() {
   return {
     tocItems,
     activeId,
+    lineCount,
     shouldShowTOC,
     generateTOC,
     scrollToHeading

package/mdsite-nuxt/app/layouts/default.vue

@@ -11,6 +11,7 @@
       <div class="desktop-layout">
         <!-- Left Sidebar (Navigation) -->
         <v-navigation-drawer
+          v-if="hasMultipleMenuItems"
           v-model="sidebarsVisible"
           :permanent="!isPrinting"
           absolute
@@ -61,6 +62,7 @@
     <div v-else class="mobile-layout">
       <!-- Mobile Drawer -->
       <v-navigation-drawer
+        v-if="hasMultipleMenuItems"
         v-model="drawerOpen"
         temporary
         location="left"
@@ -118,6 +120,7 @@
 
 <script setup lang="ts">
 import { useTableOfContents } from '~/composables/useTableOfContents'
+import { useNavigationTree } from '~/composables/useNavigationTree'
 
 const { mdAndUp } = useDisplay()
 const route = useRoute()
@@ -127,6 +130,13 @@ const desktopContentContainer = ref<HTMLElement>()
 const mobileContentContainer = ref<HTMLElement>()
 const { tocItems, activeId: activeHeadingId, shouldShowTOC, generateTOC } = useTableOfContents()
 
+// Navigation state - gates the left drawer and hamburger toggle button.
+// loadTree() is invoked eagerly from the layout so the tree is populated even
+// when the drawer (which would normally host the only other call site) is
+// hidden due to a small menu. Without this, hasMultipleMenuItems stays false
+// forever and the menu never appears.
+const { hasMultipleMenuItems, loadTree } = useNavigationTree()
+
 // Provide TOC generation function to child pages
 provide('generateTOC', () => {
   const container = mdAndUp.value ? desktopContentContainer.value : mobileContentContainer.value
@@ -197,6 +207,11 @@ const onAfterPrint = () => {
 }
 
 onMounted(() => {
+  // Eagerly load the navigation tree so hasMultipleMenuItems can reactively
+  // flip to true once data arrives, even when the menu drawer is initially
+  // hidden because the tree is still empty.
+  loadTree()
+
   if (import.meta.client) {
     window.addEventListener('beforeprint', onBeforePrint)
     window.addEventListener('afterprint', onAfterPrint)

package/mdsite-nuxt/nuxt.config.ts

@@ -18,7 +18,25 @@ export default defineNuxtConfig({
     public: {
       contentDomain: path.basename(mdsite.contentDir),
       contentPath: mdsite.contentDir,
-      siteConfig
+      // `mdsite.config` is a valid `MdsiteConfig` at runtime, but
+      // Nuxt's runtime-config type generator collapses every complex
+      // field of `siteConfig` to a degenerate shape — `menu` becomes
+      // `Array<{}>` (regardless of whether the source type is recursive
+      // or contains `Array<any>`) and `footer` becomes `Array<any>`.
+      // We verified this by:
+      //   1. Tightening `MdsiteConfig.menu` to a proper recursive
+      //      `MdsiteMenuItem` (no `any`) and clearing `.nuxt` cache:
+      //      the generated `menu` was still `Array<{}>`.
+      //   2. Trying `declare module 'nuxt/schema'` augmentations of
+      //      `PublicRuntimeConfig.siteConfig`: the augmentation
+      //      *intersects* with the broken generated type rather than
+      //      overriding it, producing an even narrower target.
+      // Since the runtime value is unchanged, `as any` is the most
+      // honest pragmatic escape hatch. The recursive `MdsiteMenuItem`
+      // type is still useful: it gives the rest of the codebase
+      // (notably `scripts/generate-indices.ts`) a single source of
+      // truth and proper types.
+      siteConfig: siteConfig as any
     }
   },
 

package/mdsite-nuxt/scripts/generate-indices.test.ts

@@ -4,7 +4,7 @@ import path from 'node:path'
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
-import { generateNavigationJson, generateSearchIndexJson } from './generate-indices.js'
+import { generateNavigationJson, generateSearchIndexJson, generateFooterJson } from './generate-indices.js'
 
 describe('generated content indices', () => {
   const originalEnv = { ...process.env }
@@ -234,4 +234,111 @@ describe('generated content indices', () => {
       ])
     })
   })
+
+  describe('mdsite.yml footer lookup', () => {
+    async function readFooter() {
+      return JSON.parse(await fs.readFile(path.join(publicDir, '_footer.json'), 'utf8'))
+    }
+
+    async function readNavigation() {
+      return JSON.parse(await fs.readFile(path.join(publicDir, '_navigation.json'), 'utf8'))
+    }
+
+    it('generates _footer.json with paths and titles from mdsite.yml footer section', async () => {
+      await fs.writeFile(path.join(contentDir, 'index.md'), '# Home\n\nWelcome home.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'about.md'), '# About\n\nAbout us.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'contacts.md'), '# Contacts\n\nContact us.', 'utf8')
+
+      const mdsitePath = path.join(tempDir, 'mdsite.yml')
+      await fs.writeFile(mdsitePath, [
+        'site:',
+        '  name: Test Site',
+        'footer:',
+        '  - about',
+        '  - contacts',
+        '',
+      ].join('\n'), 'utf8')
+      process.env.MDSITE_CONFIG_PATH = mdsitePath
+
+      await generateFooterJson()
+
+      const footer = await readFooter()
+      expect(footer).toEqual([
+        { path: '/about', title: 'About' },
+        { path: '/contacts', title: 'Contacts' },
+      ])
+    })
+
+    it('returns an empty footer array when no footer section is configured', async () => {
+      await fs.writeFile(path.join(contentDir, 'index.md'), '# Home\n\nWelcome.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'mdsite.yml'), [
+        'site:',
+        '  name: Test Site',
+        '',
+      ].join('\n'), 'utf8')
+      process.env.MDSITE_CONFIG_PATH = path.join(contentDir, 'mdsite.yml')
+
+      await generateFooterJson()
+
+      const footer = await readFooter()
+      expect(footer).toEqual([])
+    })
+
+    it('excludes footer entries from the navigation tree', async () => {
+      await fs.writeFile(path.join(contentDir, 'index.md'), '# Home\n\nWelcome home.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'guide.md'), '# Guide\n\nUseful guide.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'about.md'), '# About\n\nAbout us.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'contacts.md'), '# Contacts\n\nContact us.', 'utf8')
+
+      const mdsitePath = path.join(tempDir, 'mdsite.yml')
+      await fs.writeFile(mdsitePath, [
+        'site:',
+        '  name: Test Site',
+        'menu:',
+        '  - index',
+        '  - guide',
+        'footer:',
+        '  - contacts',
+        '',
+      ].join('\n'), 'utf8')
+      process.env.MDSITE_CONFIG_PATH = mdsitePath
+
+      await generateNavigationJson()
+      await generateFooterJson()
+
+      const navigation = await readNavigation()
+      const paths = navigation.map((n: { path: string }) => n.path)
+      expect(paths).toContain('/')
+      expect(paths).toContain('/guide')
+      expect(paths).not.toContain('/contacts')
+
+      const footer = await readFooter()
+      expect(footer).toEqual([
+        { path: '/contacts', title: 'Contacts' },
+      ])
+    })
+
+    it('excludes footer entries from the fallback navigation tree', async () => {
+      await fs.writeFile(path.join(contentDir, 'index.md'), '# Home\n\nWelcome home.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'about.md'), '# About\n\nAbout us.', 'utf8')
+      await fs.writeFile(path.join(contentDir, 'contacts.md'), '# Contacts\n\nContact us.', 'utf8')
+
+      const mdsitePath = path.join(tempDir, 'mdsite.yml')
+      await fs.writeFile(mdsitePath, [
+        'site:',
+        '  name: Test Site',
+        'footer: [contacts]',
+        '',
+      ].join('\n'), 'utf8')
+      delete process.env.MDSITE_CONFIG_PATH
+
+      await generateNavigationJson()
+
+      const navigation = await readNavigation()
+      const paths = navigation.map((n: { path: string }) => n.path)
+      expect(paths).toContain('/')
+      expect(paths).toContain('/about')
+      expect(paths).not.toContain('/contacts')
+    })
+  })
 })