vocs 2.1.12 → 2.2.1

package/src/internal/markdown-imports.ts

@@ -0,0 +1,154 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type * as Estree from 'estree'
+import type * as MdAst from 'mdast'
+import remarkMdx from 'remark-mdx'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
+
+type MdxEsm = MdAst.RootContent & {
+  type: 'mdxjsEsm'
+  data?: {
+    estree?: Estree.Program
+  }
+}
+
+type MdxJsxElement = MdAst.RootContent & {
+  type: 'mdxJsxFlowElement' | 'mdxJsxTextElement'
+  attributes?: unknown[]
+  children?: MdAst.RootContent[]
+  name?: string | null
+}
+
+type MarkdownImport = {
+  source: string
+}
+
+type Replacement = {
+  end: number
+  start: number
+  value: string
+}
+
+export function inlineMarkdownImports(source: string, filePath: string): string {
+  return inline(source, path.resolve(filePath), new Set())
+}
+
+function inline(source: string, filePath: string, seen: Set<string>): string {
+  if (seen.has(filePath)) return ''
+  seen.add(filePath)
+
+  let tree: MdAst.Root
+  try {
+    tree = unified().use(remarkParse).use(remarkMdx).parse(source)
+  } catch {
+    return source
+  }
+
+  const imports = new Map<string, MarkdownImport>()
+  const replacements: Replacement[] = []
+
+  collectImports(tree.children, imports, replacements)
+  collectComponentReplacements(tree, imports, filePath, seen, replacements)
+
+  if (replacements.length === 0) return source
+  return applyReplacements(source, replacements)
+}
+
+function collectImports(
+  children: MdAst.RootContent[],
+  imports: Map<string, MarkdownImport>,
+  replacements: Replacement[],
+) {
+  for (const node of children) {
+    if (node.type !== 'mdxjsEsm') continue
+
+    const mdxEsm = node as MdxEsm
+    const declarations = mdxEsm.data?.estree?.body.filter(
+      (statement): statement is Estree.ImportDeclaration => statement.type === 'ImportDeclaration',
+    )
+    if (!declarations || declarations.length === 0) continue
+
+    let markdownDeclarations = 0
+    for (const declaration of declarations) {
+      const source = declaration.source.value
+      if (typeof source !== 'string' || !isMarkdownImport(source)) continue
+      markdownDeclarations++
+
+      const specifier = declaration.specifiers.find(
+        (specifier): specifier is Estree.ImportDefaultSpecifier =>
+          specifier.type === 'ImportDefaultSpecifier',
+      )
+      if (!specifier) continue
+      imports.set(specifier.local.name, { source })
+    }
+
+    if (markdownDeclarations === declarations.length) {
+      const replacement = toReplacement(node, '')
+      if (replacement) replacements.push(replacement)
+    }
+  }
+}
+
+function collectComponentReplacements(
+  node: MdAst.Root | MdAst.RootContent,
+  imports: Map<string, MarkdownImport>,
+  filePath: string,
+  seen: Set<string>,
+  replacements: Replacement[],
+) {
+  if (isMdxJsxElement(node)) {
+    const name = node.name ?? undefined
+    const markdownImport = name ? imports.get(name) : undefined
+    if (markdownImport && isStaticMdxComponent(node)) {
+      const importedPath = resolveMarkdownImport(markdownImport.source, filePath)
+      if (importedPath) {
+        const importedSource = fs.readFileSync(importedPath, 'utf-8')
+        const value = inline(importedSource, importedPath, new Set(seen))
+        const replacement = toReplacement(node, value)
+        if (replacement) replacements.push(replacement)
+      }
+    }
+  }
+
+  if ('children' in node && Array.isArray(node.children))
+    for (const child of node.children)
+      collectComponentReplacements(child, imports, filePath, seen, replacements)
+}
+
+function isMdxJsxElement(node: MdAst.Root | MdAst.RootContent): node is MdxJsxElement {
+  return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement'
+}
+
+function isStaticMdxComponent(node: MdxJsxElement): boolean {
+  return (node.attributes?.length ?? 0) === 0 && (node.children?.length ?? 0) === 0
+}
+
+function resolveMarkdownImport(source: string, filePath: string): string | undefined {
+  if (!source.startsWith('.') && !path.isAbsolute(source)) return undefined
+
+  const resolved = path.isAbsolute(source) ? source : path.resolve(path.dirname(filePath), source)
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved
+  return undefined
+}
+
+function isMarkdownImport(source: string): boolean {
+  return /\.(md|mdx)$/.test(source)
+}
+
+function toReplacement(
+  node: MdAst.Root | MdAst.RootContent,
+  value: string,
+): Replacement | undefined {
+  const start = node.position?.start.offset
+  const end = node.position?.end.offset
+  if (start === undefined || end === undefined) return undefined
+  return { end, start, value }
+}
+
+function applyReplacements(source: string, replacements: Replacement[]): string {
+  let result = source
+  for (const replacement of replacements.sort((a, b) => b.start - a.start))
+    result = result.slice(0, replacement.start) + replacement.value + result.slice(replacement.end)
+  return result
+}

