@life-and-dev/mdsite 0.6.0 → 0.7.1

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

@@ -4,7 +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'
+import type { MdsiteFooterItem, MdsiteMenuItem } from '../utils/mdsite-config'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -452,25 +452,60 @@ async function loadMenuConfig(sourceDir: string): Promise<MdsiteMenuItem[] | nul
 // FOOTER LOGIC
 // ----------------------------------------------------------------------------
 
+/**
+ * Runtime-validated footer entry. `null` is rendered as a vertical separator
+ * in the bar; external URLs keep their raw `path` and render in a new tab;
+ * internal links use the normalized path with the H1 title (or custom title).
+ */
 export interface FooterLink {
     path: string
     title: string
+    type: 'link' | 'separator'
+    isExternal: boolean
+}
+
+/**
+ * Same filter the CLI uses, but expressed against `MdsiteFooterItem`. Keeps
+ * CLI and renderer parsers in lockstep so both drop malformed entries the
+ * same way.
+ */
+function isValidFooterItem(item: unknown): item is MdsiteFooterItem {
+    if (item === null) return true
+    if (typeof item === 'string') return item.trim().length > 0
+    if (typeof item === 'object') {
+        const keys = Object.keys(item as Record<string, unknown>)
+        if (keys.length !== 1) return false
+        const value = (item as Record<string, unknown>)[keys[0]]
+        return value === null || typeof value === 'string'
+    }
+    return false
+}
+
+/**
+ * True when the string is an absolute http(s) URL. Used to keep external
+ * links out of the menu-exclusion set (no markdown file to exclude) and to
+ * open them in a new tab in the footer.
+ */
+function isExternalUrl(value: string): boolean {
+    return value.startsWith('http://') || value.startsWith('https://')
 }
 
 /**
  * Read the footer array from a candidate mdsite.yml config file.
  * Returns null when the file is missing, unreadable, or has no footer key.
+ * Footer lives under `features.footer` in mdsite.yml.
  */
