@life-and-dev/mdsite 0.5.3 → 0.7.0

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

@@ -1,10 +1,10 @@
 /**
  * Unit tests for the pure `mapSiteConfig` helper extracted from
- * `useSiteConfig`. The `sourceEdit` Edit-on-GitHub link in `AppBar` and
- * `AppFooter` is only rendered when `getEditUrl()` produces a URL, which
- * in turn requires `contentGitRepo` to be populated from `server.repo`.
- * These tests pin that mapping down so a future refactor cannot regress
- * it back to the empty-string default.
+ * `useSiteConfig`. The `sourceEdit` Edit-link in `AppBar` and `AppFooter`
+ * is only rendered when `getEditUrl()` produces a URL, which in turn
+ * requires `features.sourceEdit` to be a non-empty URL prefix. These
+ * tests pin that mapping down so a future refactor cannot regress it
+ * back to a boolean flag or break the empty-string default.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -17,13 +17,10 @@ describe('mapSiteConfig', () => {
     expect(result).toEqual({
       siteName: '',
       siteCanonical: '',
-      contentGitRepo: '',
-      contentGitBranch: 'main',
-      contentGitPath: '.',
       contentPath: '.',
       features: {
         bibleTooltips: false,
-        sourceEdit: false
+        sourceEdit: ''
       },
       themeColorLight: '#000000',
       themeColorDark: '#ffffff'
@@ -39,76 +36,29 @@ describe('mapSiteConfig', () => {
     expect(result.siteCanonical).toBe('https://example.test')
   })
 
-  describe('contentGitRepo (Edit on GitHub source)', () => {
-    it('reads server.repo into contentGitRepo', () => {
-      const result = mapSiteConfig({
-        server: { repo: 'https://github.com/life-and-dev/mdsite' }
-      }, undefined)
-
-      expect(result.contentGitRepo).toBe('https://github.com/life-and-dev/mdsite')
-    })
-
-    it('defaults to empty string when server.repo is missing', () => {
-      const result = mapSiteConfig({ server: {} }, undefined)
-
-      expect(result.contentGitRepo).toBe('')
-    })
-
-    it('defaults to empty string when server is missing entirely', () => {
-      const result = mapSiteConfig({}, undefined)
-
-      expect(result.contentGitRepo).toBe('')
-    })
-  })
-
-  describe('contentGitBranch (Edit on GitHub source)', () => {
-    it('defaults to "main" when server.gitBranch is missing', () => {
-      expect(mapSiteConfig({}, undefined).contentGitBranch).toBe('main')
-    })
-
-    it('defaults to "main" when server is missing entirely', () => {
-      expect(mapSiteConfig({ server: {} }, undefined).contentGitBranch).toBe('main')
-    })
-
-    it('reads server.gitBranch into contentGitBranch', () => {
-      const result = mapSiteConfig({
-        server: { gitBranch: 'develop' }
-      }, undefined)
-
-      expect(result.contentGitBranch).toBe('develop')
-    })
-
-    it('treats an empty string server.gitBranch as missing and falls back to "main"', () => {
-      // Whitespace-only branches are normalised away upstream in
-      // `utils/mdsite-config.ts` `normalizeMdsiteConfig`; the mapper here
-      // only falls back on the empty string, not on whitespace.
-      expect(mapSiteConfig({ server: { gitBranch: '' } }, undefined).contentGitBranch).toBe('main')
-    })
-  })
-
   describe('features', () => {
-    it('defaults both feature flags to false when features is missing', () => {
+    it('defaults sourceEdit to "" and bibleTooltips to false when features is missing', () => {
       const result = mapSiteConfig({}, undefined)
 
       expect(result.features.bibleTooltips).toBe(false)
-      expect(result.features.sourceEdit).toBe(false)
+      expect(result.features.sourceEdit).toBe('')
     })
 
-    it('reads sourceEdit from features.sourceEdit', () => {
+    it('reads sourceEdit (URL prefix) from features.sourceEdit', () => {
       const result = mapSiteConfig({
-        features: { sourceEdit: true, bibleTooltips: false }
+        features: { sourceEdit: 'https://github.com/org/repo/edit/main/', bibleTooltips: false }
       }, undefined)
 
-      expect(result.features.sourceEdit).toBe(true)
+      expect(result.features.sourceEdit).toBe('https://github.com/org/repo/edit/main/')
       expect(result.features.bibleTooltips).toBe(false)
     })
 
     it('reads bibleTooltips from features.bibleTooltips', () => {
       const result = mapSiteConfig({
-        features: { sourceEdit: false, bibleTooltips: true }
+        features: { sourceEdit: '', bibleTooltips: true }
       }, undefined)
 
-      expect(result.features.sourceEdit).toBe(false)
+      expect(result.features.sourceEdit).toBe('')
       expect(result.features.bibleTooltips).toBe(true)
     })
   })
@@ -139,28 +89,4 @@ describe('mapSiteConfig', () => {
     expect(mapSiteConfig({}, undefined).contentPath).toBe('.')
     expect(mapSiteConfig({}, '').contentPath).toBe('.')
   })
-
-  describe('contentGitPath (Edit on GitHub source)', () => {
-    it('defaults to "." when contentGitPath is undefined', () => {
-      // Preserves the historical cwd-relative fallback so existing
-      // callers/tests that omit the third arg keep working.
-      expect(mapSiteConfig({}, undefined).contentGitPath).toBe('.')
-      expect(mapSiteConfig({}, undefined, undefined).contentGitPath).toBe('.')
-    })
-
-    it('defaults to "." when contentGitPath is an empty string', () => {
-      // Empty string is treated as missing so an absent
-      // runtimeConfig.public.contentGitPath falls back cleanly.
-      expect(mapSiteConfig({}, undefined, '').contentGitPath).toBe('.')
-    })
-
-    it('passes an absolute contentGitPath through unchanged', () => {
-      // The renderer supplies `path.dirname(mdsite.configPath)` here so
-      // `relative(contentGitPath, contentPath)` is cwd-independent and
-      // identical on server and client (no hydration mismatch).
-      expect(
-        mapSiteConfig({}, '/home/user/site/docs', '/home/user/site').contentGitPath
-      ).toBe('/home/user/site')
-    })
-  })
 })

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

@@ -9,13 +9,9 @@ export interface RawSiteConfig {
     name?: string
     canonical?: string
   }
-  server?: {
-    repo?: string
-    gitBranch?: string
-  }
   features?: {
     bibleTooltips?: boolean
-    sourceEdit?: boolean
+    sourceEdit?: string
   }
   themes?: {
     light?: { colors?: { primary?: string } }
@@ -26,13 +22,10 @@ export interface RawSiteConfig {
 export interface SiteConfig {
   siteName: string
   siteCanonical: string
-  contentGitRepo: string
-  contentGitBranch: string
-  contentGitPath: string
   contentPath: string
   features: {
     bibleTooltips: boolean
-    sourceEdit: boolean
+    sourceEdit: string
   }
   themeColorLight: string
   themeColorDark: string
@@ -41,33 +34,22 @@ export interface SiteConfig {
 /**
  * Pure helper that maps the raw runtime `siteConfig` object into the shape
  * the renderer actually consumes. Extracted from `useSiteConfig` so the
- * field mapping (notably `contentGitRepo` ← `server.repo`, which is what
- * powers the Edit on GitHub link in `AppBar` and `AppFooter`) can be unit
- * tested independently of the Nuxt runtime.
+ * field mapping can be unit tested independently of the Nuxt runtime.
  *
- * `contentGitPath` must be an absolute path when supplied (the renderer
- * sets it from `path.dirname(mdsite.configPath)` in `nuxt.config.ts`).
- * Leaving it undefined preserves the historical cwd-relative `'.'`
- * default, which is only correct when the renderer's cwd equals the git
- * repo root — pass an absolute path to make `useSourceEdit`'s
- * `relative(contentGitPath, contentPath)` computation deterministic
- * across server and client and avoid hydration mismatches.
+ * `sourceEdit` is a user-supplied URL prefix used by `useSourceEdit` to
+ * build per-page Edit links; an empty string disables the link.
  */
 export function mapSiteConfig(
   siteConfig: RawSiteConfig | undefined,
   contentPath: string | undefined,
-  contentGitPath: string | undefined = '.',
 ): SiteConfig {
   return {
     siteName: siteConfig?.site?.name || '',
     siteCanonical: siteConfig?.site?.canonical || '',
-    contentGitRepo: siteConfig?.server?.repo || '',
-    contentGitBranch: siteConfig?.server?.gitBranch || 'main',
-    contentGitPath: contentGitPath || '.',
     contentPath: contentPath || '.',
     features: {
       bibleTooltips: siteConfig?.features?.bibleTooltips ?? false,
-      sourceEdit: siteConfig?.features?.sourceEdit ?? false
+      sourceEdit: siteConfig?.features?.sourceEdit ?? ''
     },
     themeColorLight: siteConfig?.themes?.light?.colors?.primary || '#000000',
     themeColorDark: siteConfig?.themes?.dark?.colors?.primary || '#ffffff'
@@ -83,7 +65,6 @@ export function useSiteConfig(): SiteConfig {
 
   return mapSiteConfig(
     siteConfig,
-    config.public.contentPath,
-    config.public.contentGitPath as string | undefined
+    config.public.contentPath
   )
 }

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

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for `buildEditUrl`, the pure helper extracted from
+ * `useSourceEdit`. The composable itself depends on Nuxt's auto-imported
+ * `useRoute`/`useSiteConfig`, so the testable surface is the pure
+ * function. The slug-derivation logic in `mapSiteConfig` is already
+ * pinned by `useSiteConfig.test.ts`; these tests pin the URL-building
+ * behavior — most importantly that a user-supplied `source-edit` URL
+ * without a trailing slash still produces a valid path with exactly
+ * one separator (no `…/blob/mainindex.md` bug, no duplicate slashes).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { buildEditUrl } from './useSourceEdit'
+
+describe('buildEditUrl', () => {
+  describe('disabled prefix', () => {
+    it('returns undefined when prefix is empty', () => {
+      expect(buildEditUrl('', '/features/source-edit')).toBeUndefined()
+    })
+
+    it('returns undefined when prefix is whitespace-only', () => {
+      expect(buildEditUrl('   ', '/features/source-edit')).toBeUndefined()
+    })
+
+    it('does not depend on route path when prefix is empty', () => {
+      expect(buildEditUrl('', '/')).toBeUndefined()
+      expect(buildEditUrl('', '')).toBeUndefined()
+    })
+  })
+
+  describe('separator normalization', () => {
+    const nestedPath = '/features/source-edit'
+
+    it('inserts a single "/" when prefix has no trailing slash', () => {
+      // Regression: previously produced `…/blob/mainfeatures/source-edit.md`.
+      expect(buildEditUrl('https://github.com/org/repo/blob/main', nestedPath))
+        .toBe('https://github.com/org/repo/blob/main/features/source-edit.md')
+    })
+
+    it('keeps exactly one "/" when prefix already has a trailing slash', () => {
+      expect(buildEditUrl('https://github.com/org/repo/blob/main/', nestedPath))
+        .toBe('https://github.com/org/repo/blob/main/features/source-edit.md')
+    })
+
+    it('collapses multiple trailing slashes to one', () => {
+      expect(buildEditUrl('https://github.com/org/repo/blob/main///', nestedPath))
+        .toBe('https://github.com/org/repo/blob/main/features/source-edit.md')
+      expect(buildEditUrl('https://github.com/org/repo/blob/main//', nestedPath))
+        .toBe('https://github.com/org/repo/blob/main/features/source-edit.md')
+    })
+
+    it('does not double-slash when prefix path component already ends with slash', () => {
+      // Defensive: ensures normalize strips every trailing slash, not just
+      // the last one.
+      expect(buildEditUrl('https://github.com/org/repo/blob/main//', '/index'))
+        .toBe('https://github.com/org/repo/blob/main/index.md')
+    })
+  })
+
+  describe('route path handling', () => {
+    const prefix = 'https://github.com/org/repo/blob/main'
+
+    it('maps the root path "/" to index.md', () => {
+      expect(buildEditUrl(prefix, '/')).toBe(`${prefix}/index.md`)
+    })
+
+    it('maps an empty path to index.md', () => {
+      expect(buildEditUrl(prefix, '')).toBe(`${prefix}/index.md`)
+    })
+
+    it('strips a leading slash from nested paths', () => {
+      expect(buildEditUrl(prefix, '/features/source-edit'))
+        .toBe(`${prefix}/features/source-edit.md`)
+    })
+
+    it('passes nested paths without leading slash through unchanged', () => {
+      expect(buildEditUrl(prefix, 'features/source-edit'))
+        .toBe(`${prefix}/features/source-edit.md`)
+    })
+
+    it('handles single-segment nested paths', () => {
+      expect(buildEditUrl(prefix, '/menu'))
+        .toBe(`${prefix}/menu.md`)
+    })
+  })
+
+  describe('combined normalization + route handling', () => {
+    it('produces the documented URL for the docs site root with no trailing slash', () => {
+      // The exact case from the bug report: `mdsite.yml:6` has no trailing
+      // slash and the docs root resolves to `index.md`.
+      expect(buildEditUrl('https://github.com/life-and-dev/mdsite/blob/main', '/'))
+        .toBe('https://github.com/life-and-dev/mdsite/blob/main/index.md')
+    })
+
+    it('produces the same URL whether or not the user adds a trailing slash', () => {
+      const a = buildEditUrl('https://github.com/org/repo/blob/main', '/features/source-edit')
+      const b = buildEditUrl('https://github.com/org/repo/blob/main/', '/features/source-edit')
+      const c = buildEditUrl('https://github.com/org/repo/blob/main///', '/features/source-edit')
+      expect(a).toBe(b)
+      expect(b).toBe(c)
+    })
+  })
+})

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

@@ -1,66 +1,54 @@
-import { relative, normalize, posix } from 'pathe'
+/**
+ * Generate source edit URL for the current page.
+ *
+ * `siteConfig.features.sourceEdit` is a user-supplied URL prefix (e.g.
+ * `https://github.com/org/repo/edit/main`) to which the renderer's
+ * per-route content path (with a `.md` suffix) is appended. The prefix is
+ * normalized so the user may include or omit a trailing slash — any
+ * number of trailing slashes is collapsed to exactly one. An empty or
+ * whitespace-only prefix disables the link. The user is in control of
+ * the full URL — no provider-specific validation is performed.
+ */
 
 /**
- * Generate source edit URL for the current page
+ * Build a source-edit URL from a user-supplied prefix and a route path.
+ *
+ * Exported for unit testing. Behavior:
+ * - Returns `undefined` when `prefix` is empty or whitespace-only.
+ * - Strips every trailing `/` from `prefix`, then inserts exactly one `/`
+ *   between the prefix and the content path. This means a prefix with no
+ *   trailing slash (`…/blob/main`) and a prefix with one (`…/blob/main/`)
+ *   both produce the same result, and a prefix with several
+ *   (`…/blob/main///`) does not yield duplicate slashes.
+ * - The route `/` and an empty path both map to `index.md`.
+ *
+ * @param prefix      URL prefix from `features.source-edit`
+ * @param routePath   Current route path (e.g. `/features/source-edit`)
+ * @returns           Full edit URL, or `undefined` when disabled
  */
-export function useSourceEdit() {
-    const route = useRoute()
-    const siteConfig = useSiteConfig()
+export function buildEditUrl(prefix: string, routePath: string): string | undefined {
+    if (!prefix || prefix.trim() === '') {
+        return undefined
+    }
 
-    /**
-     * Calculate the subdirectory within the git repo where content is located
-     */
-    function getContentSubdirectory(): string {
-        const gitPath = normalize(siteConfig.contentGitPath)
-        const contentPath = normalize(siteConfig.contentPath)
+    const contentPath = !routePath || routePath === '/'
+        ? 'index'
+        : (routePath.startsWith('/') ? routePath.slice(1) : routePath)
 
-        // Calculate relative path from git root to content directory
-        const subdir = relative(gitPath, contentPath)
+    const normalizedPrefix = prefix.replace(/\/+$/, '')
+    return `${normalizedPrefix}/${contentPath}.md`
+}
 
-        // Convert to posix path for GitHub URLs (forward slashes)
-        return subdir ? posix.normalize(subdir) : ''
-    }
+export function useSourceEdit() {
+    const route = useRoute()
+    const siteConfig = useSiteConfig()
 
     /**
      * Generate source edit URL for current route
      * @returns source edit URL or undefined if not enabled or not a content page
      */
     function getEditUrl(): string | undefined {
-        const path = route.path
-        const repo = siteConfig.contentGitRepo
-
-        // Check if feature is enabled
-        if (!siteConfig.features.sourceEdit) {
-            return undefined
-        }
-
-        // Only render if repo starts with "https://github.com" (current supported provider)
-        if (!repo || !repo.startsWith('https://github.com')) {
-            return undefined
-        }
-
-        var contentPath: string;
-
-        // Home page path
-        if (!path || path === '/') {
-            contentPath = 'index'
-        }
-
-        // Convert route path to content file path
-        // Example: /church/evolution/312-constantine → https://github.com/life-and-dev/church/blob/main/evolution/312-constantine.md
-        else {
-            contentPath = path.startsWith('/') ? path.slice(1) : path
-        }
-
-        // Get the subdirectory within the git repo
-        const subdir = getContentSubdirectory()
-
-        // Build the full path: subdirectory + content file path
-        const fullPath = subdir
-            ? `${subdir}/${contentPath}.md`
-            : `${contentPath}.md`
-
-        return `${repo}/blob/${siteConfig.contentGitBranch}/${fullPath}`
+        return buildEditUrl(siteConfig.features.sourceEdit, route.path)
     }
 
     return {

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

@@ -35,6 +35,12 @@
               <slot />
             </div>
           </v-container>
+          <!--
+            Footer sits inside the main column (not as a fixed bottom bar) so it
+            scrolls with the article and only appears once the user has reached
+            the end of the page.
+          -->
+          <AppFooter />
         </v-main>
 
         <!-- Right Sidebar (Table of Contents) -->
@@ -110,11 +116,12 @@
             <slot />
           </div>
         </v-container>
+        <!--
+          In-flow footer for mobile: scrolls with the article content.
+        -->
+        <AppFooter />
       </v-main>
     </div>
-
-    <!-- Footer Bar (always visible on all layouts) -->
-    <AppFooter />
   </div>
 </template>
 

package/mdsite-nuxt/nuxt.config.ts

@@ -9,17 +9,17 @@ import { loadMdsiteConfigSync } from './utils/mdsite-config'
 const mdsite = loadMdsiteConfigSync()
 const siteConfig = mdsite.config
 const appBaseURL = process.env.NUXT_APP_BASE_URL || '/'
-// The git repo root, used by `useSourceEdit` to compute the
-// repo-relative path to a content file (so the Edit-on-GitHub URL
-// points at `…/blob/<branch>/<subdir>/<file>.md` rather than a
-// cwd-relative or absolute filesystem path). We default to the
-// directory containing `mdsite.yml` because that is the conventional
-// git root for an mdsite content dir; falling back to the content
-// dir itself covers the case where `mdsite.yml` is missing (legacy
-// `content.config.yml` layouts loaded through `renderer-hooks`).
-const contentGitPath = mdsite.configPath
-  ? path.dirname(mdsite.configPath)
-  : mdsite.contentDir
+
+// mdsite is a static site generator. SSR is only needed at build time so
+// `nuxi generate` can pre-render every route to HTML. In `dev` and
+// `preview` mode SSR uses a per-request fork worker that pulls the full
+// Nuxt + Vuetify + @nuxt/content + mermaid + sharp pipeline and OOMs
+// (Worker terminated … JS heap out of memory) on memory-constrained
+// hosts. Keep SSR on for build/generate, off for dev/preview so the
+// dev server renders client-side only and `mdsite generate` still
+// produces per-route static HTML.
+const isSsrNuxtCommand = process.argv.includes('build') || process.argv.includes('generate')
+const ssrEnabled = isSsrNuxtCommand
 
 export default defineNuxtConfig({
   compatibilityDate: '2025-07-15',
@@ -29,7 +29,6 @@ export default defineNuxtConfig({
     public: {
       contentDomain: path.basename(mdsite.contentDir),
       contentPath: mdsite.contentDir,
-      contentGitPath,
       // `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
@@ -58,10 +57,18 @@ export default defineNuxtConfig({
   },
 
   nitro: {
-    preset: 'static'  // Pure static preset - no SPA fallbacks
+    preset: 'static',  // Pure static preset - no SPA fallbacks
+    // The `mdsite` CLI sets `MDSITE_NITRO_OUTPUT_DIR` in dev mode so the
+    // build output lands in the content directory's `<paths.build>/.output/`
+    // rather than inside the renderer source (e.g. the `mdsite-nuxt/`
+    // submodule). The default `.output` is kept for direct use of the
+    // renderer (e.g. running `nuxt generate` by hand for renderer dev).
+    output: {
+      dir: process.env.MDSITE_NITRO_OUTPUT_DIR || '.output'
+    }
   },
 
-  ssr: true,
+  ssr: ssrEnabled,
 
   css: [
     '~/assets/css/markdown.css',
@@ -186,7 +193,7 @@ export default defineNuxtConfig({
     },
 
     'build:before': async () => {
-      if (process.argv.includes('prepare') || !mdsite.configPath || process.env.MDSITE_RENDERER_ORCHESTRATED === '1') {
+      if (process.argv.includes('prepare') || !mdsite.configPath) {
         return
       }
 

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

@@ -66,12 +66,12 @@ describe('generate-favicons', () => {
   })
 
   describe('generateFavicons', () => {
-    it('uses the bundled default favicon and writes all expected assets when config.favicon is empty', async () => {
+    it('uses the bundled default favicon and writes all expected assets when site.favicon is empty', async () => {
       const outputDir = path.join(tmpDir, 'output')
 
       const ok = await generateFavicons({
         contentDir: tmpDir,
-        config: { favicon: '' },
+        config: { site: { favicon: '' } },
         outputDir,
       })
 
@@ -106,7 +106,7 @@ describe('generate-favicons', () => {
 
       const ok = await generateFavicons({
         contentDir: tmpDir,
-        config: { favicon: 'favicon.svg' },
+        config: { site: { favicon: 'favicon.svg' } },
         outputDir,
       })
 

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

@@ -38,7 +38,7 @@ export function resolveFaviconSource(
 
 export interface GenerateFaviconsOptions {
   contentDir?: string
-  config?: { favicon?: string; site?: { name?: string } }
+  config?: { site?: { favicon?: string; name?: string } }
   outputDir?: string
 }
 
@@ -50,9 +50,9 @@ export async function generateFavicons(options: GenerateFaviconsOptions = {}): P
     ? { contentDir: options.contentDir, config: options.config }
     : loadMdsiteConfigSync()
   const { contentDir, config } = resolved
-  const siteName = (config as { site?: { name?: string } }).site?.name ?? 'site'
+  const siteName = config.site?.name ?? 'site'
 
-  const resolvedSource = resolveFaviconSource(contentDir, config.favicon ?? '')
+  const resolvedSource = resolveFaviconSource(contentDir, config.site?.favicon ?? '')
 
   if (!resolvedSource) {
     console.error('❌ No favicon source available (configured source missing AND bundled default not found).')
@@ -64,7 +64,7 @@ export async function generateFavicons(options: GenerateFaviconsOptions = {}): P
   await fs.ensureDir(publicDir)
 
   if (resolvedSource.isDefault) {
-    console.log('ℹ️ No favicon source configured (config.favicon empty or file not found). Using bundled default favicon.')
+    console.log('ℹ️ No favicon source configured (site.favicon empty or file not found). Using bundled default favicon.')
   }
 
   console.log(`🎨 Generating favicons for site: ${siteName}`)