fix: serve static content files and resolve image paths (#46)

* fix: return web Response from all server handlers

Nitro wraps plain return values in NodeResponse, which Bun rejects
in dev mode (nitrojs/nitro#4228). Return standard Response/Response.json
directly to bypass this. Also read readingTime from eager frontmatter
glob instead of loading full MDX module in API route.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: serve static content files via /_content route

Catch-all route serves non-md/mdx files (images, PDFs, etc.) from
the .content directory. Blocks .md/.mdx and path traversal.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: resolve image paths in MDX relative to source file

Remark plugin rewrites image src (both markdown ![](…) and JSX <img>)
to absolute /_content/ URLs based on the MD file's location within
the content directory. External URLs left untouched.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: add @types/mdast, @types/hast, mdast-util-mdx-jsx deps

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: resolve image paths in MDX and disable fumadocs remarkImage

Remark plugin resolves image src (markdown, HTML, JSX, HAST) relative
to the MD file's location. Disable fumadocs remarkImage to prevent
it from converting src to JS imports before our plugin runs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: type-safe remark-resolve-images, add @types/unist

Replace string array visit with type-checked node.type guard to
fix TS overload error. Add @types/unist to chronicle devDeps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: handle protocol-relative URLs and malformed path encoding

Skip protocol-relative URLs (//cdn.example.com) in image resolver.
Catch malformed percent-encoding in _content route safePath call.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rsbh

bun.lock

@@ -22,12 +22,16 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@raystack/tools-config": "0.56.0",
+    "@types/hast": "^3.0.4",
     "@types/lodash": "^4.17.23",
+    "@types/mdast": "^4.0.4",
     "@types/mdx": "^2.0.13",
     "@types/node": "^25.1.0",
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
     "@types/semver": "^7.7.1",
+    "@types/unist": "^3.0.3",
+    "mdast-util-mdx-jsx": "^3.2.0",
     "semver": "^7.7.4",
     "typescript": "5.9.3"
   },

packages/chronicle/package.json

@@ -0,0 +1,59 @@
+import path from 'node:path'
+import { visit } from 'unist-util-visit'
+import type { Plugin } from 'unified'
+import type { Image, Html } from 'mdast'
+import type { Element } from 'hast'
+import type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute } from 'mdast-util-mdx-jsx'
+
+function resolveUrl(src: string, dir: string): string {
+  if (/^[a-z][a-z0-9+\-.]*:/i.test(src)) return src
+  if (src.startsWith('//')) return src
+  if (src.startsWith('#')) return src
+  if (src.startsWith('/_content/')) return src
+
+  if (src.startsWith('/')) return `/_content${src}`
+  return `/_content/${path.posix.normalize(path.posix.join(dir, src))}`
+}
+
+const remarkResolveImages: Plugin = () => {
+  return (tree, file) => {
+    const filePath = file.path
+    if (!filePath) return
+
+    const contentIdx = filePath.lastIndexOf('/content/')
+    if (contentIdx === -1) return
+
+    const relative = filePath.slice(contentIdx + '/content/'.length)
+    const dir = path.posix.dirname(relative)
+
+    visit(tree, 'image', (node: Image) => {
+      if (!node.url) return
+      node.url = resolveUrl(node.url, dir)
+    })
+
+    visit(tree, 'html', (node: Html) => {
+      node.value = node.value.replace(
+        /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi,
+        (_, before, src, after) => `${before}${resolveUrl(src, dir)}${after}`
+      )
+    })
+
+    visit(tree, (node) => {
+      if (node.type !== 'mdxJsxFlowElement' && node.type !== 'mdxJsxTextElement') return
+      const jsx = node as MdxJsxFlowElement | MdxJsxTextElement
+      if (jsx.name !== 'img') return
+      const srcAttr = jsx.attributes.find((a): a is MdxJsxAttribute => a.type === 'mdxJsxAttribute' && a.name === 'src')
+      if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
+      srcAttr.value = resolveUrl(srcAttr.value, dir)
+    })
+
+    visit(tree, 'element', (node: Element) => {
+      if (node.tagName !== 'img') return
+      const src = node.properties?.src
+      if (typeof src !== 'string') return
+      node.properties.src = resolveUrl(src, dir)
+    })
+  }
+}
+
+export default remarkResolveImages

packages/chronicle/src/lib/remark-resolve-images.ts

@@ -23,6 +23,11 @@ const frontmatterGlob: Record<string, Record<string, unknown>> = import.meta.glo
   { eager: true, import: 'frontmatter' }
 );
 