package/src/internal/search.client.ts

@@ -1,3 +1,9 @@
+import type {
+  Options as MiniSearchOptions,
+  SearchOptions as MiniSearchSearchOptions,
+} from 'minisearch'
+import type * as Config from './config.js'
+
 export const searchFields = ['category', 'subtitle', 'text', 'title', 'titles'] as const
 export const storeFields = [
   'category',
@@ -40,3 +46,26 @@ export function tokenize(text: string): string[] {
 
   return tokens.filter((w) => w.length > 0)
 }
+
+export namespace SearchConfig {
+  export function getIndexOptions(config?: Config.Config): MiniSearchOptions {
+    const index = config?.search.index ?? {}
+    return {
+      ...index,
+      fields: index.fields ? [...index.fields] : [...searchFields],
+      storeFields: mergeStoreFields(index.storeFields),
+      tokenize: index.tokenize ?? tokenize,
+    }
+  }
+
+  export function getQueryOptions(config: Config.Config): MiniSearchSearchOptions {
+    return {
+      ...config.search.query,
+      tokenize: config.search.query?.tokenize ?? config.search.index?.tokenize ?? tokenize,
+    }
+  }
+
+  function mergeStoreFields(fields: readonly string[] | undefined): string[] {
+    return [...new Set([...storeFields, ...(fields ?? [])])]
+  }
+}

package/src/internal/search.test.ts

@@ -1,3 +1,6 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
 import type * as MdAst from 'mdast'
 import { describe, expect, it } from 'vitest'
 import * as Config from './config.js'
@@ -859,6 +862,40 @@ Some content here.
   })
 })
 
