@karaoke-cms/astro 0.9.7 → 0.10.3

package/src/index.ts

@@ -1,15 +1,17 @@
 import type { AstroIntegration } from 'astro';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { fileURLToPath } from 'url';
-import { resolve, isAbsolute, dirname } from 'path';
+import { resolve, isAbsolute, dirname, join } from 'path';
 import { wikiLinkPlugin } from 'remark-wiki-link';
+import { remarkObsidianEmbeds, pendingMediaCopies } from './remark/remark-obsidian-embeds.js';
 import sitemap from '@astrojs/sitemap';
 import { validateModules } from './validate-config.js';
 import { resolveModules } from './utils/resolve-modules.js';
 import { resolveLayout } from './utils/resolve-layout.js';
 import { resolveCollections } from './utils/resolve-collections.js';
 import { resolveMenus } from './utils/resolve-menus.js';
-import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from './types.js';
+import { generateDocsInstancePages } from './codegen/generate-docs-instance.js';
+import type { KaraokeConfig, ModuleInstance, ThemeInstance, ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from './types.js';
 
 /**
  * karaoke() — the main Astro integration for karaoke-cms.
@@ -56,6 +58,7 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
 
   const theme = config.theme;
   let _resolvedCollections: ResolvedCollections | undefined;
+  let _docsInstances: Array<{ id: string; collection: string; mount: string; folder: string; label: string; layout: string; sidebarStyle: string }> = [];
 
   return {
     name: '@karaoke-cms/astro',
@@ -66,13 +69,36 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
           ? (isAbsolute(config.vault) ? config.vault : resolve(rootDir, config.vault))
           : rootDir;
         const isProd = command === 'build';
+
+        if (!existsSync(vaultDir)) {
+          console.warn(
+            `[karaoke-cms] Vault path does not exist: ${vaultDir}\n` +
+            `  Check KARAOKE_VAULT in your .env or .env.default. The site will build with empty collections.`,
+          );
+        }
+
         _resolvedCollections = resolveCollections(vaultDir, isProd, config.collections);
-        const modules = (config.modules ?? []).filter(m => m.enabled !== false);
-        const _resolvedMenus = resolveMenus(vaultDir, modules);
+
+        // ── Gather modules from both config.modules and theme.implementedModules ──
+        // config.modules are user-declared; theme.implementedModules are theme-built-in.
+        // Dedup by id: config wins (first seen).
+        const configModules = (config.modules ?? []).filter((m: ModuleInstance) => m.enabled !== false);
+        const themeModules = isThemeInstance(config.theme)
+          ? (config.theme.implementedModules ?? []).filter((m: ModuleInstance) => m.enabled !== false)
+          : [];
+        const seenIds = new Set<string>();
+        const allModules = [...configModules, ...themeModules].filter((m: ModuleInstance) => {
+          if (seenIds.has(m.id)) return false;
+          seenIds.add(m.id);
+          return true;
+        });
+
+        const _resolvedMenus = resolveMenus(vaultDir, allModules);
 
         // ── Scaffold module pages and CSS on first dev run ────────────────
+        // Only scaffold for user-declared config.modules (theme modules handle their own CSS).
         if (command === 'dev') {
-          for (const mod of modules) {
+          for (const mod of configModules) {
             if (mod.scaffoldPages) {
               for (const { src, dest } of mod.scaffoldPages) {
                 if (!existsSync(src)) continue;
@@ -109,24 +135,39 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
           }
         }
 
-        // ── Load theme and inject module routes ───────────────────────────
-        const themeIntegration = theme.toAstroIntegration(modules);
+        // ── Code-generate per-instance docs pages ─────────────────────────
+        const docsInstances = allModules
+          .filter((m: ModuleInstance) => m.collection != null)
+          .map((m: ModuleInstance) => ({
+            id: m.id,
+            collection: m.collection!.name,
+            mount: m.mount,
+            folder: m.collection!.folder,
+            label: m.collection!.label,
+            layout: m.collection!.layout,
+            sidebarStyle: m.collection!.sidebarStyle,
+          }));
+        _docsInstances = docsInstances;
+        const generatedRoutes = generateDocsInstancePages(rootDir, docsInstances);
 
-        for (const mod of modules) {
-          for (const route of mod.routes) {
-            injectRoute(route);
-          }
-        }
+        // ── Load theme and inject module routes ───────────────────────────
+        // Pass only configModules to the theme — it already knows its implementedModules.
+        const themeIntegration = theme.toAstroIntegration(configModules);
 
-        // ── Module routes — injected from implements[] on the ThemeInstance ──
-        if (isThemeInstance(config.theme)) {
-          for (const mod of config.theme.implementedModules ?? []) {
+        // Inject non-docs module routes (blog, search, etc.)
+        for (const mod of allModules) {
+          if (!mod.collection) {
             for (const route of mod.routes) {
-              injectRoute({ pattern: route.pattern, entrypoint: route.entrypoint });
+              injectRoute(route);
             }
           }
         }
 
+        // Inject generated docs routes (file:// URLs to .astro/generated/... files)
+        for (const route of generatedRoutes) {
+          injectRoute(route);
+        }
+
         // ── Core routes — always present regardless of theme ─────────────
         injectRoute({ pattern: '/rss.xml', entrypoint: '@karaoke-cms/astro/pages/rss.xml.ts' });
 
@@ -136,13 +177,23 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
           injectRoute({ pattern: '/karaoke-cms/[...slug]', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/[...slug].astro' });
         }
 
+        // Collect optional Astro integrations from modules (e.g. module-seo's Vite plugin)
+        const moduleIntegrations = allModules
+          .map((m: ModuleInstance) => m.integration)
+          .filter((i): i is AstroIntegration => i !== undefined);
+
         updateConfig({
-          integrations: [sitemap(), themeIntegration],
+          integrations: [sitemap(), themeIntegration, ...moduleIntegrations],
           vite: {
-            plugins: [virtualConfigPlugin(config, resolved, layout, _resolvedCollections, _resolvedMenus)],
+            plugins: [
+              virtualConfigPlugin(config, resolved, layout, _resolvedCollections, _resolvedMenus, vaultDir, allModules),
+              virtualDocsSectionsPlugin(docsInstances),
+              mediaPlugin(pendingMediaCopies),
+            ],
           },
           markdown: {
             remarkPlugins: [
+              [remarkObsidianEmbeds, { vaultDir }],
               [wikiLinkPlugin, {
                 pageResolver: (name: string) => [name.toLowerCase().replace(/ /g, '-')],
                 hrefTemplate: (permalink: string) => `/${permalink}/`,
@@ -154,14 +205,22 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
       },
 
       'astro:build:done'({ pages }) {
-        if (!_resolvedCollections?.docs?.enabled) return;
-        // pages is { pathname: string }[] — check if any /docs page was rendered
-        const hasDocsRoute = (pages ?? []).some(p => p.pathname?.startsWith('docs'));
-        if (!hasDocsRoute) {
+        // Skip if neither the legacy docs collection nor any docs module instance is active.
+        if (!_resolvedCollections?.docs?.enabled && _docsInstances.length === 0) return;
+        // Check if at least one docs-style page was rendered.
+        // If _docsInstances is populated, codegen routes are active — check each mount.
+        // Fallback to legacy /docs regex for backward compat with theme-provided docs routes.
+        const pagePathnameSet = new Set((pages ?? []).map(p => p.pathname ?? ''));
+        const hasAnyDocsPage = _docsInstances.length > 0
+          ? _docsInstances.some(inst =>
+              [...pagePathnameSet].some(p => p.startsWith(inst.mount.replace(/^\//, '')))
+            )
+          : [...pagePathnameSet].some(p => p.match(/^docs\b/));
+        if (!hasAnyDocsPage) {
           console.warn(
-            '[karaoke-cms] Your vault has a docs collection enabled but the active theme ' +
-            'has no /docs route. Published docs entries will not be accessible. ' +
-            'Consider using @karaoke-cms/theme-default which includes /docs routes.',
+            '[karaoke-cms] Your vault has a docs collection enabled but no docs route was ' +
+            'rendered. Published docs entries will not be accessible. ' +
+            'Consider adding docs() to your theme\'s implements or config.modules.',
           );
         }
       },
@@ -178,11 +237,15 @@ function virtualConfigPlugin(
   resolved: ResolvedModules,
   layout: ResolvedLayout,
   resolvedCollections: ResolvedCollections,
-  resolvedMenus: ResolvedMenus,
+  initialResolvedMenus: ResolvedMenus,
+  vaultDir: string,
+  modules: ModuleInstance[],
 ) {
   const VIRTUAL_ID = 'virtual:karaoke-cms/config';
   const RESOLVED_ID = '\0' + VIRTUAL_ID;
 
+  let currentMenus = initialResolvedMenus;
+
   return {
     name: 'vite-plugin-karaoke-cms-config',
     resolveId(id: string) {
@@ -196,17 +259,115 @@ export const siteDescription = ${JSON.stringify(config.description ?? '')};
 export const resolvedModules = ${JSON.stringify(resolved)};
 export const resolvedLayout = ${JSON.stringify(layout)};
 export const resolvedCollections = ${JSON.stringify(resolvedCollections)};
-export const resolvedMenus = ${JSON.stringify(resolvedMenus)};
+export const resolvedMenus = ${JSON.stringify(currentMenus)};
 export const blogMount = ${JSON.stringify(
   (config.modules ?? []).find((m: { id: string; mount: string }) => m.id === 'blog')?.mount ?? '/blog'
 )};
 `;
       }
     },
+    configureServer(server: any) {
+      const menusPath = join(vaultDir, 'karaoke-cms/config/menus.yaml');
+      server.watcher.add(menusPath);
+      server.watcher.on('change', (file: string) => {
+        if (file !== menusPath) return;
+        currentMenus = resolveMenus(vaultDir, modules);
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+        if (mod) server.moduleGraph.invalidateModule(mod);
+        server.ws.send({ type: 'full-reload' });
+      });
+    },
+  };
+}
+
+/**
+ * Vite plugin providing `virtual:karaoke-cms/docs-sections`.
+ * Generated doc pages, tags/[tag].astro, RecentPosts, and rss.xml import from it
+ * to discover all active docs sections at build time.
+ */
+function virtualDocsSectionsPlugin(docsInstances: Array<{ id: string; collection: string; mount: string; folder: string; label: string; layout: string; sidebarStyle: string }>) {
+  const VIRTUAL_ID = 'virtual:karaoke-cms/docs-sections';
+  const RESOLVED_ID = '\0' + VIRTUAL_ID;
+
+  return {
+    name: 'vite-plugin-karaoke-cms-docs-sections',
+    resolveId(id: string) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+    },
+    load(id: string) {
+      if (id === RESOLVED_ID) {
+        return `export const docsSections = ${JSON.stringify(docsInstances)};`;
+      }
+    },
+  };
+}
+
+/**
+ * Vite plugin serving vault media files (audio, video, and wiki-linked frontmatter images)
+ * from /media/<filename> during dev and emitting them to dist/media/ during build.
+ */
+function mediaPlugin(mediaCopies: Set<string>) {
+  const MIME: Record<string, string> = {
+    jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png',
+    gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', avif: 'image/avif',
+    mp3: 'audio/mpeg', m4a: 'audio/mp4', ogg: 'audio/ogg', wav: 'audio/wav', flac: 'audio/flac',
+    mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime',
+  };
+
+  const findAbsPath = (basename: string): string | undefined => {
+    for (const abs of mediaCopies) {
+      if (abs.endsWith('/' + basename) || abs.endsWith('\\' + basename)) return abs;
+    }
+  };
+
+  return {
+    name: 'vite-plugin-karaoke-media',
+    configureServer(server: any) {
+      server.middlewares.use((req: any, res: any, next: any) => {
+        if (!req.url?.startsWith('/media/')) return next();
+        const basename = req.url.slice('/media/'.length).split('?')[0];
+        const absPath = findAbsPath(basename);
+        if (!absPath) return next();
+        const ext = basename.split('.').pop()?.toLowerCase() ?? '';
+        res.setHeader('Content-Type', MIME[ext] ?? 'application/octet-stream');
+        res.end(readFileSync(absPath));
+      });
+    },
+    generateBundle(this: any) {
+      for (const absPath of mediaCopies) {
+        const basename = absPath.split('/').pop()!;
+        this.emitFile({ type: 'asset', fileName: `media/${basename}`, source: readFileSync(absPath) });
+      }
+    },
   };
 }
 
 export { defineModule } from './define-module.js';
 export { defineTheme } from './define-theme.js';
