@life-and-dev/mdsite 0.3.1 → 0.5.0

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(40)
+  })
+
+  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 < 40 (and headings >= 3)', () => {
+      expect(computeShouldShowTOC(3, 0)).toBe(false)
+      expect(computeShouldShowTOC(5, 39)).toBe(false)
+    })
+
+    it('returns true when headings >= 3 and lines >= 40', () => {
+      expect(computeShouldShowTOC(3, 40)).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 = 40
+
+/**
+ * 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/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')
+    })
+  })
 })

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

@@ -445,6 +445,166 @@ async function loadMenuConfig(sourceDir: string): Promise<MenuItemType[] | null>
     return null
 }
 
+// ----------------------------------------------------------------------------
+// FOOTER LOGIC
+// ----------------------------------------------------------------------------
+
+export interface FooterLink {
+    path: string
+    title: string
+}
+
+/**
+ * Read the footer array from a candidate mdsite.yml config file.
+ * Returns null when the file is missing, unreadable, or has no footer key.
+ */
+async function tryReadFooterFromConfig(configPath: string): Promise<string[] | null> {
+    if (!await fs.pathExists(configPath)) {
+        return null
+    }
+
+    try {
+        const content = await fs.readFile(configPath, 'utf-8')
+        const parsed = parseYaml(content) as { footer?: unknown } | null
+        if (parsed && Array.isArray(parsed.footer) && parsed.footer.length > 0) {
+            return parsed.footer.filter((item): item is string => typeof item === 'string')
+        }
+    } catch (e) {
+        // Ignore parse errors - they shouldn't abort the whole lookup chain
+    }
+
+    return null
+}
+
+/**
+ * Layered footer lookup. Tries, in order:
+ *   1. MDSITE_CONFIG_PATH env var
+ *   2. <sourceDir>/../mdsite.yml
+ *   3. <sourceDir>/mdsite.yml
+ * Returns the first non-empty footer array, or null if none resolve.
+ */
+async function loadFooterConfig(sourceDir: string): Promise<string[] | null> {
+    const candidates: string[] = []
+    if (process.env.MDSITE_CONFIG_PATH) {
+        candidates.push(process.env.MDSITE_CONFIG_PATH)
+    }
+    candidates.push(path.join(sourceDir, '..', 'mdsite.yml'))
+    candidates.push(path.join(sourceDir, 'mdsite.yml'))
+
+    for (const candidate of candidates) {
+        const footer = await tryReadFooterFromConfig(candidate)
+        if (footer) {
+            return footer
+        }
+    }
+
+    return null
+}
+
+/**
+ * Resolve a raw footer entry to its normalized URL path. Returns null when the
+ * path is empty after resolution.
+ */
+function resolveFooterPath(item: string): string | null {
+    const resolvedPath = resolvePath(item, '/')
+    if (!resolvedPath || resolvedPath === '/') {
+        return null
+    }
+    return normalizeIndexPath(resolvedPath)
+}
+
+/**
+ * Process footer items into a flat list of { path, title } links.
+ * Title falls back to the raw entry when the markdown file is missing or has no H1.
+ */
+async function processFooterItems(items: string[]): Promise<FooterLink[]> {
+    const links: FooterLink[] = []
+
+    for (const item of items) {
+        const normalizedPath = resolveFooterPath(item)
+        if (!normalizedPath) {
+            continue
+        }
+
+        const markdownPath = getMarkdownPath(normalizedPath)
+        let title: string | null = null
+
+        try {
+            if (await fs.pathExists(markdownPath)) {
+                const content = await fs.readFile(markdownPath, 'utf-8')
+                const metadata = extractMarkdownMetadata(content)
+                title = metadata.title
+            }
+        } catch (e) {
+            // Ignore missing files
+        }
+
+        links.push({
+            path: normalizedPath,
+            title: title || item
+        })
+    }
+
+    return links
+}
+
+/**
+ * Build the set of normalized footer paths used to exclude entries from the nav tree.
+ * Returns an empty set when no footer section is configured.
+ */
+async function getFooterExcludedPaths(sourceDir: string): Promise<Set<string>> {
+    const items = await loadFooterConfig(sourceDir)
+    if (!items) {
+        return new Set()
+    }
+
+    const excluded = new Set<string>()
+    for (const item of items) {
+        const normalizedPath = resolveFooterPath(item)
+        if (normalizedPath) {
+            excluded.add(normalizedPath)
+        }
+    }
+    return excluded
+}
+
+/**
+ * Recursively drop any node whose path matches the excluded set. Subtree children
+ * of a dropped node are removed along with the parent.
+ */
+function filterTreeByExcludedPaths(nodes: MinimalTreeNode[], excluded: Set<string>): MinimalTreeNode[] {
+    return nodes
+        .filter(node => !excluded.has(node.path))
+        .map(node => ({
+            ...node,
+            children: node.children ? filterTreeByExcludedPaths(node.children, excluded) : undefined
+        }))
+}
+
+/**
+ * Generate footer links JSON file
+ */
+export async function generateFooterJson() {
+    const domain = getContentDomain()
+    console.log(`📎 Building footer links for: ${domain}`)
+
+    const sourceDir = getSourceDir()
+    const items = await loadFooterConfig(sourceDir)
+    const links = items ? await processFooterItems(items) : []
+
+    const targetDir = getTargetDir()
+    const outputPath = path.join(targetDir, '_footer.json')
+
+    await fs.ensureDir(targetDir)
+    await fs.writeJson(outputPath, links, { spaces: 2 })
+
+    const fileSize = (await fs.stat(outputPath)).size
+    const fileSizeKB = (fileSize / 1024).toFixed(2)
+
+    console.log(`✓ Footer links generated: ${outputPath} (${fileSizeKB} KB)`)
+    console.log(`✓ Total footer links: ${links.length}\n`)
+}
+
 /**
  * Generate navigation JSON file
  */
@@ -466,8 +626,17 @@ export async function generateNavigationJson() {
         console.error('Error building navigation tree:', error)
     }
 
+    // Deduplicate footer entries from the menu tree (if any footer section is configured)
+    const excludedPaths = await getFooterExcludedPaths(sourceDir)
+    if (excludedPaths.size > 0) {
+        tree = filterTreeByExcludedPaths(tree, excludedPaths)
+    }
+
     if (tree.length === 0) {
         tree = await buildFallbackNavigationTree(sourceDir)
+        if (excludedPaths.size > 0) {
+            tree = filterTreeByExcludedPaths(tree, excludedPaths)
+        }
     }
 
     const targetDir = getTargetDir()
@@ -614,6 +783,7 @@ export async function generateSearchIndexJson() {
 export async function buildContentData() {
     await generateNavigationJson()
     await generateSearchIndexJson()
+    await generateFooterJson()
 }
 
 // Run if called directly

package/mdsite-nuxt/scripts/renderer-hooks.ts

@@ -122,6 +122,7 @@ function ensureLegacyCompatibilityConfig(rootDir: string): string | undefined {
       sourceEdit: legacyConfig.features?.sourceEdit ?? true
     },
     menu: [],
+    footer: [],
     server: {
       output: '.output',
       path: '.mdsite',

package/mdsite-nuxt/scripts/sync-content.ts

@@ -22,6 +22,7 @@ const STATIC_FILES = [
 // Debounce timers for JSON regeneration (5 second delay)
 let navigationDebounceTimer: NodeJS.Timeout | null = null
 let searchDebounceTimer: NodeJS.Timeout | null = null
+let footerDebounceTimer: NodeJS.Timeout | null = null
 
 /**
  * Get content domain from environment variable (read at runtime, not import time)
@@ -87,6 +88,26 @@ function regenerateSearchIndex() {
     }, 5000)
 }
 
+/**
+ * Regenerate footer links JSON with debouncing (5 second delay)
+ */
+function regenerateFooter() {
+    if (footerDebounceTimer) {
+        clearTimeout(footerDebounceTimer)
+    }
+
+    footerDebounceTimer = setTimeout(async () => {
+        console.log('🔄 Regenerating footer links...')
+        try {
+            const { generateFooterJson } = await import('./generate-indices.js')
+            await generateFooterJson()
+        } catch (error) {
+            console.error('❌ Failed to regenerate footer links:', error)
+        }
+        footerDebounceTimer = null
+    }, 5000)
+}
+
 /**
  * Generate navigation and search JSON files (one-time on startup)
  */
@@ -106,6 +127,13 @@ export async function generateJsonFiles() {
     } catch (error) {
         console.error('❌ Failed to generate search index:', error)
     }
+
+    try {
+        const { generateFooterJson } = await import('./generate-indices.js')
+        await generateFooterJson()
+    } catch (error) {
+        console.error('❌ Failed to generate footer links:', error)
+    }
 }
 
 /**
@@ -198,6 +226,7 @@ export async function startWatcher() {
                 console.log(`📝 Markdown added: ${fileName}`)
                 regenerateNavigation()
                 regenerateSearchIndex()
+                regenerateFooter()
             } else {
                 copyImage(filePath, true, 'added')
             }
@@ -209,6 +238,7 @@ export async function startWatcher() {
                 console.log(`📝 Markdown updated: ${fileName}`)
                 regenerateNavigation()
                 regenerateSearchIndex()
+                regenerateFooter()
             } else {
                 copyImage(filePath, true, 'updated')
             }
@@ -220,6 +250,7 @@ export async function startWatcher() {
                 console.log(`📝 Markdown deleted: ${fileName}`)
                 regenerateNavigation()
                 regenerateSearchIndex()
+                regenerateFooter()
             } else {
                 deleteImage(filePath)
             }

package/mdsite-nuxt/utils/mdsite-config.ts

@@ -12,6 +12,7 @@ export interface MdsiteConfig {
     sourceEdit: boolean
   }
   menu: Array<string | null | Record<string, string | null | Array<any>>>
+  footer: string[]
   server: {
     output: string
     path: string
@@ -201,6 +202,7 @@ function createDefaultMdsiteConfig(siteName: string): MdsiteConfig {
       sourceEdit: true
     },
     menu: [],
+    footer: [],
     server: {
       output: '.output',
       path: '.mdsite',
@@ -233,6 +235,7 @@ function normalizeMdsiteConfig(rawConfig: Record<string, any>, contentDir: strin
     },
     content: contentPath ? { path: contentPath } : fallbackConfig.content,
     menu: Array.isArray(rawConfig.menu) ? rawConfig.menu : fallbackConfig.menu,
+    footer: Array.isArray(rawConfig.footer) ? rawConfig.footer.filter((item): item is string => typeof item === 'string') : [],
     server: {
       output: typeof rawConfig.server?.output === 'string' ? rawConfig.server.output : fallbackConfig.server.output,
       path: typeof rawConfig.server?.path === 'string' ? rawConfig.server.path : fallbackConfig.server.path,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@life-and-dev/mdsite",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "private": false,
   "description": "Local-first CLI that orchestrates mdsite-nuxt",