docs-i18n 0.7.4 → 0.8.0

package/admin/vite.config.ts

@@ -10,4 +10,17 @@ export default defineConfig({
     }),
     react(),
   ],
+  // Bundle all deps into server build so it can run without node_modules
+  environments: {
+    ssr: {
+      build: {
+        rollupOptions: {
+          external: ['node:*'],
+        },
+      },
+      resolve: {
+        noExternal: true,
+      },
+    },
+  },
 });

package/dist/cli.js

@@ -72,7 +72,7 @@ async function handleSiteCommand() {
     child.on("exit", (code) => process.exit(code ?? 0));
   } else if (subCommand === "upload") {
     console.log("Uploading content to D1...");
-    const { collectContentFiles, generateContentSql, collectTranslations, generateTranslationSql } = await import("./upload-XL6KG6S2.js");
+    const { collectContentFiles, generateContentSql, collectTranslations, generateTranslationSql } = await import("./upload-KYKJVERO.js");
     const projectRoot = process.cwd();
     const contentRows = collectContentFiles(projectRoot);
     const contentSql = generateContentSql(contentRows);

package/dist/{upload-XL6KG6S2.js → upload-KYKJVERO.js}

@@ -21,7 +21,7 @@ function walkDir(dir, contentRoot, rows) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory() && !entry.name.startsWith(".")) {
       walkDir(fullPath, contentRoot, rows);
-    } else if (entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".json"))) {
+    } else if (entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".mdx") || entry.name.endsWith(".json"))) {
       const relativePath = relative(contentRoot, fullPath);
       const body = readFileSync(fullPath, "utf-8");
       const parts = relativePath.split("/");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-i18n",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "description": "Universal documentation translation engine — parse, translate, cache, assemble, manage.",
   "type": "module",
   "bin": {

package/template/app/components/BlogArticle.tsx

@@ -19,6 +19,7 @@ import { MarkdownContent } from '~/components/markdown'
 import { Toc } from '~/components/Toc'
 import { Breadcrumbs } from '~/components/Breadcrumbs'
 import { FallbackBanner } from '~/components/FallbackBanner'
+import { useSiteConfig } from '~/utils/site-config'
 import type { LoadedBlogPost } from '~/utils/blog'
 
 type BlogArticleProps = {
@@ -29,6 +30,7 @@ type BlogArticleProps = {
 }
 
 export function BlogArticle({ post, lang, locale }: BlogArticleProps) {
+  const siteConfig = useSiteConfig()
   const { title, content, authors, published, filePath, isFallback } = post
 
   // Prepend byline to content (matches tanstack.com pattern)
@@ -137,6 +139,7 @@ ${content}`
                         branch=""
                         filePath={filePath}
                         containerRef={markdownContainerRef}
+                        customComponents={siteConfig.components}
                       />
                     </div>
                     {isTocVisible && (

package/template/app/components/Doc.tsx

@@ -11,6 +11,7 @@ import { MarkdownContent } from '~/components/markdown'
 import type { DocsConfig, MarkdownHeading } from '~/types'
 import { useLocalCurrentFramework } from './FrameworkSelect'
 import { useParams } from '@tanstack/react-router'
+import { useSiteConfig } from '~/utils/site-config'
 
 type DocProps = {
   title: string
@@ -50,6 +51,8 @@ export function Doc({
   isFallback = false,
   locale,
 }: DocProps) {
+  const siteConfig = useSiteConfig()
+
   // Extract headings synchronously during render to avoid hydration mismatch
   const { headings, markup } = React.useMemo(
     () => renderMarkdown(content),
@@ -154,6 +157,7 @@ export function Doc({
             htmlMarkup={markup}
             containerRef={markdownContainerRef}
             currentFramework={currentFramework}
+            customComponents={siteConfig.components}
             titleBarActions={
               setIsFullWidth ? (
                 <button

package/template/app/components/markdown/MarkdownContent.tsx

@@ -3,6 +3,7 @@ import { SquarePen } from 'lucide-react'
 import { twMerge } from 'tailwind-merge'
 import { Markdown } from './Markdown'
 import { Button } from '../ui/Button'
+import type { SiteConfig } from '~/types'
 
 type MarkdownContentProps = {
   title: string
@@ -23,6 +24,8 @@ type MarkdownContentProps = {
   containerRef?: React.RefObject<HTMLDivElement | null>
   /** Current framework for filtering markdown content */
   currentFramework?: string
+  /** Custom components from SiteConfig for rendering MDX JSX elements */
+  customComponents?: SiteConfig['components']
 }
 
 export function MarkdownContent({
@@ -36,11 +39,12 @@ export function MarkdownContent({
   titleBarActions,
   proseClassName,
   containerRef,
+  customComponents,
 }: MarkdownContentProps) {
   const markdownElement = htmlMarkup ? (
-    <Markdown htmlMarkup={htmlMarkup} />
+    <Markdown htmlMarkup={htmlMarkup} customComponents={customComponents} />
   ) : rawContent ? (
-    <Markdown rawContent={rawContent} renderMarkdown={renderMarkdown} />
+    <Markdown rawContent={rawContent} renderMarkdown={renderMarkdown} customComponents={customComponents} />
   ) : null
 
   return (

package/template/app/site.config.ts

@@ -136,6 +136,8 @@ export const siteConfig: SiteConfig = {
     versionSelector: true,
     editOnGithub: true,
   },
+  /** Custom MDX components. Consumers override this to register their own JSX components. */
+  components: {},
 }
 
 /**

package/template/app/types/index.ts

@@ -36,6 +36,10 @@ export interface ProjectConfig {
   badge?: string
   tagline?: string
   description?: string
+  /** Transform file path to URL slug. Strips numeric prefixes, extensions, etc. */
+  urlMapper?: (filePath: string) => string
+  /** How to generate sidebar: 'config' reads docs.config.json, 'filesystem' auto-generates from directory structure */
+  sidebarSource?: 'config' | 'filesystem'
 }
 
 export interface MarkdownHeading {

package/template/app/utils/content-loader.ts

@@ -62,10 +62,16 @@ function getTranslationCache(projectRoot: string): TranslationCache | null {
   }
 }
 
-export function createFsLoader(projectRoot: string): ContentLoader {
+export function createFsLoader(
+  projectRoot: string,
+  urlMapper?: (filePath: string) => string,
+): ContentLoader {
+  /** Supported markdown extensions, in priority order. */
+  const mdExtensions = ['.mdx', '.md']
+
   /**
-   * Read a raw .md file from one of the candidate base directories.
-   * Returns the raw file content and resolved path, or null.
+   * Read a raw .md/.mdx file from one of the candidate base directories.
+   * When urlMapper is set, scans directories and matches by mapped slug.
    */
   function readRawFile(
     project: string,
@@ -73,14 +79,52 @@ export function createFsLoader(projectRoot: string): ContentLoader {
     lang: string,
     slug: string,
   ): { raw: string; filePath: string } | null {
-    const candidates = [
-      resolve(projectRoot, 'content', project, version, lang, `${slug}.md`),
-      resolve(projectRoot, 'content', project, lang, `${slug}.md`),
-      resolve(projectRoot, 'content', lang, `${slug}.md`),
+    const baseDirs = [
+      resolve(projectRoot, 'content', project, version, lang),
+      resolve(projectRoot, 'content', project, lang),
+      resolve(projectRoot, 'content', lang),
     ]
-    for (const filePath of candidates) {
-      if (existsSync(filePath)) {
-        return { raw: readFileSync(filePath, 'utf-8'), filePath }
+
+    if (!urlMapper) {
+      for (const baseDir of baseDirs) {
+        for (const ext of mdExtensions) {
+          const filePath = resolve(baseDir, `${slug}${ext}`)
+          if (existsSync(filePath)) {
+            return { raw: readFileSync(filePath, 'utf-8'), filePath }
+          }
+        }
+      }
+      return null
+    }
+
+    // With urlMapper: scan files and match by mapped slug
+    for (const baseDir of baseDirs) {
+      if (!existsSync(baseDir)) continue
+      const match = findFileByMappedSlug(baseDir, baseDir, slug)
+      if (match) return match
+    }
+    return null
+  }
+
+  /** Recursively scan for .md/.mdx files, apply urlMapper, match target slug. */
+  function findFileByMappedSlug(
+    dir: string,
+    baseDir: string,
+    targetSlug: string,
+  ): { raw: string; filePath: string } | null {
+    let entries: ReturnType<typeof readdirSync>
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return null }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue
+      const fullPath = join(dir, entry.name)
+      if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+        const mapped = urlMapper!(relative(baseDir, fullPath))
+        if (mapped === targetSlug) {
+          return { raw: readFileSync(fullPath, 'utf-8'), filePath: fullPath }
+        }
+      } else if (entry.isDirectory()) {
+        const result = findFileByMappedSlug(fullPath, baseDir, targetSlug)
+        if (result) return result
       }
     }
     return null
@@ -114,8 +158,9 @@ export function createFsLoader(projectRoot: string): ContentLoader {
     try {
       const entries = readdirSync(dir, { withFileTypes: true })
       for (const entry of entries) {
-        if (entry.isFile() && entry.name.endsWith('.md')) {
-          slugs.push(relative(base, join(dir, entry.name)).replace(/\.md$/, ''))
+        if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
+          const rawSlug = relative(base, join(dir, entry.name)).replace(/\.mdx?$/, '')
+          slugs.push(urlMapper ? urlMapper(relative(base, join(dir, entry.name))) : rawSlug)
         } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
           slugs.push(...scanDirectory(join(dir, entry.name), base))
         }
@@ -149,7 +194,9 @@ export function createFsLoader(projectRoot: string): ContentLoader {
       const cache = getTranslationCache(projectRoot)
       if (cache) {
         try {
-          const sourceFilePath = `${slug}.md`
+          // Derive the extension from the resolved file path for cache lookup
+          const ext = en.filePath.endsWith('.mdx') ? '.mdx' : '.md'
+          const sourceFilePath = `${slug}${ext}`
           const result = assemble(
             en.raw,
             lang,
@@ -241,45 +288,51 @@ import type { Db } from '~/db'
 import { createDb, schema } from '~/db'
 
 export function createD1Loader(db: Db): ContentLoader {
-  return {
-    async loadDoc(project, version, lang, slug) {
-      const path = `${project}/${version}/${lang}/${slug}.md`
-
-      // Try requested language
+  /** Try loading a row by slug with .mdx first, then .md. */
+  async function loadBySlug(
+    prefix: string,
+    slug: string,
+  ): Promise<{ row: { body: string; path: string } } | null> {
+    for (const ext of ['.mdx', '.md']) {
+      const path = `${prefix}/${slug}${ext}`
       const row = await db
         .select()
         .from(schema.content)
         .where(eq(schema.content.path, path))
         .get()
+      if (row) return { row: { body: row.body, path } }
+    }
+    return null
+  }
 
-      if (row) {
-        const { data, content } = matter(row.body)
+  return {
+    async loadDoc(project, version, lang, slug) {
+      // Try requested language
+      const result = await loadBySlug(`${project}/${version}/${lang}`, slug)
+
+      if (result) {
+        const { data, content } = matter(result.row.body)
         return {
           content,
           meta: { title: (data.title as string) || '', ...data },
           locale: lang,
           isFallback: false,
-          filePath: path,
+          filePath: result.row.path,
         }
       }
 
       // Fallback to English
       if (lang !== 'en') {
-        const enPath = `${project}/${version}/en/${slug}.md`
-        const enRow = await db
-          .select()
-          .from(schema.content)
-          .where(eq(schema.content.path, enPath))
-          .get()
-
-        if (enRow) {
-          const { data, content } = matter(enRow.body)
+        const enResult = await loadBySlug(`${project}/${version}/en`, slug)
+
+        if (enResult) {
+          const { data, content } = matter(enResult.row.body)
           return {
             content,
             meta: { title: (data.title as string) || '', ...data },
             locale: 'en',
             isFallback: true,
-            filePath: enPath,
+            filePath: enResult.row.path,
           }
         }
       }
@@ -348,7 +401,7 @@ export function createD1Loader(db: Db): ContentLoader {
         .all()
 
       return rows
-        .map((r) => r.path.replace(prefix, '').replace(/\.md$/, ''))
+        .map((r) => r.path.replace(prefix, '').replace(/\.mdx?$/, ''))
         .filter((s) => s.length > 0)
     },
   }

package/template/app/utils/docs.server.ts

@@ -8,8 +8,9 @@
 import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { resolve, relative, join } from 'node:path'
 import matter from 'gray-matter'
-import type { LoadedDoc, DocsConfig, DocsConfigItem } from '~/types'
+import type { LoadedDoc, DocsConfig, DocsConfigItem, ProjectConfig } from '~/types'
 import { type ContentLoader, createFsLoader } from './content-loader'
+import { generateSidebarFromFilesystem } from './sidebar-generator'
 
 /**
  * Get the project root directory.
@@ -61,25 +62,35 @@ export function setContentLoader(loader: ContentLoader) {
 
 /**
  * Load a document with i18n fallback.
- * Delegates to the active ContentLoader.
+ * When projectConfig has urlMapper, creates a mapper-aware loader.
  */
 export async function loadDoc(
   project: string,
   version: string,
   lang: string,
   slug: string,
+  projectConfig?: ProjectConfig,
 ): Promise<LoadedDoc> {
+  if (projectConfig?.urlMapper) {
+    const loader = createFsLoader(getProjectRoot(), projectConfig.urlMapper)
+    return loader.loadDoc(project, version, lang, slug)
+  }
   return getLoader().loadDoc(project, version, lang, slug)
 }
 
 /**
- * Load docs config (config.json for sidebar structure).
- * Delegates to the active ContentLoader, with auto-scan fallback.
+ * Load docs config (sidebar structure).
+ * When sidebarSource is 'filesystem', generates from directory tree.
  */
 export async function loadDocsConfig(
   project: string,
   version: string,
+  projectConfig?: ProjectConfig,
 ): Promise<DocsConfig> {
+  if (projectConfig?.sidebarSource === 'filesystem') {
+    return loadFilesystemSidebar(project, version, projectConfig)
+  }
+
   const config = await getLoader().loadDocsConfig(project, version)
   if (config) return config
 
@@ -87,6 +98,27 @@ export async function loadDocsConfig(
   return autoScanDocs(getProjectRoot(), project, version)
 }
 
+/** Generate sidebar from filesystem using numeric prefix ordering. */
+function loadFilesystemSidebar(
+  project: string,
+  version: string,
+  projectConfig: ProjectConfig,
+): DocsConfig {
+  const root = getProjectRoot()
+  const candidates = [
+    resolve(root, 'content', project, version, 'en'),
+    resolve(root, 'content', project, 'en'),
+    resolve(root, 'content', 'en'),
+  ]
+  for (const dir of candidates) {
+    if (existsSync(dir) && statSync(dir).isDirectory()) {
+      const config = generateSidebarFromFilesystem(dir, projectConfig.urlMapper)
+      if (config.sections.length > 0) return config
+    }
+  }
+  return { sections: [] }
+}
+
 /**
  * Auto-generate sidebar config by scanning .md files in the content directory.
  */
@@ -126,9 +158,9 @@ function scanDirectory(dir: string, base: string): DocsConfigItem[] {
   try {
     const entries = readdirSync(dir, { withFileTypes: true })
     for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith('.md')) {
+      if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
         const relativePath = relative(base, join(dir, entry.name))
-        const slug = relativePath.replace(/\.md$/, '')
+        const slug = relativePath.replace(/\.mdx?$/, '')
         // Read frontmatter for title
         const filePath = join(dir, entry.name)
         const raw = readFileSync(filePath, 'utf-8')

package/template/app/utils/markdown/plugins/index.ts

@@ -6,3 +6,4 @@ export {
 } from './transformFrameworkComponent'
 export { transformTabsComponent } from './transformTabsComponent'
 export { type MarkdownHeading, rehypeCollectHeadings } from './collectHeadings'
+export { rehypeMdxJsxToRaw } from './mdxJsxToRaw'

package/template/app/utils/markdown/plugins/mdxJsxToRaw.ts

@@ -0,0 +1,127 @@
+/**
+ * Rehype plugin that converts passed-through MDX JSX AST nodes into
+ * raw HTML strings so that rehype-raw can parse them into standard
+ * hast element nodes.
+ *
+ * This is needed because remark-mdx produces mdxJsxFlowElement /
+ * mdxJsxTextElement nodes which remark-rehype can pass through (via
+ * the `passThrough` option) but rehype-raw does not understand. By
+ * serialising them to raw HTML first, the existing pipeline
+ * (rehype-raw -> rehype-stringify) handles them naturally as HTML
+ * elements, which html-react-parser can then match to custom
+ * components.
+ *
+ * MDX expression nodes (mdxFlowExpression, mdxTextExpression) and
+ * ESM nodes (mdxjsEsm) are stripped silently — they have no
+ * meaningful HTML representation in a server-rendered pipeline.
+ */
+
+import { visit, SKIP } from 'unist-util-visit'
+import type { Root } from 'hast'
+
+interface MdxJsxAttribute {
+  type: 'mdxJsxAttribute'
+  name: string
+  value: string | { type: string; value: string } | null | undefined
+}
+
+interface MdxJsxNode {
+  type: string
+  name: string | null
+  attributes?: MdxJsxAttribute[]
+  children?: any[]
+}
+
+function serializeAttributes(attrs?: MdxJsxAttribute[]): string {
+  if (!attrs || attrs.length === 0) return ''
+  return attrs
+    .map((attr) => {
+      if (attr.type !== 'mdxJsxAttribute') return ''
+      const name = attr.name
+      if (attr.value == null) return ` ${name}`
+      const val =
+        typeof attr.value === 'string'
+          ? attr.value
+          : typeof attr.value === 'object' && attr.value.value
+            ? attr.value.value
+            : ''
+      return ` ${name}="${val.replace(/"/g, '"')}"`
+    })
+    .join('')
+}
+
+function serializeChildren(children: any[]): string {
+  return children
+    .map((child: any) => {
+      if (child.type === 'text') return child.value ?? ''
+      if (child.type === 'raw') return child.value ?? ''
+      if (
+        child.type === 'mdxJsxFlowElement' ||
+        child.type === 'mdxJsxTextElement'
+      ) {
+        return serializeMdxJsx(child)
+      }
+      // For standard hast element nodes that ended up as children
+      if (child.type === 'element' && child.tagName) {
+        const attrs = serializeHastProps(child.properties)
+        const inner = child.children ? serializeChildren(child.children) : ''
+        return `<${child.tagName}${attrs}>${inner}</${child.tagName}>`
+      }
+      return ''
+    })
+    .join('')
+}
+
+function serializeHastProps(props?: Record<string, any>): string {
+  if (!props) return ''
+  return Object.entries(props)
+    .map(([key, val]) => {
+      if (val === true) return ` ${key}`
+      if (val === false || val == null) return ''
+      return ` ${key}="${String(val).replace(/"/g, '&quot;')}"`
+    })
+    .join('')
+}
+
+function serializeMdxJsx(node: MdxJsxNode): string {
+  const tag = node.name
+  if (!tag) {
+    // Fragment — just render children
+    return node.children ? serializeChildren(node.children) : ''
+  }
+  const attrs = serializeAttributes(node.attributes as MdxJsxAttribute[])
+  const inner = node.children ? serializeChildren(node.children) : ''
+  if (!inner && (!node.children || node.children.length === 0)) {
+    return `<${tag}${attrs}></${tag}>`
+  }
+  return `<${tag}${attrs}>${inner}</${tag}>`
+}
+
+export function rehypeMdxJsxToRaw() {
+  return (tree: Root) => {
+    visit(tree, (node: any, index, parent: any) => {
+      if (
+        node.type === 'mdxJsxFlowElement' ||
+        node.type === 'mdxJsxTextElement'
+      ) {
+        const html = serializeMdxJsx(node as MdxJsxNode)
+        if (parent && typeof index === 'number') {
+          parent.children[index] = { type: 'raw', value: html }
+        }
+        return SKIP
+      }
+      // Strip expression / ESM nodes
+      if (
+        node.type === 'mdxFlowExpression' ||
+        node.type === 'mdxTextExpression' ||
+        node.type === 'mdxjsEsm'
+      ) {
+        if (parent && typeof index === 'number') {
+          parent.children.splice(index, 1)
+          return [SKIP, index] as any
+        }
+        return SKIP
+      }
+    })
+  }
+}

