feat: extend content config

Author: farnabaz

modules/config.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync } from 'node:fs'
-import { defineNuxtModule, useLogger } from '@nuxt/kit'
+import { addServerImports, createResolver, defineNuxtModule, useLogger } from '@nuxt/kit'
 import { defu } from 'defu'
 import { resolveContentDir } from '../utils/content-dir'
 import { getGitBranch, getGitEnv, getGitRoot, getLocalGitInfo } from '../utils/git'
@@ -37,7 +37,16 @@ export default defineNuxtModule<ComarkDocsOptions>({
     isr: 300,
   },
   async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url)
     const rootDir = nuxt.options.rootDir
+
+    addServerImports([
+      {
+        name: 'extendContent',
+        from: resolver.resolve('../server/internal/extend-content'),
+        priority: -1,
+      },
+    ])
     // Untyped view: `site` (nuxt-site-config) and `appConfig` aren't typed until app.config is generated.
     const nuxtOptions = nuxt.options as typeof nuxt.options & {
       site?: { url?: string; name?: string }

playground/server/utils/content.ts

@@ -0,0 +1,6 @@
+import type { ContentOptions } from 'comark-content'
+
+export function extendContent(options: ContentOptions): ContentOptions {
+  console.log('[playground] extendContent override applied, sources:', Object.keys(options.sources || {}))
+  return options
+}

server/internal/extend-content.ts

@@ -0,0 +1,14 @@
+import type { ContentOptions } from 'comark-content'
+
+/**
+ * Default (no-op) hook over the options `createSourceContent` builds for every content instance.
+ *
+ * Consumers override it by exporting a function of the same name from their own `server/utils/`:
+ * the layer registers this one as an auto-import with a negative priority, so a scanned export
+ * (unimport's default priority of 1) shadows it. A plain `server/utils/` file in the layer could
+ * not be shadowed — Nitro scans layer dirs *after* the consumer's, and equal-priority collisions
+ * resolve to the last one scanned.
+ */
+export function extendContent<T extends ContentOptions>(options: T): T {
+  return options
+}

server/utils/content.ts

@@ -1,4 +1,4 @@
-import { comarkContent, defineContentPlugin, type ComarkContent, type CacheOptions } from 'comark-content'
+import { type ContentOptions, defineContentPlugin, type ComarkContent, type CacheOptions, comarkContent  } from 'comark-content';
 import fs from 'comark-content/sources/fs'
 import github from 'comark-content/sources/github'
 import rangi from 'comark/plugins/rangi'
@@ -23,6 +23,7 @@ const comarkPlugins = [
   }),
 ]
 
+// Bound to THIS instance so a preview content instance serves its own version's sections, not production's.
 const searchSectionsPlugin = defineContentPlugin(() => ({
   name: 'search-sections',
   setup(ctx) {
@@ -38,7 +39,8 @@ export async function createSourceContent(
   ref: string,
   opts: { remote?: boolean; cache?: CacheOptions; basePath?: string; watch?: boolean } = {}
 ) {
-  const instance = comarkContent({
+
+  const options: any = {
     markdown: {
       plugins: comarkPlugins,
       html: false,
@@ -49,13 +51,18 @@ export async function createSourceContent(
     plugins: [searchSectionsPlugin],
     cache: opts.cache,
     basePath: opts.basePath,
-  })
+  }
+
+  // A no-op unless the consumer shadows it from their own `server/utils/`. Re-typed as the layer's own
+  // options: a consumer's hook is declared against the wide `ContentOptions`, and letting that widen the
+  // argument would erase the source and plugin types `comarkContent` infers from the literal.
+  const instance = comarkContent(extendContent(options) as ContentOptions)
 
   // Only the default instance watches: others read a fixed ref that can't change, and retaining
   // `watch()`'s stop function to release the watcher would leak once the preview entry is evicted.
   if (import.meta.dev && opts.watch) {
     await instance.watch()
-    instance.hooks.hook('watch:file:update', (_source, key) => {
+    instance.hooks.hook('watch:file:update', (_source:string, key: string) => {
       invalidateSearchSections(instance)
       console.log(`${key} updated`)
     })