@life-and-dev/mdsite 0.4.0 → 0.5.1

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

@@ -4,6 +4,7 @@ import fs from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { parse as parseYaml } from 'yaml'
+import type { MdsiteMenuItem } from '../utils/mdsite-config'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -108,8 +109,10 @@ export interface MinimalTreeNode {
     isPrimary?: boolean
 }
 
-type MenuItemType = string | { [key: string]: string | null | MenuItemType[] } | null
-
+// `MdsiteMenuItem` is imported from `~/utils/mdsite-config` (see top of file).
+// It is the same recursive shape that was previously defined locally as
+// `MdsiteMenuItem`. Single source of truth lives in `utils/mdsite-config.ts`
+// so the Nuxt runtime-config type generator can infer it correctly.
 /**
  * Normalize URL path so a trailing /index resolves to its parent.
  * Mirrors filePathToUrlPath behavior so menu paths match content routes.
@@ -161,7 +164,7 @@ function resolvePath(menuPath: string, contextPath: string): string {
  * Process menu items recursively and build minimal tree structure
  */
 async function processMenuItems(
-    items: MenuItemType[],
+    items: MdsiteMenuItem[],
     contextPath: string,
     order: number = 0
 ): Promise<{ nodes: MinimalTreeNode[], nextOrder: number }> {
@@ -371,14 +374,14 @@ async function buildFallbackNavigationTree(sourceDir: string): Promise<MinimalTr
  * Load the menu array from a candidate config file (legacy _menu.yml/yaml or mdsite.yml).
  * Returns null if the file is missing, unreadable, has no menu key, or has an empty menu.
  */
-async function tryReadMenuFromConfig(configPath: string): Promise<MenuItemType[] | null> {
+async function tryReadMenuFromConfig(configPath: string): Promise<MdsiteMenuItem[] | null> {
     if (!await fs.pathExists(configPath)) {
         return null
     }
 
     try {
         const content = await fs.readFile(configPath, 'utf-8')
-        const parsed = parseYaml(content) as { menu?: MenuItemType[] } | null
+        const parsed = parseYaml(content) as { menu?: MdsiteMenuItem[] } | null
         if (parsed && Array.isArray(parsed.menu) && parsed.menu.length > 0) {
             return parsed.menu
         }
@@ -393,14 +396,14 @@ async function tryReadMenuFromConfig(configPath: string): Promise<MenuItemType[]
  * Try to read menu items from a plain (non-wrapped) legacy _menu.yml/yaml file.
  * Returns null if the file is missing, unreadable, or doesn't contain a non-empty array.
  */
-async function tryReadLegacyMenuFile(menuPath: string): Promise<MenuItemType[] | null> {
+async function tryReadLegacyMenuFile(menuPath: string): Promise<MdsiteMenuItem[] | null> {
     if (!await fs.pathExists(menuPath)) {
         return null
     }
 
     try {
         const content = await fs.readFile(menuPath, 'utf-8')
-        const parsed = parseYaml(content) as MenuItemType[] | null
+        const parsed = parseYaml(content) as MdsiteMenuItem[] | null
         if (Array.isArray(parsed) && parsed.length > 0) {
             return parsed
         }
@@ -420,7 +423,7 @@ async function tryReadLegacyMenuFile(menuPath: string): Promise<MenuItemType[] |
  *   5. <sourceDir>/mdsite.yml
  * Returns the first non-empty menu array, or null if none resolve to a menu.
  */
-async function loadMenuConfig(sourceDir: string): Promise<MenuItemType[] | null> {
+async function loadMenuConfig(sourceDir: string): Promise<MdsiteMenuItem[] | null> {
     const candidates: { path: string, isLegacy: boolean }[] = [
         { path: path.join(sourceDir, '_menu.yml'), isLegacy: true },
         { path: path.join(sourceDir, '_menu.yaml'), isLegacy: true }
@@ -445,6 +448,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 +629,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 +786,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

@@ -2,6 +2,30 @@ import fs from 'fs';
 import path from 'path';
 import YAML from 'yaml';
 
+/**
+ * Recursive shape of a single `mdsite.yml` `menu:` entry.
+ *
+ * - `string`        → flat link to a markdown slug
+ *                     (e.g. `- genesis`, `- resurrections`)
+ * - `null`          → visual separator (`===` in YAML)
+ * - `Record<string, MdsiteMenuValue>` → group: object whose keys are group
+ *                     labels (e.g. `"Members of the Trinity":`) and whose
+ *                     values are `MdsiteMenuValue` items
+ * - `MdsiteMenuValue` (the value side of a group) can be:
+ *     - `string`         → alias link with custom title
+ *                          (e.g. `"Job": https://...`, `"Homepage": index`)
+ *     - `null`           → group label only (renders as a heading, no link)
+ *     - `MdsiteMenuItem[]` → nested submenu (recursive)
+ *
+ * Keeping this a `type` alias (not an `interface`) and avoiding `any` lets
+ * Nuxt's runtime-config type generator infer `runtimeConfig.public.siteConfig`
+ * without collapsing `menu` to `{}[]`. See `nuxt.config.ts` for the cast
+ * history this replaces.
+ */
+export type MdsiteMenuItem = string | null | MdsiteMenuGroup
+export type MdsiteMenuGroup = { [key: string]: MdsiteMenuValue }
+export type MdsiteMenuValue = string | null | MdsiteMenuItem[]
+
 export interface MdsiteConfig {
   content?: {
     path?: string
@@ -11,7 +35,8 @@ export interface MdsiteConfig {
     bibleTooltips: boolean
     sourceEdit: boolean
   }
-  menu: Array<string | null | Record<string, string | null | Array<any>>>
+  menu: MdsiteMenuItem[]
+  footer: string[]
   server: {
     output: string
     path: string
@@ -201,6 +226,7 @@ function createDefaultMdsiteConfig(siteName: string): MdsiteConfig {
       sourceEdit: true
     },
     menu: [],
+    footer: [],
     server: {
       output: '.output',
       path: '.mdsite',
@@ -233,6 +259,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.4.0",
+  "version": "0.5.1",
   "type": "module",
   "private": false,
   "description": "Local-first CLI that orchestrates mdsite-nuxt",