@life-and-dev/mdsite 0.5.0 → 0.5.1

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 >= 3" 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/useTableOfContents.test.ts

@@ -8,7 +8,7 @@ import { computeShouldShowTOC, TOC_MIN_HEADINGS, TOC_MIN_LINES } from './useTabl
 describe('useTableOfContents threshold', () => {
   it('exposes the expected minimum constants', () => {
     expect(TOC_MIN_HEADINGS).toBe(3)
-    expect(TOC_MIN_LINES).toBe(40)
+    expect(TOC_MIN_LINES).toBe(15)
   })
 
   describe('computeShouldShowTOC', () => {
@@ -18,13 +18,13 @@ describe('useTableOfContents threshold', () => {
       expect(computeShouldShowTOC(2, 100)).toBe(false)
     })
 
-    it('returns false when lines < 40 (and headings >= 3)', () => {
+    it('returns false when lines < 15 (and headings >= 3)', () => {
       expect(computeShouldShowTOC(3, 0)).toBe(false)
-      expect(computeShouldShowTOC(5, 39)).toBe(false)
+      expect(computeShouldShowTOC(5, 14)).toBe(false)
     })
 
-    it('returns true when headings >= 3 and lines >= 40', () => {
-      expect(computeShouldShowTOC(3, 40)).toBe(true)
+    it('returns true when headings >= 3 and lines >= 15', () => {
+      expect(computeShouldShowTOC(3, 15)).toBe(true)
       expect(computeShouldShowTOC(5, 100)).toBe(true)
     })
 

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

@@ -8,7 +8,7 @@ export interface TocItem {
 /** 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
+export const TOC_MIN_LINES = 15
 
 /**
  * Pure helper that decides whether the TOC should be shown.

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.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 }

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,7 @@ export interface MdsiteConfig {
     bibleTooltips: boolean
     sourceEdit: boolean
   }
-  menu: Array<string | null | Record<string, string | null | Array<any>>>
+  menu: MdsiteMenuItem[]
   footer: string[]
   server: {
     output: string

package/package.json

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