@kirchdev/duxt 0.7.0 → 0.8.0

package/build/sources/documentation-media.ts

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync
+} from 'node:fs';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { resolvesInside } from '../sections/section-input';
+
+const PRIVATE_DIRECTORIES = new Set([
+  '.git',
+  'node_modules',
+  '.data',
+  '.nuxt',
+  '.output',
+  '.turbo',
+  '.cache'
+]);
+
+const IMAGES = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.svg',
+  '.webp',
+  '.avif',
+  '.apng',
+  '.ico'
+]);
+
+export const documentationMediaDirectory = (root = process.cwd()) =>
+  join(root, '.data/duxt-media/public');
+
+export interface DocumentationMedia {
+  root: string;
+  prefix: string;
+  files: string[];
+}
+
+/** Publish only image outputs in _assets, leaving capture sources private. */
+export function publishDocumentationMedia(
+  root: string,
+  output: string,
+  identity: string,
+  checkout?: string
+): DocumentationMedia {
+  const prefix = `/_duxt/media/${createHash('sha256').update(identity).digest('hex')}`;
+  const media: DocumentationMedia = { root, prefix, files: [] };
+  if (!existsSync(root) || lstatSync(root).isSymbolicLink()) return media;
+  if (checkout && !resolvesInside(root, checkout)) return media;
+  const outputRoot = resolve(output);
+  const descend = (directory: string, asset = false) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const absolute = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (
+          !PRIVATE_DIRECTORIES.has(entry.name) &&
+          resolve(absolute) !== outputRoot
+        )
+          descend(absolute, asset || entry.name === '_assets');
+      } else if (
+        asset &&
+        entry.isFile() &&
+        IMAGES.has(extname(entry.name).toLowerCase())
+      ) {
+        const target = join(output, prefix, relative(root, absolute));
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(absolute, target);
+        media.files.push(relative(root, absolute).split(sep).join('/'));
+      }
+    }
+  };
+  descend(root);
+  return media;
+}
+
+/** Resolve file-relative documentation images; external/public images pass through. */
+export function documentationImageUrl(
+  value: string,
+  file: string,
+  media: DocumentationMedia
+): string {
+  if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(value)) return value;
+  const owner = relative(media.root, file);
+  if (owner === '..' || owner.startsWith(`..${sep}`)) return value;
+  const match = /^([^?#]*)(.*)$/.exec(value)!;
+  let path: string;
+  try {
+    path = decodeURIComponent(match[1]!);
+  } catch {
+    return value;
+  }
+  const absolute = path.startsWith('/')
+    ? resolve(media.root, `.${path}`)
+    : resolve(dirname(file), path);
+  const rel = relative(media.root, absolute).split(sep).join('/');
+  if (
+    rel.startsWith('../') ||
+    rel === '..' ||
+    !rel.split('/').includes('_assets') ||
+    !media.files.includes(rel)
+  )
+    return value;
+  return `${media.prefix}/${rel.split('/').map(encodeURIComponent).join('/')}${match[2]}`;
+}
+
+/** Rewrite only image nodes in Content's compressed MDC tree. */
+export function rewriteDocumentationImages(
+  content: Record<string, unknown>,
+  file: string,
+  media: DocumentationMedia
+): void {
+  const walk = (node: unknown) => {
+    if (Array.isArray(node)) {
+      const [tag, props] = node;
+      if (
+        ['img', 'prose-img', 'ProseImg'].includes(tag) &&
+        props &&
+        typeof props === 'object'
+      ) {
+        for (const key of ['src', 'dark']) {
+          if (typeof props[key] === 'string')
+            props[key] = documentationImageUrl(props[key], file, media);
+        }
+      }
+      for (const child of node) walk(child);
+    } else if (node && typeof node === 'object') {
+      for (const child of Object.values(node)) walk(child);
+    }
+  };
+  walk(content.body);
+}

package/build/sources/sources.ts

@@ -14,6 +14,10 @@ import { resolveLatestRefs } from './sources-git';
 // module could reach it without this file's imports coming with it.
 import { repositoryRoot } from './repository-root';
 import { resolvesInside } from '../sections/section-input';
+import {
+  documentationMediaDirectory,
+  publishDocumentationMedia
+} from './documentation-media';
 export { repositoryRoot };
 export type {
   DuxtResolvedSource,
@@ -232,7 +236,9 @@ const excluded = (source: DuxtSource) => {
   const partials = source.exclude?.partials ?? PARTIALS;
   const drafts = source.exclude?.drafts ?? DRAFTS;
 
-  return includeDrafts() ? [partials] : [partials, drafts];
+  return includeDrafts()
+    ? [partials, '**/_assets/**']
+    : [partials, '**/_assets/**', drafts];
 };
 
 /**
@@ -315,6 +321,20 @@ export function duxtSources(
 
     containedKeys(collection);
 
+    const base = source.path ?? 'docs';
+    const mediaPath =
+      effective.path === base || effective.path.startsWith(`${base}/`)
+        ? base
+        : effective.path;
+    const identity = JSON.stringify([
+      effective.repo ?? repositoryRoot(),
+      mediaPath,
+      usedRef ? [refIsTag(usedRef) ? 'tag' : 'branch', refName(usedRef)] : null
+    ]);
+    for (const contentSource of collection.source ?? []) {
+      prepareMedia(contentSource, effective.repo, mediaPath, identity);
+    }
+
     collections[entry.collection] = collection;
   });
 
@@ -327,6 +347,37 @@ export function duxtSources(
   return collections;
 }
 
+/** Prepare media for a source, including partial sources sharing a collection. */
+function prepareMedia(
+  contentSource: NonNullable<
+    ReturnType<typeof defineCollection>['source']
+  >[number],
+  repo: string | undefined,
+  mediaPath: string,
+  identity: string
+) {
+  const output = documentationMediaDirectory();
+  const keys = contentSource.getKeys!;
+  const prepared = contentSource as typeof contentSource & {
+    duxtMediaIdentity?: string;
+    duxtMedia?: import('./documentation-media').DocumentationMedia;
+  };
+  // Include source ownership in Content's checksum, even when Markdown is unchanged.
+  prepared.duxtMediaIdentity = identity;
+  contentSource.getKeys = async () => {
+    const root = repo
+      ? join(contentSource.cwd, mediaPath)
+      : join(repositoryRoot(), mediaPath);
+    prepared.duxtMedia = publishDocumentationMedia(
+      root,
+      output,
+      identity,
+      repo ? contentSource.cwd : undefined
+    );
+    return keys();
+  };
+}
+
 /**
  * Keep a downloaded repository's keys to files that are inside its checkout.
  *
@@ -367,11 +418,11 @@ function partialFolders(
   expanded: ReturnType<typeof expandSources>
 ): Map<
   string | undefined,
-  { repo?: string; path: string; partials: string }[]
+  { repo?: string; path: string; partials: string; mediaPath: string }[]
 > {
   const byLocale = new Map<
     string | undefined,
-    { repo?: string; path: string; partials: string }[]
+    { repo?: string; path: string; partials: string; mediaPath: string }[]
   >();
   const seen = new Set<string>();
 
@@ -389,7 +440,17 @@ function partialFolders(
     seen.add(claim);
 
     const list = byLocale.get(key) ?? [];
-    list.push({ repo: effective.repo, path: effective.path, partials });
+    const base = source.path ?? 'docs';
+    const mediaPath =
+      effective.path === base || effective.path.startsWith(`${base}/`)
+        ? base
+        : effective.path;
+    list.push({
+      repo: effective.repo,
+      path: effective.path,
+      partials,
+      mediaPath
+    });
     byLocale.set(key, list);
   });
 
@@ -411,7 +472,12 @@ function partialFolders(
  * than resolves; see `modules/validate.ts`.
  */
 function definePartials(
-  folders: { repo?: string; path: string; partials: string }[]
+  folders: {
+    repo?: string;
+    path: string;
+    partials: string;
+    mediaPath: string;
+  }[]
 ) {
   const entries = folders.map((folder) =>
     folder.repo
@@ -438,6 +504,16 @@ function definePartials(
   });
 
   containedKeys(collection);
+  for (const [index, contentSource] of (collection.source ?? []).entries()) {
+    const folder = folders[index]!;
+    // Partials stay shared across versions and read the repository's default ref.
+    const identity = JSON.stringify([
+      folder.repo ?? repositoryRoot(),
+      folder.mediaPath,
+      null
+    ]);
+    prepareMedia(contentSource, folder.repo, folder.mediaPath, identity);
+  }
 
   return collection;
 }

package/modules/documentation-media.ts

@@ -0,0 +1,50 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import type { Nuxt } from '@nuxt/schema';
+import type { ModuleOptions } from '@nuxt/image';
+import {
+  documentationMediaDirectory,
+  rewriteDocumentationImages
+} from '../build/sources/documentation-media';
+import type { DocumentationMedia } from '../build/sources/documentation-media';
+
+interface ParseContext {
+  file?: { path?: string };
+  content?: Record<string, unknown>;
+  collection?: { source?: { duxtMedia?: DocumentationMedia }[] };
+}
+
+export default function duxtDocumentationMedia(_options: unknown, nuxt: Nuxt) {
+  const directory = documentationMediaDirectory(nuxt.options.rootDir);
+  // Rebuild the generated output even when Content reuses every parsed page.
+  // Removed source assets must not survive a later build of the same ref.
+  rmSync(directory, { recursive: true, force: true });
+  mkdirSync(directory, { recursive: true });
+  const image = nuxt.options.image as
+    | Partial<ModuleOptions>
+    | false
+    | undefined;
+  if (image !== false) {
+    const options = image ?? {};
+    options.dirs = [...(options.dirs ?? []), directory];
+    nuxt.options.image = options as ModuleOptions;
+  }
+
+  nuxt.hook('nitro:config', (nitro) => {
+    nitro.publicAssets ??= [];
+    if (!nitro.publicAssets.some((asset) => asset?.dir === directory)) {
+      nitro.publicAssets.push({ dir: directory, maxAge: 0 });
+    }
+  });
+
+  nuxt.hook(
+    'content:file:afterParse' as never,
+    ((context: ParseContext) => {
+      const file = context.file?.path;
+      if (!file || !context.content) return;
+      for (const source of context.collection?.source ?? []) {
+        const media = source.duxtMedia;
+        if (media) rewriteDocumentationImages(context.content, file, media);
+      }
+    }) as never
+  );
+}

package/nuxt.config.ts

@@ -252,6 +252,9 @@ export default defineNuxtConfig({
     // history at parse time.
     layer('./modules/git-meta.ts'),
 
+    // Mount documentation media before @nuxt/image discovers its input dirs.
+    layer('./modules/documentation-media.ts'),
+
     // `redirectFrom:` in a page's frontmatter, under every prefix the site
     // serves that page at.
     layer('./modules/redirects.ts'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@kirchdev/duxt",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "duxt is a Nuxt layer: extend it and your docs/ folder becomes a site, with theme, search, API reference and llms.txt included. Point it at other repositories, or at tags of the same one, and each becomes a version.",
   "keywords": [
     "content-v3",
@@ -75,10 +75,10 @@
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.14",
     "@iconify-json/flag": "^1.2.12",
-    "@iconify-json/lucide": "^1.2.141",
+    "@iconify-json/lucide": "^1.2.142",
     "@iconify-json/simple-icons": "^1.2.99",
     "@lezer/highlight": "^1.2.5",
-    "@lucide/vue": "^1.53.0",
+    "@lucide/vue": "^1.54.0",
     "@nuxt/content": "^3.16.1",
     "@nuxt/icon": "^2.5.1",
     "@nuxt/image": "^2.1.0",
@@ -98,7 +98,7 @@
     "jiti": "^2.7.0",
     "mermaid": "^12.1.0",
     "reka-ui": "^2.11.0",
-    "satori": "^0.44.0",
+    "satori": "^0.47.1",
     "shadcn-nuxt": "^2.8.2",
     "shiki": "^4.5.0",
     "tailwind-merge": "^3.7.0",
@@ -110,7 +110,7 @@
   },
   "devDependencies": {
     "@types/jsdom": "^30.0.0",
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "jsdom": "^30.1.2",
     "nuxt": "^4.6.0",
     "typescript": "^6.0.3",