docs-i18n 0.7.5 → 0.8.1

package/admin/dist/server/server.js

@@ -15556,38 +15556,6 @@ async function getStartManifest(matchedRoutes) {
 //#endregion
 //#region \0#tanstack-start-server-fn-resolver
 var manifest = {
-	"a3d81974aeece150d4b02be5b91590b8187442ebea56be4a89dcbf053626d22b": {
-		functionName: "fetchVersion_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
-	},
-	"3bf4ba50ca8ccc3c8c60d8f2e53307a320940d68c478df494552066904c5cd74": {
-		functionName: "fetchLlmConfig_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
-	},
-	"e0b4116f6b2c8d096830102e36458acf9c616a056fcdddda956a4d66984ef58c": {
-		functionName: "fetchConfig_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
-	},
-	"a054a04356fe9987891efee8b7a11cd2dedb00f6b2e8f26d1c642e001e553d53": {
-		functionName: "openFile_createServerFn_handler",
-		importer: () => import("./assets/misc-y6t3-UOP.js")
-	},
-	"421de02ce39dde6e27cf4689e837ec072cbd01e63f8cdd5c2a3f42f0bd5ca613": {
-		functionName: "fetchJobs_createServerFn_handler",
-		importer: () => import("./assets/jobs-FXffC7LH.js")
-	},
-	"c08559ac758aa0d315deaca7a0d7d923a9a44d997c8cb811151417c1f221ddd6": {
-		functionName: "createJob_createServerFn_handler",
-		importer: () => import("./assets/jobs-FXffC7LH.js")
-	},
-	"8a56694c9d7b29422a3e7d2f6b803be100d79d3853d92d465cb55ed572781e62": {
-		functionName: "fetchJob_createServerFn_handler",
-		importer: () => import("./assets/jobs-FXffC7LH.js")
-	},
-	"88c2855c84e91504070bfecc50ddfa50339d22c305626800b6d9b05d79385d71": {
-		functionName: "deleteJob_createServerFn_handler",
-		importer: () => import("./assets/jobs-FXffC7LH.js")
-	},
 	"4e218d79545765572808c7eab33b7663d4496209c15406d0b449366905b6b83f": {
 		functionName: "fetchStatus_createServerFn_handler",
 		importer: () => import("./assets/status-CM7Azp4n.js")
@@ -15611,6 +15579,38 @@ var manifest = {
 	"5080dc3f2f2309ec6981b94c431969637130c657e8a1dfb10400b4614eecc1ea": {
 		functionName: "fetchModels_createServerFn_handler",
 		importer: () => import("./assets/models-YNa3F3nn.js")
+	},
+	"421de02ce39dde6e27cf4689e837ec072cbd01e63f8cdd5c2a3f42f0bd5ca613": {
+		functionName: "fetchJobs_createServerFn_handler",
+		importer: () => import("./assets/jobs-FXffC7LH.js")
+	},
+	"c08559ac758aa0d315deaca7a0d7d923a9a44d997c8cb811151417c1f221ddd6": {
+		functionName: "createJob_createServerFn_handler",
+		importer: () => import("./assets/jobs-FXffC7LH.js")
+	},
+	"8a56694c9d7b29422a3e7d2f6b803be100d79d3853d92d465cb55ed572781e62": {
+		functionName: "fetchJob_createServerFn_handler",
+		importer: () => import("./assets/jobs-FXffC7LH.js")
+	},
+	"88c2855c84e91504070bfecc50ddfa50339d22c305626800b6d9b05d79385d71": {
+		functionName: "deleteJob_createServerFn_handler",
+		importer: () => import("./assets/jobs-FXffC7LH.js")
+	},
+	"a3d81974aeece150d4b02be5b91590b8187442ebea56be4a89dcbf053626d22b": {
+		functionName: "fetchVersion_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
+	},
+	"3bf4ba50ca8ccc3c8c60d8f2e53307a320940d68c478df494552066904c5cd74": {
+		functionName: "fetchLlmConfig_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
+	},
+	"e0b4116f6b2c8d096830102e36458acf9c616a056fcdddda956a4d66984ef58c": {
+		functionName: "fetchConfig_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
+	},
+	"a054a04356fe9987891efee8b7a11cd2dedb00f6b2e8f26d1c642e001e553d53": {
+		functionName: "openFile_createServerFn_handler",
+		importer: () => import("./assets/misc-y6t3-UOP.js")
 	}
 };
 async function getServerFnById(id) {

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.5",
+  "version": "0.8.1",
   "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, {

package/template/app/utils/sidebar-generator.ts

@@ -0,0 +1,185 @@
+/**
+ * Filesystem-based sidebar generation.
+ *
+ * Walks a content directory tree, sorts entries by numeric prefix,
+ * and produces a DocsConfig with sections (directories) and items (files).
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import matter from 'gray-matter'
+import type {
+  DocsConfig,
+  DocsConfigSection,
+  DocsConfigItem,
+} from '~/types'
+
+/**
+ * Convert a kebab-case name to Title Case.
+ * 'getting-started' → 'Getting Started'
+ */
+function toTitleCase(name: string): string {
+  return name
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+/**
+ * Strip a leading numeric prefix from a single name segment.
+ * '01-getting-started' → 'getting-started'
+ */
+function stripPrefix(name: string): string {
+  return name.replace(/^\d+-/, '')
+}
+
+/**
+ * Extract the numeric prefix for sorting. Returns Infinity if none.
+ */
+function sortOrder(name: string): number {
+  const match = name.match(/^(\d+)-/)
+  return match ? parseInt(match[1], 10) : Infinity
+}
+
+/**
+ * Try to read the frontmatter title from a markdown file.
+ */
+function readTitle(filePath: string): string | null {
+  try {
+    const raw = readFileSync(filePath, 'utf-8')
+    const { data } = matter(raw)
+    if (typeof data.title === 'string' && data.title) return data.title
+  } catch {
+    // ignore
+  }
+  return null
+}
+
+/**
+ * Generate a DocsConfig by walking a content directory.
+ *
+ * @param contentDir  Absolute path to the content directory to scan
+ *                    (e.g. `/path/to/content/latest/docs/en`)
+ * @param urlMapper   Optional function to transform relative file paths to URL slugs
+ */
+export function generateSidebarFromFilesystem(
+  contentDir: string,
+  urlMapper?: (path: string) => string,
+): DocsConfig {
+  if (!existsSync(contentDir) || !statSync(contentDir).isDirectory()) {
+    return { sections: [] }
+  }
+
+  const sections = buildSections(contentDir, contentDir, urlMapper)
+  return { sections }
+}
+
+/**
+ * Recursively build sidebar sections from a directory.
+ * Directories become sections, .md/.mdx files become items.
+ */
+function buildSections(
+  dir: string,
+  baseDir: string,
+  urlMapper?: (path: string) => string,
+): DocsConfigSection[] {
+  const sections: DocsConfigSection[] = []
+
+  let entries: ReturnType<typeof readdirSync>
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return sections
+  }
+
+  // Sort by numeric prefix
+  const sorted = [...entries].sort(
+    (a, b) => sortOrder(a.name) - sortOrder(b.name),
+  )
+
+  // Collect top-level files (items without a section) — only at root level
+  const topLevelItems: DocsConfigItem[] = []
+
+  for (const entry of sorted) {
+    if (entry.name.startsWith('.')) continue
+
+    if (entry.isDirectory()) {
+      const subDir = join(dir, entry.name)
+      const cleanName = stripPrefix(entry.name)
+      const label = toTitleCase(cleanName)
+
+      // Collect all file items from this directory (recursively flattened into children)
+      const children = collectItems(subDir, baseDir, urlMapper)
+
+      if (children.length > 0) {
+        sections.push({ label, children })
+      }
+    } else if (
+      entry.isFile() &&
+      (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))
+    ) {
+      const filePath = join(dir, entry.name)
+      const relativePath = filePath
+        .slice(baseDir.length + 1) // remove baseDir prefix + leading slash
+      const cleanName = stripPrefix(entry.name).replace(/\.mdx?$/, '')
+      const slug = urlMapper ? urlMapper(relativePath) : relativePath.replace(/\.mdx?$/, '')
+      const title = readTitle(filePath)
+      const label = title || toTitleCase(cleanName)
+
+      topLevelItems.push({ label, to: slug })
+    }
+  }
+
+  // If there are top-level files, add them as a section
+  if (topLevelItems.length > 0) {
+    sections.unshift({
+      label: 'Overview',
+      children: topLevelItems,
+    })
+  }
+
+  return sections
+}
+
+/**
+ * Collect all file items from a directory, recursing into subdirectories.
+ * Subdirectory files are flattened into a single list of items.
+ */
+function collectItems(
+  dir: string,
+  baseDir: string,
+  urlMapper?: (path: string) => string,
+): DocsConfigItem[] {
+  const items: DocsConfigItem[] = []
+
+  let entries: ReturnType<typeof readdirSync>
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return items
+  }
+
+  const sorted = [...entries].sort(
+    (a, b) => sortOrder(a.name) - sortOrder(b.name),
+  )
+
+  for (const entry of sorted) {
+    if (entry.name.startsWith('.')) continue
+
+    if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
+      const filePath = join(dir, entry.name)
+      const relativePath = filePath.slice(baseDir.length + 1)
+      const cleanName = stripPrefix(entry.name).replace(/\.mdx?$/, '')
+      const slug = urlMapper ? urlMapper(relativePath) : relativePath.replace(/\.mdx?$/, '')
+      const title = readTitle(filePath)
+      const label = title || toTitleCase(cleanName)
+
+      items.push({ label, to: slug })
+    } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
+      // Recurse into subdirectories
+      items.push(...collectItems(join(dir, entry.name), baseDir, urlMapper))
+    }
+  }
+
+  return items
+}