package/template/app/utils/markdown/processor.ts

@@ -1,5 +1,6 @@
 import { unified } from 'unified'
 import remarkParse from 'remark-parse'
+import remarkMdx from 'remark-mdx'
 import remarkGfm from 'remark-gfm'
 import remarkRehype from 'remark-rehype'
 import rehypeCallouts from 'rehype-callouts'
@@ -10,6 +11,7 @@ import rehypeStringify from 'rehype-stringify'
 
 import {
   rehypeCollectHeadings,
+  rehypeMdxJsxToRaw,
   rehypeParseCommentComponents,
   rehypeTransformCommentComponents,
   rehypeTransformFrameworkComponents,
@@ -29,9 +31,20 @@ export function renderMarkdown(content: string): MarkdownRenderResult {
 
   const processor = unified()
     .use(remarkParse)
+    .use(remarkMdx)
     .use(remarkGfm)
-    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(remarkRehype, {
+      allowDangerousHtml: true,
+      passThrough: [
+        'mdxjsEsm',
+        'mdxFlowExpression',
+        'mdxJsxFlowElement',
+        'mdxJsxTextElement',
+        'mdxTextExpression',
+      ],
+    })
     .use(extractCodeMeta)
+    .use(rehypeMdxJsxToRaw)
     .use(rehypeRaw)
     .use(rehypeParseCommentComponents)
     .use(rehypeCallouts, {