-export type { ModuleInstance, ThemeInstance, ModuleMenuEntry } from './types.js';
-export type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, RegionComponent, ResolvedMenus, ResolvedMenu, ResolvedMenuEntry } from './types.js';
+export { resolveWikiImage } from './remark/remark-obsidian-embeds.js';
+export type {
+  // CSS contract
+  CssContractSlot,
+  CssContract,
+  // Named primitive types
+  RouteDefinition,
+  CollectionSpec,
+  ScaffoldPage,
+  // Module system
+  ModuleInstance,
+  ThemeInstance,
+  ModuleMenuEntry,
+  // Factory definitions
+  ModuleDefinition,
+  ThemeDefinition,
+  ThemeFactoryConfig,
+  // Configuration
+  KaraokeConfig,
+  ResolvedModules,
+  ResolvedLayout,
+  ResolvedCollections,
+  RegionComponent,
+  ResolvedMenus,
+  ResolvedMenu,
+  ResolvedMenuEntry,
+} from './types.js';

package/src/pages/rss.xml.ts

@@ -1,13 +1,18 @@
 import rss from '@astrojs/rss';
 import { getCollection } from 'astro:content';
 import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
+import { docsSections } from 'virtual:karaoke-cms/docs-sections';
 import type { APIContext } from 'astro';
 
 export async function GET(context: APIContext) {
-  const [blogPosts, docPages] = await Promise.all([
-    getCollection('blog', ({ data }) => data.publish === true),
-    getCollection('docs', ({ data }) => data.publish === true),
-  ]);
+  const blogPosts = await getCollection('blog', ({ data }) => data.publish === true);
+
+  // Fetch from all active docs collections; use allSettled so one missing collection
+  // doesn't abort the entire RSS feed (e.g., if content.config.ts wasn't updated yet).
+  const docsSettled = await Promise.allSettled(
+    docsSections.map(s => getCollection(s.collection as any, ({ data }) => data.publish === true))
+  );
+  const docsResults = docsSettled.map(r => r.status === 'fulfilled' ? r.value : []);
 
   const blogItems = blogPosts.map(post => ({
     title: post.data.title,
@@ -16,12 +21,14 @@ export async function GET(context: APIContext) {
     link: `/blog/${post.id}/`,
   }));
 
-  const docItems = docPages.map(doc => ({
-    title: doc.data.title,
-    pubDate: doc.data.date,
-    description: doc.data.description,
-    link: `/docs/${doc.id}/`,
-  }));
+  const docItems = docsSections.flatMap((s, i) =>
+    (docsResults[i] ?? []).map(doc => ({
+      title: doc.data.title,
+      pubDate: doc.data.date,
+      description: doc.data.description,
+      link: `${s.mount}/${doc.id}/`,
+    }))
+  );
 
   const items = [...blogItems, ...docItems].sort(
     (a, b) => (b.pubDate?.valueOf() ?? 0) - (a.pubDate?.valueOf() ?? 0),

package/src/remark/remark-obsidian-embeds.ts

@@ -0,0 +1,260 @@
+/**
+ * remark-obsidian-embeds
+ *
+ * Transforms Obsidian-style ![[file]] embed syntax into standard mdast nodes:
+ *   - Images (.png, .jpg, etc.) → mdast `image` node with relative path
+ *     → triggers Astro's remark-collect-images + image optimization pipeline
+ *   - Audio (.mp3, .m4a, etc.) → mdast `html` node with <audio controls>
+ *   - Video (.mp4, .webm, etc.) → mdast `html` node with <video controls>
+ *   - Unsupported types or unresolved files → raw text preserved
+ *
+ * Path resolution order (mirrors Obsidian's own lookup):
+ *   1. Same folder as the note
+ *   2. Vault attachmentFolderPath from .obsidian/app.json (vault-root-relative)
+ *   3. Vault root
+ *
+ * IMPORTANT: In Obsidian, paths in attachmentFolderPath starting with '/'
+ * are vault-root-relative (NOT filesystem-absolute). Always join with vaultDir.
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { dirname, join, relative, resolve } from 'path'
+
+// Matches ![[filename]] and ![[filename|hint]]
+// Group 1: filename (may include subfolder like "folder/image.png")
+// Group 2: hint (optional — e.g., "200", "alt text", "300x200")
+const EMBED_RE = /!\[\[([^\]#|]+?)(?:\|([^\]]*))?\]\]/g
+
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.avif'])
+const AUDIO_EXTS = new Set(['.mp3', '.m4a', '.ogg', '.wav', '.flac'])
+const VIDEO_EXTS = new Set(['.mp4', '.webm', '.mov'])
+
+/**
+ * Set of absolute vault paths for audio/video files that need to be served.
+ * Populated at remark-transform time, drained by the Vite plugin at build time.
+ */
+export const pendingMediaCopies = new Set<string>()
+
+interface ObsidianAppConfig {
+  attachmentFolderPath?: string
+}
+
+const obsidianConfigCache = new Map<string, ObsidianAppConfig>()
+
+function getObsidianConfig(vaultDir: string): ObsidianAppConfig {
+  if (!obsidianConfigCache.has(vaultDir)) {
+    try {
+      const configPath = join(vaultDir, '.obsidian', 'app.json')
+      const config = existsSync(configPath)
+        ? (JSON.parse(readFileSync(configPath, 'utf8')) as ObsidianAppConfig)
+        : {}
+      obsidianConfigCache.set(vaultDir, config)
+    } catch {
+      obsidianConfigCache.set(vaultDir, {})
+    }
+  }
+  return obsidianConfigCache.get(vaultDir)!
+}
+
+function extOf(filename: string): string {
+  const dot = filename.lastIndexOf('.')
+  return dot >= 0 ? filename.slice(dot).toLowerCase() : ''
+}
+
+function resolveVaultAsset(
+  filename: string,
+  noteDir: string,
+  vaultDir: string,
+): string | null {
+  const config = getObsidianConfig(vaultDir)
+
+  const candidates: string[] = [
+    join(noteDir, filename),
+    ...(config.attachmentFolderPath
+      // In Obsidian, even paths starting with '/' are vault-root-relative
+      ? [join(vaultDir, config.attachmentFolderPath, filename)]
+      : []),
+    join(vaultDir, filename),
+  ]
+
+  // Deduplicate (noteDir might equal vaultDir for root-level notes)
+  const seen = new Set<string>()
+  for (const candidate of candidates) {
+    const abs = resolve(candidate)
+    if (seen.has(abs)) continue
+    seen.add(abs)
+    if (existsSync(abs)) return abs
+  }
+  return null
+}
+
+interface EmbedHint {
+  alt: string
+  width?: number
+  height?: number
+}
+
+function parseHint(hint: string | undefined): EmbedHint {
+  if (!hint) return { alt: '' }
+  const trimmed = hint.trim()
+  // WxH format: "300x200" → width + height
+  const wxh = /^(\d+)x(\d+)$/i.exec(trimmed)
+  if (wxh) return { alt: '', width: parseInt(wxh[1], 10), height: parseInt(wxh[2], 10) }
+  // Numeric-only: "200" → width only
+  if (/^\d+$/.test(trimmed)) return { alt: '', width: parseInt(trimmed, 10) }
+  // String hint → alt text
+  return { alt: trimmed }
+}
+
+/**
+ * Process a text node value, splitting it on ![[...]] embeds.
+ * Returns null if no embeds are found (caller keeps the original node).
+ * Returns an array of replacement nodes otherwise.
+ */
+function processText(
+  text: string,
+  noteDir: string,
+  vaultDir: string,
+): any[] | null {
+  const parts: any[] = []
+  let lastIndex = 0
+  let found = false
+
+  EMBED_RE.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = EMBED_RE.exec(text)) !== null) {
+    found = true
+    const [fullMatch, rawFilename, hint] = match
+    const matchStart = match.index
+    const filename = rawFilename.trim()
+
+    // Text before this embed
+    if (matchStart > lastIndex) {
+      parts.push({ type: 'text', value: text.slice(lastIndex, matchStart) })
+    }
+
+    const ext = extOf(filename)
+    const absPath = resolveVaultAsset(filename, noteDir, vaultDir)
+
+    if (!absPath) {
+      // File not found — preserve raw text so the author can see it's broken
+      parts.push({ type: 'text', value: fullMatch })
+    } else if (IMAGE_EXTS.has(ext)) {
+      const { alt, width, height } = parseHint(hint)
+      // Relative path from note directory → what Astro's remark-collect-images expects
+      const url = relative(noteDir, absPath)
+      const node: any = { type: 'image', url, alt, title: null }
+      if (width !== undefined) {
+        node.data = { hProperties: { width, ...(height !== undefined ? { height } : {}) } }
+      }
+      parts.push(node)
+    } else if (AUDIO_EXTS.has(ext)) {
+      const basename = filename.split('/').pop() ?? filename
+      pendingMediaCopies.add(absPath)
+      parts.push({
+        type: 'html',
+        value: `<audio controls src="/media/${basename}"><p>Audio: ${basename}</p></audio>`,
+      })
+    } else if (VIDEO_EXTS.has(ext)) {
+      const basename = filename.split('/').pop() ?? filename
+      pendingMediaCopies.add(absPath)
+      parts.push({
+        type: 'html',
+        value: `<video controls src="/media/${basename}"><p>Video: ${basename}</p></video>`,
+      })
+    } else {
+      // Unsupported type — preserve raw text
+      parts.push({ type: 'text', value: fullMatch })
+    }
+
+    lastIndex = matchStart + fullMatch.length
+  }
+
+  if (!found) return null
+
+  // Remaining text after last embed
+  if (lastIndex < text.length) {
+    parts.push({ type: 'text', value: text.slice(lastIndex) })
+  }
+
+  return parts
+}
+
+/**
+ * Minimal tree walker — visits all nodes of a given type.
+ * Avoids external `unist-util-visit` dependency.
+ */
+function walkTree(node: any, type: string, fn: (node: any) => void): void {
+  if (node.type === type) fn(node)
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) walkTree(child, type, fn)
+  }
+}
+
+/**
+ * Rewrite a featured_image value the same way the remark plugin does at render time.
+ * Safe to call from Astro templates — returns /media/<basename> for [[wiki links]],
+ * leaves relative/absolute paths and URLs unchanged, returns undefined for no value.
+ */
+export function resolveWikiImage(value: string | undefined): string | undefined {
+  if (!value) return undefined
+  const m = /^\[\[([^\]#|]+?)(?:\|[^\]]*)?\]\]$/.exec(value)
+  if (!m) return value
+  const basename = m[1].trim().split('/').pop() ?? m[1].trim()
+  return `/media/${basename}`
+}
+
+export interface ObsidianEmbedsOptions {
+  vaultDir: string
+}
+
+export function remarkObsidianEmbeds(options: ObsidianEmbedsOptions) {
+  return function transformer(tree: any, file: any): void {
+    // Derive note directory from VFile path (populated by Astro's glob loader)
+    // Fall back to vaultDir if file.path is unavailable (e.g., in test contexts)
+    const notePath: string | undefined = file?.path
+    const noteDir = notePath ? dirname(resolve(notePath)) : options.vaultDir
+
+    // Resolve [[wiki links]] in featured_image frontmatter field.
+    // file.data.astro.frontmatter is populated by Astro before remark plugins run.
+    const fm = (file as any)?.data?.astro?.frontmatter
+    if (fm?.featured_image && typeof fm.featured_image === 'string') {
+      const wikiMatch = /^\[\[([^\]#|]+?)(?:\|[^\]]*)?\]\]$/.exec(fm.featured_image)
+      if (wikiMatch) {
+        const filename = wikiMatch[1].trim()
+        const absPath = resolveVaultAsset(filename, noteDir, options.vaultDir)
+        if (absPath) {
+          const basename = filename.split('/').pop() ?? filename
+          pendingMediaCopies.add(absPath)
+          fm.featured_image = `/media/${basename}`
+        }
+      }
+    }
+
+    // Visit paragraph nodes only — ![[...]] inside code/inlineCode are never paragraphs,
+    // so this naturally skips code blocks without needing ancestor traversal.
+    walkTree(tree, 'paragraph', (para: any) => {
+      let changed = false
+      const newChildren: any[] = []
+
+      for (const child of para.children) {
+        if (child.type !== 'text') {
+          newChildren.push(child)
+          continue
+        }
+
+        const replacements = processText(child.value, noteDir, options.vaultDir)
+        if (replacements === null) {
+          newChildren.push(child)
+        } else {
+          newChildren.push(...replacements)
+          changed = true
+        }
+      }
+
+      if (changed) {
+        para.children = newChildren
+      }
+    })
+  }
+}