+const readingTimeGlob: Record<string, { text: string; minutes: number; words: number; time: number } | undefined> = import.meta.glob(
+  '../../.content/**/*.{mdx,md}',
+  { eager: true, import: 'readingTime' }
+);
+
 const metaGlob: Record<string, Record<string, unknown>> = import.meta.glob(
   '../../.content/**/meta.json',
   { eager: true }
@@ -38,10 +43,12 @@ function buildFiles() {
   for (const [key, data] of Object.entries(frontmatterGlob)) {
     const originalPath = key.slice(CONTENT_PREFIX.length);
     const relativePath = originalPath.replace(/readme\.(mdx?)$/i, 'index.$1');
+    const rt = readingTimeGlob[key];
+    const _readingTime = rt?.minutes != null ? Math.max(1, Math.round(rt.minutes)) : undefined;
     files.push({
       type: 'page',
       path: relativePath,
-      data: { ...data, _relativePath: relativePath, _originalPath: originalPath }
+      data: { ...data, _readingTime, _relativePath: relativePath, _originalPath: originalPath }
     });
   }
 

packages/chronicle/src/lib/source.ts

@@ -51,11 +51,11 @@ export default defineHandler(async event => {
       ? await response.json()
       : await response.text();
 
-    return {
+    return Response.json({
       status: response.status,
       statusText: response.statusText,
       body: responseBody
-    };
+    });
   } catch (error) {
     const message =
       error instanceof Error

packages/chronicle/src/server/api/apis-proxy.ts

@@ -1,5 +1,5 @@
 import { defineHandler } from 'nitro';
 
 export default defineHandler(() => {
-  return { status: 'ok' };
+  return Response.json({ status: 'ok' });
 });

packages/chronicle/src/server/api/health.ts

@@ -1,5 +1,5 @@
 import { defineHandler, HTTPError } from 'nitro';
-import { getPage, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath, loadPageModule } from '@/lib/source';
+import { getPage, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 
 export default defineHandler(async event => {
   const slugParam = event.url.searchParams.get('slug') ?? '';
@@ -11,18 +11,12 @@ export default defineHandler(async event => {
   }
 
   const nav = await getPageNav(slug);
-  const originalPath = getOriginalPath(page);
-  const relativePath = getRelativePath(page);
-  const mdxModule = (originalPath || relativePath) ? await loadPageModule(originalPath || relativePath) : null;
 
-  return {
-    frontmatter: {
-      ...extractFrontmatter(page, slug[slug.length - 1]),
-      _readingTime: mdxModule?._readingTime,
-    },
-    relativePath,
-    originalPath,
+  return Response.json({
+    frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+    relativePath: getRelativePath(page),
+    originalPath: getOriginalPath(page),
     prev: nav.prev,
     next: nav.next,
-  };
+  });
 });

packages/chronicle/src/server/api/page.ts

@@ -125,21 +125,21 @@ export default defineHandler(async event => {
 
   if (!query) {
     const docs = await getDocs(ctx);
-    return docs
+    return Response.json(docs
       .filter(d => d.type === 'page')
       .slice(0, 8)
       .map(d => ({
         id: d.id,
         url: d.url,
         type: d.type,
         content: d.title
-      }));
+      })));
   }
 
-  return index.search(query).map(r => ({
+  return Response.json(index.search(query).map(r => ({
     id: r.id,
     url: r.url,
     type: r.type,
     content: r.title
-  }));
+  })));
 });

packages/chronicle/src/server/api/search.ts

@@ -15,7 +15,7 @@ export default defineHandler(async event => {
   }
 
   const apiConfigs = getApiConfigsForVersion(config, versionDir);
-  if (!apiConfigs.length) return [];
+  if (!apiConfigs.length) return Response.json([]);
 
-  return loadApiSpecs(apiConfigs);
+  return Response.json(await loadApiSpecs(apiConfigs));
 });

packages/chronicle/src/server/api/specs.ts

@@ -34,6 +34,5 @@ export default defineHandler(async event => {
     throw new HTTPError({ status: 404, message: 'Not Found' });
   }
 
-  event.res.headers.set('Content-Type', 'text/markdown; charset=utf-8');
-  return matter(raw).content;
+  return new Response(matter(raw).content, { headers: { 'Content-Type': 'text/markdown; charset=utf-8' } });
 });