+describe('SearchDocuments.fromConfig', () => {
+  it('indexes imported markdown content from file-backed pages', async () => {
+    const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vocs-search-'))
+    const pagesDir = path.join(rootDir, 'src/pages')
+    fs.mkdirSync(pagesDir, { recursive: true })
+
+    fs.writeFileSync(
+      path.join(rootDir, 'notes.md'),
+      '# Notes\n\nSome indexable prose about widgets and links.',
+    )
+    fs.writeFileSync(
+      path.join(pagesDir, 'notes.mdx'),
+      `---
+title: Notes
+---
+
+import Notes from '../../notes.md'
+
+<Notes />`,
+    )
+
+    const documents = await Search.SearchDocuments.fromConfig(Config.define({ rootDir }))
+
+    expect(documents).toContainEqual(
+      expect.objectContaining({
+        href: '/notes#notes',
+        text: ' Some indexable prose about widgets and links.',
+        title: 'Notes',
+        type: 'page',
+      }),
+    )
+  })
+})
+
 describe('Search fields and storeFields', () => {
   it('exports search fields', () => {
     expect(Search.searchFields).toMatchInlineSnapshot(`
@@ -902,6 +939,65 @@ describe('Config.search defaults', () => {
     expect(config.search.fuzzy).toBe(0.2)
     expect(config.search.prefix).toBe(true)
     expect(typeof config.search.boostDocument).toBe('function')
+    expect(config.search.query?.boost).toEqual(config.search.boost)
+    expect(config.search.query?.fuzzy).toBe(0.2)
+    expect(config.search.query?.prefix).toBe(true)
+  })
+
+  it('normalizes legacy search options into query options', () => {
+    const config = Config.define({
+      search: {
+        boost: { text: 10 },
+        combineWith: 'OR',
+        fuzzy: false,
+        prefix: false,
+      },
+    })
+
+    expect(config.search.query?.boost).toMatchObject({ title: 4, text: 10 })
+    expect(config.search.query?.combineWith).toBe('OR')
+    expect(config.search.query?.fuzzy).toBe(false)
+    expect(config.search.query?.prefix).toBe(false)
+  })
+})
+
+describe('SearchConfig', () => {
+  it('returns default index options', () => {
+    expect(Search.SearchConfig.getIndexOptions(config)).toMatchObject({
+      fields: ['category', 'subtitle', 'text', 'title', 'titles'],
+      storeFields: [
+        'category',
+        'href',
+        'searchPriority',
+        'subtitle',
+        'text',
+        'title',
+        'titles',
+        'type',
+      ],
+    })
+  })
+
+  it('keeps required store fields when custom store fields are configured', () => {
+    const config = Config.define({
+      search: {
+        index: {
+          storeFields: ['href', 'custom'],
+        },
+      },
+    })
+
+    expect(Search.SearchConfig.getIndexOptions(config).storeFields).toEqual([
+      'category',
+      'href',
+      'searchPriority',
+      'subtitle',
+      'text',
+      'title',
+      'titles',
+      'type',
+      'custom',
+    ])
   })
 })
 
@@ -1006,6 +1102,105 @@ describe('SearchIndex.fromSearchDocuments', () => {
     expect(results[0]?.score).toBeGreaterThan(results[1]?.score ?? 0)
   })
 
+  it('indexes custom virtual fields', () => {
+    const docs: SearchDocuments.Document[] = [
+      {
+        category: '',
+        href: '/docs/runtime-api',
+        id: '/docs/runtime-api.mdx#runtime-api',
+        searchPriority: undefined,
+        subtitle: '',
+        text: 'Reference content.',
+        title: 'Runtime API',
+        titles: [],
+        type: 'page',
+      },
+    ]
+    const config = Config.define({
+      search: {
+        index: {
+          fields: ['path'],
+          extractField(document, fieldName) {
+            if (fieldName === 'path') return document.href
+            return document[fieldName as keyof typeof document]
+          },
+        },
+      },
+    })
+
+    const index = SearchIndex.fromSearchDocuments(docs, config)
+
+    expect(index.search('runtime', Search.SearchConfig.getQueryOptions(config))[0]?.id).toBe(
+      '/docs/runtime-api.mdx#runtime-api',
+    )
+  })
+
+  it('stores custom fields', () => {
+    const docs: SearchDocuments.Document[] = [
+      {
+        category: 'Docs',
+        href: '/guide',
+        id: '/docs/guide.mdx#guide',
+        searchPriority: undefined,
+        subtitle: '',
+        text: 'Install instructions.',
+        title: 'Guide',
+        titles: [],
+        type: 'page',
+      },
+    ]
+    const config = Config.define({
+      search: {
+        index: {
+          storeFields: ['path'],
+          extractField(document, fieldName) {
+            if (fieldName === 'path') return document.href
+            return document[fieldName as keyof typeof document]
+          },
+        },
+      },
+    })
+
+    const index = SearchIndex.fromSearchDocuments(docs, config)
+    const result = index.search('guide', Search.SearchConfig.getQueryOptions(config))[0]
+
+    expect(result).toMatchObject({ href: '/guide', path: '/guide', title: 'Guide' })
+  })
+
+  it('applies query fields, weights, and filter at runtime', () => {
+    const docs = [
+      ...buildDoc(
+        '/docs/title.mdx',
+        '/title',
+        `# Alpha
+
+No keyword.
+`,
+      ),
+      ...buildDoc(
+        '/docs/text.mdx',
+        '/text',
+        `# Other
+
+Alpha keyword.
+`,
+      ),
+    ]
+    const config = Config.define({
+      search: {
+        query: {
+          fields: ['text'],
+          filter: (result) => result.id !== '/docs/text.mdx#other',
+          weights: { fuzzy: 0.5, prefix: 0.5 },
+        },
+      },
+    })
+
+    const index = SearchIndex.fromSearchDocuments(docs, config)
+
+    expect(index.search('alpha', Search.SearchConfig.getQueryOptions(config))).toEqual([])
+  })
+
   it('boosts shallow paths over deep paths', () => {
     const shallowDoc: SearchDocuments.Document = {
       category: '',

package/src/internal/search.ts

@@ -14,11 +14,12 @@ import { unified } from 'unified'
 import * as UnistUtil from 'unist-util-visit'
 import * as yaml from 'yaml'
 import type * as Config from './config.js'
+import * as MarkdownImports from './markdown-imports.js'
 import { extractSubheading, getPhrasingContentText } from './mdx.js'
 import * as OpenApiRegistry from './openapi/registry.js'
 import * as OpenApiSearch from './openapi/search.js'
 import * as Path from './path.js'
-import { searchFields, storeFields, tokenize } from './search.client.js'
+import { SearchConfig } from './search.client.js'
 import * as Sidebar from './sidebar.js'
 import * as TaskRunner from './task-runner.js'
 import * as TopNav from './topNav.js'
@@ -61,7 +62,8 @@ export namespace SearchDocuments {
     for (const page of mdxPages)
       taskRunner.run(async () => {
         const filePath = path.join(pagesDirPath, page)
-        const content = await fs.promises.readFile(filePath, 'utf-8')
+        const rawContent = await fs.promises.readFile(filePath, 'utf-8')
+        const content = MarkdownImports.inlineMarkdownImports(rawContent, filePath)
 
         const { searchPriority, sections } = extract(content, config)
         if (sections.length === 0) return
@@ -206,12 +208,11 @@ export namespace SearchIndex {
   /**
    * Create a search index from documents.
    */
-  export function fromSearchDocuments(documents: SearchDocuments.Document[]): SearchIndex {
-    const index = new MiniSearch<SearchDocuments.Document>({
-      fields: [...searchFields],
-      storeFields: [...storeFields],
-      tokenize,
-    })
+  export function fromSearchDocuments(
+    documents: SearchDocuments.Document[],
+    config?: Config.Config,
+  ): SearchIndex {
+    const index = new MiniSearch<SearchDocuments.Document>(SearchConfig.getIndexOptions(config))
     index.addAll(documents)
     return index
   }
@@ -220,17 +221,15 @@ export namespace SearchIndex {
    * Load a search index from a JSON file.
    */
   export function loadFromFile(options: loadFromFile.Options): SearchIndex {
-    const { filePath } = options
+    const { config, filePath } = options
 
     const json = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
-    return MiniSearch.loadJSON(json, {
-      fields: [...searchFields],
-      storeFields: [...storeFields],
-    })
+    return MiniSearch.loadJSON(json, SearchConfig.getIndexOptions(config))
   }
 
   export declare namespace loadFromFile {
     type Options = {
+      config?: Config.Config
       filePath: string
     }
   }
@@ -260,7 +259,8 @@ export namespace SearchIndex {
   ): string[] {
     const { pagesDir, previousIds = [], config } = options
 
-    const content = fs.readFileSync(filePath, 'utf-8')
+    const rawContent = fs.readFileSync(filePath, 'utf-8')
+    const content = MarkdownImports.inlineMarkdownImports(rawContent, filePath)
     const { searchPriority, sections } = extract(content, config)
 
     // Remove old entries for this file

package/src/internal/vite-plugins.ts

@@ -636,7 +636,7 @@ export function search(config: Config.Config): PluginOption {
   async function buildIndex(): Promise<SearchIndex.SearchIndex> {
     logger.info('Building search index...', { timestamp: true })
     const docs = await SearchDocuments.fromConfig(config)
-    const index = SearchIndex.fromSearchDocuments(docs)
+    const index = SearchIndex.fromSearchDocuments(docs, config)
 
     // Populate fileIds map for HMR
     for (const doc of docs) {

package/src/react/Link.tsx

@@ -1,7 +1,8 @@
 'use client'
 
-import { useEffect, useState } from 'react'
-import { useRouter, Link as WakuLink } from 'waku'
+import { useContext, useEffect, useState } from 'react'
+import { Link as WakuLink } from 'waku'
+import { unstable_RouterContext as WakuRouterContext } from 'waku/router/client'
 import * as Path from '../internal/path.js'
 
 const viewportPrefetchDelayMs = 2_000
@@ -57,14 +58,18 @@ function useViewportPrefetchReady(enabled: boolean) {
 
 export function Link(props: Link.Props) {
   const { to, unstable_prefetchOnEnter = true, unstable_prefetchOnView = true, ...rest } = props
-  const { path } = useRouter()
-  const prefetchOnView = useViewportPrefetchReady(Boolean(unstable_prefetchOnView))
+  const router = useContext(WakuRouterContext)
+  const routerPath = router?.route.path
+  const isExternal = Path.isExternal(props.to)
+  const prefetchOnView = useViewportPrefetchReady(
+    Boolean(unstable_prefetchOnView) && !isExternal && routerPath !== undefined,
+  )
 
-  if (Path.isExternal(props.to))
-    return <a {...rest} href={props.to} rel="noopener noreferrer" target="_blank" />
+  if (isExternal) return <a {...rest} href={props.to} rel="noopener noreferrer" target="_blank" />
 
   const [before, after] = (props.to || '').split('#')
-  const resolvedTo = `${before ? before : path}${after ? `#${after}` : ''}`
+  const resolvedTo = `${before ? before : (routerPath ?? '')}${after ? `#${after}` : ''}`
+  if (routerPath === undefined) return <a {...rest} href={resolvedTo || props.to} />
   return (
     <WakuLink
       {...rest}

package/src/react/internal/Search.tsx

@@ -11,7 +11,7 @@ import LucideFile from '~icons/lucide/file'
 import LucideHash from '~icons/lucide/hash'
 import LucideSearch from '~icons/lucide/search'
 import * as Path from '../../internal/path.js'
-import { searchFields, storeFields, tokenize } from '../../internal/search.client.js'
+import { SearchConfig } from '../../internal/search.client.js'
 import { Link } from '../Link.js'
 import { useConfig } from '../useConfig.js'
 import { DialogTrigger } from './DialogTrigger.js'
@@ -86,14 +86,12 @@ export function Search(props: Search.Props) {
         const json = await getSearchIndex()
         setIndex(
           MiniSearch.loadJSON<SearchResult>(json, {
-            fields: [...searchFields],
-            storeFields: [...storeFields],
-            tokenize,
+            ...SearchConfig.getIndexOptions(config),
           }),
         )
       })
       .catch((error) => console.error('Failed to load search index:', error))
-  }, [open, index])
+  }, [open, index, config])
 
   React.useEffect(() => {
     try {
@@ -108,12 +106,11 @@ export function Search(props: Search.Props) {
       return
     }
 
-    const results = (index.search(query, { ...config.search, tokenize }) as SearchResult[]).slice(
-      0,
-      20,
-    )
+    const results = (
+      index.search(query, SearchConfig.getQueryOptions(config)) as SearchResult[]
+    ).slice(0, 20)
     setSearch((s) => ({ ...s, results, selectedIndex: 0 }))
-  }, [query, index, config.search])
+  }, [query, index, config])
 
   React.useEffect(() => {
     if (disableKeyboardShortcut) return