package/template/app/utils/url-mapper.ts

@@ -0,0 +1,22 @@
+/**
+ * Built-in URL mapping helpers for transforming file paths to URL slugs.
+ *
+ * Projects with numeric-prefixed directories (e.g. nextjs-i18n-docs) can use
+ * `stripNumericPrefixes` as their `urlMapper` in ProjectConfig.
+ */
+
+/**
+ * Strip numeric prefixes, file extensions, and trailing /index from a file path.
+ *
+ * Example:
+ *   '01-app/01-getting-started/01-installation.mdx'
+ *   → 'app/getting-started/installation'
+ */
+export function stripNumericPrefixes(filePath: string): string {
+  return filePath
+    .replace(/\.mdx?$/, '') // strip .md or .mdx extension
+    .split('/')
+    .map((segment) => segment.replace(/^\d+-/, '')) // strip leading numeric prefix per segment
+    .join('/')
+    .replace(/\/index$/, '') // strip trailing /index
+}

package/template/content/docs-i18n/en/admin.md

@@ -0,0 +1,143 @@
+---
+title: Admin Dashboard
+description: Web UI for monitoring translation progress, managing translation jobs, previewing files, and browsing LLM models.
+---
+
+# Admin Dashboard
+
+The docs-i18n admin dashboard is a web-based UI for managing your translations. It is built with TanStack Start and React, and runs as a local development server.
+
+## Starting the Dashboard
+
+```bash
+npx docs-i18n admin
+```
+
+The dashboard opens at `http://localhost:3456`. Use `--port` to change the port:
+
+```bash
+npx docs-i18n admin --port 4000
+```
+
+The dashboard reads your `docs-i18n.config.ts` to discover projects, versions, and languages. The admin is pre-built and requires no additional dependencies.
+
+## Features
+
+### Translation Overview
+
+The main dashboard page shows a grid of all versions and languages with translation progress. For each version/language pair, you see:
+
+- Total number of source nodes (EN content units).
+- Number of translated nodes.
+- Percentage complete.
+- Breakdown by section (e.g., `docs/`, `blog/`, `learn/`), showing file counts and node counts per section.
+
+English is always shown as 100% complete since it is the source language.
+
+The overview auto-scans source files on load. If source files have not been scanned yet, the dashboard triggers a scan automatically.
+
+### File Browser
+
+Clicking on a version/language cell opens a file-level coverage list. Each file shows:
+
+- File path (relative to the source directory).
+- Total translatable nodes in that file.
+- Number of translated nodes.
+
+Files are sorted by path. You can click on any file to open the block-level preview.
+
+### File Preview
+
+The file preview shows every block (AST node) in a file side by side:
+
+- **Source** -- the original English text.
+- **Translation** -- the cached translation for the selected language, or empty if not yet translated.
+
+Each block displays its type (heading, paragraph, list, blockquote, frontmatter, code, html) and MD5 key. Non-translatable blocks (code, pure HTML tags, gaps between nodes) are shown but clearly distinguished.
+
+### Cache Management
+
+From the file preview, you can delete individual cache entries. This is useful when a translation is incorrect and you want to re-translate a specific node. After deleting, run the translate command again to get a fresh translation for that key.
+
+The dashboard also supports rescanning source files for a specific version via the UI. This rebuilds the source index and cleans orphaned entries.
+
+### Translation Jobs
+
+The dashboard includes a job management system for running translations directly from the UI instead of the command line.
+
+#### Creating a Job
+
+Click the job creation button and configure:
+
+- **Language** -- target language code.
+- **Version** -- which version to translate.
+- **Project** -- optionally filter to a specific project.
+- **Model** -- LLM model to use (can be selected from the model browser).
+- **Model rotation** -- optionally provide multiple models to rotate through.
+- **Max chunks** -- limit the number of API call chunks.
+- **Concurrency** -- number of parallel API calls (default: 3).
+- **Files** -- optionally select specific files to translate.
+
+#### Job Status
+
+Running jobs show:
+
+- Status: `running`, `completed`, `failed`, or `cancelled`.
+- Start time and finish time.
+- Number of translated chunks and total chunks.
+- Current chunk being processed.
+- Live log output (last 20 lines displayed, up to 500 lines stored).
+
+You can cancel a running job, which sends SIGTERM to the translation process. Completed or failed jobs can be removed from the list.
+
+#### How Jobs Work
+
+Under the hood, the job manager spawns a child process running the `docs-i18n translate` CLI command with the configured options. It captures stdout and stderr, parses progress information from the output, and exposes it through the dashboard API. The child process inherits the API key from your config or environment variables.
+
+### Model Browser
+
+The dashboard includes an OpenRouter model browser that fetches the list of available models from the OpenRouter API. For each model, it displays:
+
+- Model ID and name.
+- Pricing (prompt and completion per million tokens).
+- Context length and maximum output tokens.
+- Whether the model supports JSON response format and tool use.
+- Provider name.
+- Whether the model is free.
+
+The model list is cached for 5 minutes. It only shows text-to-text models (filtered by architecture modality) and excludes models with negative pricing. Models are sorted by prompt price (cheapest first).
+
+This is useful for selecting a model when creating a translation job.
+
+### Open in Editor
+
+The dashboard can open source files in your local editor. It tries the following editors in order:
+
+1. The value of the `EDITOR_CMD` environment variable (if set).
+2. `code` (VS Code)
+3. `cursor` (Cursor)
+4. `zed` (Zed)
+
+If none are found, it falls back to the system default (`open` on macOS, `xdg-open` on Linux, `start` on Windows).
+
+## Architecture
+
+The admin dashboard uses:
+
+- **TanStack Start** -- Full-stack React framework with server functions.
+- **TanStack React Query** -- For data fetching and cache management.
+- **TanStack Router** -- For client-side routing.
+- **Vite** -- Dev server and build tool.
+- **Hono** -- HTTP server (used by TanStack Start internally).
+
+Server functions are defined in `packages/admin/server/functions/` and handle:
+
+- `fetchStatus` / `fetchFileCoverage` / `fetchFileBlocks` -- Read translation status from SQLite.
+- `deleteCacheEntry` -- Delete a specific translation from the cache.
+- `rescanVersion` -- Rescan source files for a version.
+- `createJob` / `fetchJobs` / `fetchJob` / `deleteJob` -- Manage translation jobs.
+- `fetchModels` -- Fetch available models from OpenRouter.
+- `fetchVersion` / `fetchConfig` -- Get docs-i18n version and project root.
+- `openFile` -- Open a file in the local editor.
+
+The dashboard shares the same `TranslationCache` and `parseMdx` functions as the CLI, ensuring consistent behavior.