-async function tryReadFooterFromConfig(configPath: string): Promise<string[] | null> {
+async function tryReadFooterFromConfig(configPath: string): Promise<MdsiteFooterItem[] | 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')
+        const parsed = parseYaml(content) as { features?: { footer?: unknown } } | null
+        const footerItems = parsed?.features?.footer
+        if (parsed && Array.isArray(footerItems) && footerItems.length > 0) {
+            return footerItems.filter(isValidFooterItem)
         }
     } catch (e) {
         // Ignore parse errors - they shouldn't abort the whole lookup chain
@@ -486,7 +521,7 @@ async function tryReadFooterFromConfig(configPath: string): Promise<string[] | n
  *   3. <sourceDir>/mdsite.yml
  * Returns the first non-empty footer array, or null if none resolve.
  */
-async function loadFooterConfig(sourceDir: string): Promise<string[] | null> {
+async function loadFooterConfig(sourceDir: string): Promise<MdsiteFooterItem[] | null> {
     const candidates: string[] = []
     if (process.env.MDSITE_CONFIG_PATH) {
         candidates.push(process.env.MDSITE_CONFIG_PATH)
@@ -505,10 +540,13 @@ async function loadFooterConfig(sourceDir: string): Promise<string[] | null> {
 }
 
 /**
- * Resolve a raw footer entry to its normalized URL path. Returns null when the
- * path is empty after resolution.
+ * Resolve a raw footer entry to its normalized URL path. Returns null when
+ * the path is empty after resolution or when the entry is not a usable string.
  */
 function resolveFooterPath(item: string): string | null {
+    if (isExternalUrl(item)) {
+        return null
+    }
     const resolvedPath = resolvePath(item, '/')
     if (!resolvedPath || resolvedPath === '/') {
         return null
@@ -517,34 +555,112 @@ function resolveFooterPath(item: string): string | null {
 }
 
 /**
- * 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.
+ * Pull the normalized internal path out of a footer item, if any. Returns
+ * null for external URLs and `null`/empty items so they never get added to
+ * the menu-exclusion set.
+ */
+function extractInternalPath(item: MdsiteFooterItem): string | null {
+    if (typeof item === 'string') {
+        return resolveFooterPath(item)
+    }
+    if (item && typeof item === 'object') {
+        const keys = Object.keys(item)
+        if (keys.length === 1) {
+            const value = item[keys[0]]
+            if (typeof value === 'string') {
+                return resolveFooterPath(value)
+            }
+        }
+    }
+    return null
+}
+
+/**
+ * Process footer items into a flat list of FooterLink entries. Supports:
+ *   - `null` → separator
+ *   - string (file name) → internal link, title from H1
+ *   - `{ title: path }` → internal link with custom title
+ *   - `{ title: https://... }` → external link, opens in a new tab
+ * Title falls back to the raw entry / key when the markdown file is missing
+ * or has no H1.
  */
-async function processFooterItems(items: string[]): Promise<FooterLink[]> {
+async function processFooterItems(items: MdsiteFooterItem[]): Promise<FooterLink[]> {
     const links: FooterLink[] = []
 
     for (const item of items) {
-        const normalizedPath = resolveFooterPath(item)
-        if (!normalizedPath) {
+        if (item === null) {
+            links.push({
+                path: '',
+                title: '',
+                type: 'separator',
+                isExternal: false
+            })
             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
+        if (typeof item === 'string') {
+            const normalizedPath = resolveFooterPath(item)
+            if (!normalizedPath) {
+                continue
             }
-        } catch (e) {
-            // Ignore missing files
+            const title = await readH1Title(normalizedPath) ?? item
+            links.push({
+                path: normalizedPath,
+                title,
+                type: 'link',
+                isExternal: false
+            })
+            continue
         }
 
+        // Object form: { title: path-or-url }
+        const keys = Object.keys(item)
+        if (keys.length !== 1) continue
+        const displayTitle = keys[0]
+        const value = item[displayTitle]
+
+        if (value === null) {
+            links.push({
+                path: '',
+                title: displayTitle,
+                type: 'separator',
+                isExternal: false
+            })
+            continue
+        }
+
+        if (typeof value !== 'string') continue
+
+        if (isExternalUrl(value)) {
+            links.push({
+                path: value,
+                title: displayTitle,
+                type: 'link',
+                isExternal: true
+            })
+            continue
+        }
+
+        const normalizedPath = resolveFooterPath(value)
+        if (!normalizedPath) {
+            // Custom title pointing at a non-existent page — still render it
+            // using the raw value as the title so the user sees their label.
+            links.push({
+                path: value,
+                title: displayTitle,
+                type: 'link',
+                isExternal: false
+            })
+            continue
+        }
+
+        // Object form always wins for the title, mirroring how the `menu`
+        // parser treats custom labels as overrides of the file's H1.
         links.push({
             path: normalizedPath,
-            title: title || item
+            title: displayTitle,
+            type: 'link',
+            isExternal: false
         })
     }
 
@@ -552,8 +668,26 @@ async function processFooterItems(items: string[]): Promise<FooterLink[]> {
 }
 
 /**
- * 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.
+ * Read the H1 from a markdown file at the given normalized path. Returns
+ * null when the file is missing or has no H1 heading.
+ */
+async function readH1Title(normalizedPath: string): Promise<string | null> {
+    const markdownPath = getMarkdownPath(normalizedPath)
+    try {
+        if (await fs.pathExists(markdownPath)) {
+            const content = await fs.readFile(markdownPath, 'utf-8')
+            const metadata = extractMarkdownMetadata(content)
+            return metadata.title
+        }
+    } catch (e) {
+        // Ignore missing files
+    }
+    return null
+}
+
+/**
+ * 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)
@@ -563,7 +697,7 @@ async function getFooterExcludedPaths(sourceDir: string): Promise<Set<string>> {
 
     const excluded = new Set<string>()
     for (const item of items) {
-        const normalizedPath = resolveFooterPath(item)
+        const normalizedPath = extractInternalPath(item)
         if (normalizedPath) {
             excluded.add(normalizedPath)
         }
@@ -702,7 +836,29 @@ function filePathToUrlPath(filePath: string, sourceDir: string): string {
 }
 
 /**
- * Get all markdown files recursively
+ * Directory names that are never user-authored content. The recursive
+ * markdown walker skips these so a content directory that happens to be
+ * the project root (i.e. `mdsite.yml` lives at the repo root and
+ * `paths.input` is unset) does not crawl into the renderer working dir
+ * (`.mdsite/`), its `node_modules`, or other build/dependency artifacts.
+ *
+ * The rule is broad on purpose: any directory whose name starts with `.`
+ * (hidden dirs like `.git`, `.mdsite`, `.nuxt`, `.vscode`, `.idea`,
+ * `.history`, `.data`, `.output`, …) plus the two non-hidden directories
+ * that are always tooling artifacts (`node_modules`, `dist`). Keeping the
+ * list narrow would require enumerating every CI/editor/build tool that
+ * might leave a hidden directory next to the content.
+ *
+ * Keep this in sync with the Nuxt Content collection `exclude` list in
+ * `content.config.ts` — both are the same safety net at two layers.
+ */
+function isExcludedSourceDir(name: string): boolean {
+    return name.startsWith('.') || name === 'node_modules' || name === 'dist'
+}
+
+/**
+ * Get all markdown files recursively, skipping build/dependency directories
+ * (see `isExcludedSourceDir`).
  */
 async function getAllMarkdownFiles(dir: string): Promise<string[]> {
     const files: string[] = []
@@ -718,6 +874,9 @@ async function getAllMarkdownFiles(dir: string): Promise<string[]> {
         const stat = await fs.stat(itemPath)
 
         if (stat.isDirectory()) {
+            if (isExcludedSourceDir(item)) {
+                continue
+            }
             const subFiles = await getAllMarkdownFiles(itemPath)
             files.push(...subFiles)
         } else if (item.endsWith('.md') && !item.endsWith('.draft.md')) {

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

@@ -8,51 +8,31 @@ const {
   generateFaviconsMock,
   generateWebManifestMock,
   loadMdsiteConfigSyncMock,
-  parseYamlMock,
-  readFileSyncMock,
   resolveMdsiteConfigPathMock,
   rmMock,
   startWatcherMock,
-  statSyncMock,
-  stringifyYamlMock,
   syncContentMock,
-  writeFileSyncMock,
 } = vi.hoisted(() => ({
   buildContentDataMock: vi.fn(),
   existsSyncMock: vi.fn(),
   generateFaviconsMock: vi.fn(),
   generateWebManifestMock: vi.fn(),
   loadMdsiteConfigSyncMock: vi.fn(),
-  parseYamlMock: vi.fn(),
-  readFileSyncMock: vi.fn(),
   resolveMdsiteConfigPathMock: vi.fn(),
   rmMock: vi.fn(),
   startWatcherMock: vi.fn(),
-  statSyncMock: vi.fn(),
-  stringifyYamlMock: vi.fn(),
   syncContentMock: vi.fn(),
-  writeFileSyncMock: vi.fn(),
 }))
 
 vi.mock('fs', () => ({
   default: {
     existsSync: existsSyncMock,
-    statSync: statSyncMock,
-    readFileSync: readFileSyncMock,
-    writeFileSync: writeFileSyncMock,
     promises: {
       rm: rmMock,
     },
   },
 }))
 
-vi.mock('yaml', () => ({
-  default: {
-    parse: parseYamlMock,
-    stringify: stringifyYamlMock,
-  },
-}))
-
 vi.mock('./generate-indices.js', () => ({
   buildContentData: buildContentDataMock,
 }))
@@ -105,8 +85,6 @@ describe('renderer hooks orchestration', () => {
       contentDir: '/renderer/docs',
     })
     existsSyncMock.mockImplementation((target: string) => target === '/renderer/docs')
-    statSyncMock.mockReturnValue({ isFile: () => true })
-    stringifyYamlMock.mockReturnValue('compat-config')
     generateFaviconsMock.mockResolvedValue(true)
     buildContentDataMock.mockResolvedValue(undefined)
     generateWebManifestMock.mockResolvedValue(undefined)
@@ -146,70 +124,6 @@ describe('renderer hooks orchestration', () => {
     expect(process.env.MDSITE_CONFIG_PATH).toBe('/renderer/mdsite.yml')
   })
 
-  it('falls back to the legacy compatibility config when no explicit mdsite config resolves', () => {
-    resolveMdsiteConfigPathMock.mockReturnValue(undefined)
-    existsSyncMock.mockImplementation((target: string) => (
-      target === '/renderer/content.config.yml' || target === path.join('/renderer', 'legacy-docs')
-    ))
-    parseYamlMock.mockReturnValue({
-      content: {
-        path: 'legacy-docs',
-      },
-      siteName: 'Legacy Docs',
-    })
-    loadMdsiteConfigSyncMock.mockReturnValue({
-      config: { site: { name: 'Legacy Docs' } },
-      configPath: '/renderer/.mdsite-compat.yml',
-      contentDir: path.join('/renderer', 'legacy-docs'),
-    })
-
-    const runtime = prepareRendererRuntime('/renderer')
-
-    expect(readFileSyncMock).toHaveBeenCalledWith('/renderer/content.config.yml', 'utf8')
-    expect(writeFileSyncMock).toHaveBeenCalledWith('/renderer/.mdsite-compat.yml', 'compat-config', 'utf8')
-    expect(loadMdsiteConfigSyncMock).toHaveBeenCalledWith({
-      configPath: '/renderer/.mdsite-compat.yml',
-      contentPath: path.join('/renderer', 'legacy-docs'),
-    })
-    expect(runtime.configPath).toBe('/renderer/.mdsite-compat.yml')
-    expect(process.env.MDSITE_CONFIG_PATH).toBe('/renderer/.mdsite-compat.yml')
-    expect(process.env.NUXT_CONTENT_PATH).toBe(path.join('/renderer', 'legacy-docs'))
-  })
-
-  it('supports the checked-in legacy renderer config keys', () => {
-    resolveMdsiteConfigPathMock.mockReturnValue(undefined)
-    existsSyncMock.mockImplementation((target: string) => (
-      target === '/renderer/content.config.yml' || target === '/content/docs'
-    ))
-    parseYamlMock.mockReturnValue({
-      contentPath: '/content/docs',
-      contentGitRepo: 'https://example.test/docs.git',
-      siteCanonical: 'https://example.test',
-      siteName: 'Legacy Site',
-    })
-    loadMdsiteConfigSyncMock.mockReturnValue({
-      config: { site: { name: 'Legacy Site' } },
-      configPath: '/renderer/.mdsite-compat.yml',
-      contentDir: '/content/docs',
-    })
-
-    prepareRendererRuntime('/renderer')
-
-    expect(stringifyYamlMock).toHaveBeenCalledWith(expect.objectContaining({
-      server: expect.objectContaining({
-        repo: 'https://example.test/docs.git',
-      }),
-      site: expect.objectContaining({
-        canonical: 'https://example.test',
-        name: 'Legacy Site',
-      }),
-    }))
-    expect(loadMdsiteConfigSyncMock).toHaveBeenCalledWith({
-      configPath: '/renderer/.mdsite-compat.yml',
-      contentPath: '/content/docs',
-    })
-  })
-
   it('exits when no renderer config can be resolved', () => {
     const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
     const processExitSpy = vi.spyOn(process, 'exit').mockImplementation((code?: number) => {

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

@@ -1,6 +1,5 @@
 import fs from 'fs'
 import path from 'path'
-import YAML from 'yaml'
 
 import { buildContentData } from './generate-indices.js'
 import { generateFavicons, generateWebManifest } from './generate-favicons.js'
@@ -18,15 +17,11 @@ export function prepareRendererRuntime(rootDir: string, options: {
   configPath?: string
   contentPath?: string
 } = {}): RendererRuntime {
-  let configPath = resolveMdsiteConfigPath({
+  const configPath = resolveMdsiteConfigPath({
     configPath: options.configPath,
     contentPath: options.contentPath ?? process.env.NUXT_CONTENT_PATH
   })
 
-  if (!configPath) {
-    configPath = ensureLegacyCompatibilityConfig(rootDir)
-  }
-
   if (!configPath) {
     console.error('❌ No mdsite.yml configuration found. Set MDSITE_CONFIG_PATH or pass a mdsite.yml path.')
     process.exit(1)
@@ -101,45 +96,3 @@ async function generateFaviconAssets(config: MdsiteConfig): Promise<void> {
 async function generateDevManifestAssets(config: MdsiteConfig): Promise<void> {
   await generateWebManifest({ name: config.site.name, themes: config.themes })
 }
-
-function ensureLegacyCompatibilityConfig(rootDir: string): string | undefined {
-  const legacyConfigPath = path.join(rootDir, 'content.config.yml')
-
-  if (!fs.existsSync(legacyConfigPath) || !fs.statSync(legacyConfigPath).isFile()) {
-    return undefined
-  }
-
-  const legacyConfig = YAML.parse(fs.readFileSync(legacyConfigPath, 'utf8')) ?? {}
-  const legacyContentPath = legacyConfig.content?.path || legacyConfig.content?.git?.path || legacyConfig.contentPath || 'docs'
-  const contentDir = path.resolve(rootDir, legacyContentPath)
-  const compatibilityConfigPath = path.join(rootDir, '.mdsite-compat.yml')
-  const compatibilityConfig = {
-    favicon: '',
-    features: {
-      bibleTooltips: legacyConfig.features?.bibleTooltips ?? true,
-      sourceEdit: legacyConfig.features?.sourceEdit ?? true
-    },
-    menu: [],
-    footer: [],
-    server: {
-      output: '.output',
-      path: '.mdsite',
-      repo: legacyConfig.content?.git?.repo || legacyConfig.contentGitRepo || '',
-      gitBranch: legacyConfig.server?.['git-branch'] || 'main'
-    },
-    site: {
-      canonical: legacyConfig.site?.canonical || legacyConfig.siteCanonical || '',
-      name: legacyConfig.site?.name || legacyConfig.siteName || path.basename(contentDir) || 'Site'
-    },
-    themes: legacyConfig.themes || {}
-  }
-
-  fs.writeFileSync(compatibilityConfigPath, YAML.stringify(compatibilityConfig), 'utf8')
-  process.env.NUXT_CONTENT_PATH = contentDir
-  process.env.CONTENT_DIR = contentDir
-  process.env.MDSITE_CONFIG_PATH = compatibilityConfigPath
-
-  console.warn(`⚠️ Using legacy compatibility fallback from ${legacyConfigPath}`)
-
-  return compatibilityConfigPath
-}

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

@@ -209,9 +209,22 @@ export async function startWatcher() {
         `${sourceDir}/**/*.md`            // Watch all markdown files
     ]
 
+    // Skip build/dependency directories (see `isExcludedSourceDir`). The
+    // matcher inspects every path segment so a hidden dir or
+    // `node_modules`/`dist` nested anywhere under the content dir is
+    // ignored, regardless of depth.
+    const ignored = (filePath: string, stats?: { isDirectory?: () => boolean }) => {
+        if (stats?.isDirectory && stats.isDirectory()) {
+            return isExcludedSourceDir(path.basename(filePath))
+        }
+        const segments = filePath.split(path.sep)
+        return segments.some((segment) => isExcludedSourceDir(segment))
+    }
+
     const watcher = chokidar.watch(patterns, {
         persistent: true,
         ignoreInitial: true, // Files already copied above
+        ignored,
         awaitWriteFinish: {
             stabilityThreshold: 500,
             pollInterval: 100
@@ -361,7 +374,29 @@ async function isDraftOnlyImage(imagePath: string): Promise<boolean> {
 }
 
 /**
- * Get all files with specific extension recursively
+ * Directory names that are never user-authored content. The recursive image
+ * walker and the dev-mode file watcher both skip these so a content
+ * directory that happens to be the project root (i.e. `mdsite.yml` lives
+ * at the repo root and `paths.input` is unset) does not crawl into the
+ * renderer working dir (`.mdsite/`), its `node_modules`, or other
+ * build/dependency artifacts.
+ *
+ * The rule is broad on purpose: any directory whose name starts with `.`
+ * (hidden dirs like `.git`, `.mdsite`, `.nuxt`, `.vscode`, `.idea`,
+ * `.history`, `.data`, `.output`, …) plus the two non-hidden directories
+ * that are always tooling artifacts (`node_modules`, `dist`).
+ *
+ * Keep this in sync with the same predicate in
+ * `scripts/generate-indices.ts` and the Nuxt Content collection `exclude`
+ * list in `content.config.ts`.
+ */
+function isExcludedSourceDir(name: string): boolean {
+    return name.startsWith('.') || name === 'node_modules' || name === 'dist'
+}
+
+/**
+ * Get all files with specific extension recursively, skipping
+ * build/dependency directories (see `isExcludedSourceDir`).
  */
 async function getAllFiles(dir: string, ext: string): Promise<string[]> {
     const files: string[] = []
@@ -377,6 +412,9 @@ async function getAllFiles(dir: string, ext: string): Promise<string[]> {
         const stat = await fs.stat(itemPath)
 
         if (stat.isDirectory()) {
+            if (isExcludedSourceDir(item)) {
+                continue
+            }
             const subFiles = await getAllFiles(itemPath, ext)
             files.push(...subFiles)
         } else if (item.toLowerCase().endsWith(`.${ext}`)) {