package/template/content/docs-i18n/en/cli.md

@@ -0,0 +1,324 @@
+---
+title: CLI Reference
+description: Complete reference for all docs-i18n CLI commands, flags, and common workflows.
+---
+
+# CLI Reference
+
+docs-i18n provides a command-line interface for managing documentation translations. All commands read from `docs-i18n.config.ts` in the current working directory by default.
+
+```bash
+docs-i18n <command> [options]
+```
+
+## Global Options
+
+| Flag | Description |
+| --- | --- |
+| `--config <path>` | Path to config file (default: `docs-i18n.config.ts`) |
+| `--version`, `-v` | Print the docs-i18n version |
+| `--help`, `-h` | Show help text |
+
+## Commands
+
+### `translate`
+
+Translate content to a target language. Sends untranslated nodes to the configured LLM and caches the results.
+
+```bash
+docs-i18n translate --lang <code> [options]
+```
+
+**Required:**
+
+| Flag | Description |
+| --- | --- |
+| `--lang <code>` | Target language code (e.g., `zh-hans`, `ja`, `es`) |
+
+**Optional:**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--project <id>` | all projects | Filter to a specific project |
+| `--version <ver>` | all versions | Filter to a specific version |
+| `--files <paths>` | all files | Comma-separated list of relative file paths to translate |
+| `--max <n>` | 999 | Maximum number of API call chunks to process |
+| `--concurrency <n>` | 3 | Number of parallel API calls |
+| `--model <model>` | config value | Override the LLM model |
+| `--api-key <key>` | config/env | Override the API key |
+| `--max-tokens <n>` | 16384 | Max output tokens per API call |
+| `--context-length <n>` | 32768 | Model context window size |
+| `--dry-run` | false | Preview what would be translated without making API calls |
+
+**Examples:**
+
+```bash
+# Translate everything to Simplified Chinese
+docs-i18n translate --lang zh-hans
+
+# Translate a specific version with dry run
+docs-i18n translate --lang zh-hans --version latest --dry-run
+
+# Translate specific files only
+docs-i18n translate --lang zh-hans --files docs/intro.mdx,docs/guide.mdx
+
+# Use a different model with higher token limits
+docs-i18n translate --lang ja --model qwen/qwen3.5-flash-02-23 --max-tokens 65536 --context-length 1000000
+
+# Limit API calls for testing
+docs-i18n translate --lang es --max 5 --concurrency 1
+```
+
+**How it works:**
+
+1. Loads the SQLite cache and finds all untranslated keys for the given language and version.
+2. Groups untranslated nodes into chunks that fit within the model's context window, accounting for input tokens, output tokens, and language-specific token multipliers (e.g., Japanese uses 2.5x more output tokens than English).
+3. Sends each chunk to the LLM as structured JSON: an array of typed nodes with MD5 keys.
+4. Parses the JSON response, validates keys, and stores translations in the cache.
+5. Runs chunks in parallel up to the concurrency limit.
+
+Translation logs are written to `.logs/` with timestamps for debugging.
+
+---
+
+### `assemble`
+
+Assemble translated files by combining English source content with cached translations. For any untranslated nodes, the original English text is used as a fallback.
+
+```bash
+docs-i18n assemble [options]
+```
+
+**Optional:**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--project <id>` | all projects | Filter to a specific project |
+| `--version <ver>` | all versions | Filter to a specific version |
+| `--lang <code>` | all languages | Filter to a specific language |
+
+**Examples:**
+
+```bash
+# Assemble all projects, versions, and languages
+docs-i18n assemble
+
+# Assemble only Chinese for the latest version
+docs-i18n assemble --lang zh-hans --version latest
+```
+
+Output is written to `.cache/content/<version>/<lang>/` by default. Each file mirrors the structure of the English source directory.
+
+---
+
+### `rescan`
+
+Rescan source files and rebuild the source index. Also cleans orphaned translations and sources that no longer exist in the source files.
+
+```bash
+docs-i18n rescan [options]
+```
+
+**Optional:**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--project <id>` | all projects | Filter to a specific project |
+| `--version <ver>` | all versions | Filter to a specific version |
+
+**Examples:**
+
+```bash
+# Rescan all source files
+docs-i18n rescan
+
+# Rescan a specific version only
+docs-i18n rescan --version latest
+```
+
+**What it does:**
+
+1. Walks all source directories and parses every markdown/MDX file.
+2. Extracts translatable nodes and stores their MD5 keys, source text, node types, file paths, and line numbers in the SQLite cache.
+3. Deletes orphaned translations whose source keys no longer exist in any source file.
+4. Deletes orphaned source entries that are no longer referenced by any file.
+
+Run `rescan` after adding, removing, or significantly editing source files.
+
+---
+
+### `status`
+
+Show translation coverage for all projects and versions.
+
+```bash
+docs-i18n status [options]
+```
+
+**Optional:**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--lang <code>` | all languages | Show status for a specific language only |
+
+**Examples:**
+
+```bash
+# Show status for all languages
+docs-i18n status
+
+# Show status for Chinese only
+docs-i18n status --lang zh-hans
+```
+
+**Output:**
+
+```
+Translation Status
+
+latest (1523 keys):
+  zh-hans    ████████████████████ 100% (1523/1523)
+  ja         ████████████░░░░░░░░ 62% (944/1523)
+  es         ██░░░░░░░░░░░░░░░░░░ 10% (152/1523)
+```
+
+If a version shows "no source files (run rescan first)", you need to run `docs-i18n rescan` before checking status.
+
+---
+
+### `admin`
+
+Start the admin dashboard web UI for managing translations.
+
+```bash
+docs-i18n admin [options]
+```
+
+**Optional:**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--port <n>` | 3456 | Port to run the dashboard on |
+
+**Examples:**
+
+```bash
+# Start on default port
+docs-i18n admin
+
+# Start on custom port
+docs-i18n admin --port 4000
+```
+
+The dashboard opens at `http://localhost:3456` (or your custom port). See the [Admin Dashboard](./admin.md) documentation for details on its features.
+
+---
+
+### `site`
+
+Manage the documentation site. Built with TanStack Start and supports dev server, production build, content upload to D1, and deployment to Cloudflare Workers.
+
+```bash
+docs-i18n site [subcommand] [options]
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+| --- | --- |
+| `dev` (default) | Start the Vite dev server with hot reload |
+| `build` | Build the site for production |
+| `upload` | Upload content and translations to Cloudflare D1 |
+| `deploy` | Deploy to Cloudflare Workers |
+
+**Optional:**
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--port <n>` | 3000 | Port for the dev server |
+| `--db <name>` | `docs-i18n-db` | D1 database name (for `upload`) |
+
+**Examples:**
+
+```bash
+# Start dev server
+docs-i18n site
+
+# Start on custom port
+docs-i18n site dev --port 4000
+
+# Build for production
+docs-i18n site build
+
+# Upload content to D1
+docs-i18n site upload --db my-docs-db
+
+# Deploy to Cloudflare Workers
+docs-i18n site deploy
+```
+
+**How it works:**
+
+The `site` command does not require a `docs-i18n.config.ts`. It reads the `site.config.ts` file from your project root to configure the documentation site (project names, colors, locales, etc.).
+
+On first run, the template's dependencies are automatically installed. The dev server uses Vite with the consumer's `site.config.ts` aliased into the template for customization.
+
+For non-English languages, the site automatically loads translations from the `.cache/translations.db` SQLite cache and assembles them at runtime.
+
+---
+
+## Common Workflows
+
+### Full translation pipeline
+
+```bash
+# 1. Scan source files
+docs-i18n rescan
+
+# 2. Check what needs translating
+docs-i18n status
+
+# 3. Translate
+docs-i18n translate --lang zh-hans
+
+# 4. Assemble output
+docs-i18n assemble --lang zh-hans
+```
+
+### Translate a single file for review
+
+```bash
+docs-i18n translate --lang zh-hans --files docs/getting-started.mdx --max 1
+docs-i18n assemble --lang zh-hans
+```
+
+### Preview translation volume before spending API credits
+
+```bash
+docs-i18n translate --lang ja --dry-run
+```
+
+This reports the number of untranslated keys and chunks without making any API calls.
+
+### Multi-project translation
+
+```bash
+# Translate only the "query" project
+docs-i18n translate --lang zh-hans --project query
+
+# Assemble only the "table" project
+docs-i18n assemble --project table --lang zh-hans
+```
+
+### After editing source files
+
+```bash
+# Rescan to detect changes and clean orphans
+docs-i18n rescan
+
+# Translate only new/changed content (cached translations are reused)
+docs-i18n translate --lang zh-hans
+
+# Rebuild output files
+docs-i18n assemble
+```

package/template/package.json

@@ -12,8 +12,8 @@
     "@shikijs/transformers": "^3.0.0",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "^4.1.7",
-    "@tanstack/react-router": "^1.120.3",
     "@tanstack/react-query": "^5.0.0",
+    "@tanstack/react-router": "^1.120.3",
     "@tanstack/react-start": "^1.120.3",
     "drizzle-orm": "^0.38.0",
     "gray-matter": "^4.0.3",
@@ -32,6 +32,7 @@
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "shiki": "^3.0.0",