docs-i18n 0.6.3 → 0.7.0

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import * as unified from 'unified';
+import * as mdast from 'mdast';
+import { Root } from 'hast';
+
 /**
  * docs-i18n configuration schema.
  * Each project provides a `docs-i18n.config.ts` file.
@@ -248,6 +252,36 @@ declare function extractTranslatableFields(frontmatterText: string): Record<stri
  */
 declare function reconstructFrontmatter(frontmatterText: string, translatedFields: Record<string, string>): string;
 
+interface Heading {
+    id: string;
+    text: string;
+    level: number;
+}
+interface RenderedMarkdown {
+    html: string;
+    headings: Heading[];
+}
+/**
+ * The base unified processor for markdown → HTML rendering.
+ *
+ * Pipeline: remarkParse → remarkGfm → remarkRehype → rehypeRaw →
+ *           rehypeCallouts → rehypeSlug → rehypeAutolinkHeadings →
+ *           rehypeCollectHeadings → rehypeStringify
+ *
+ * Exported so consumers can extend it with additional plugins via `.use()`.
+ */
+declare const processor: unified.Processor<mdast.Root, mdast.Root, Root, Root, string>;
+/**
+ * Synchronous markdown → HTML rendering.
+ * Suitable for use inside React `useMemo` or server-side rendering.
+ */
+declare function renderMarkdown(markdown: string): RenderedMarkdown;
+/**
+ * Extract headings from an already-rendered HTML string.
+ * This is an alternative to the plugin approach — useful when you only have HTML.
+ */
+declare function extractHeadings(html: string): Heading[];
+
 /**
  * Preprocess MDX content to ensure JSX tags (<AppOnly>, <PagesOnly>, <details>, <div>)
  * are separated from surrounding content by blank lines.
@@ -256,4 +290,10 @@ declare function reconstructFrontmatter(frontmatterText: string, translatedField
  */
 declare function normalize(content: string): string;
 
-export { type DocsI18nConfig, type ProjectConfig, TranslationCache, assemble, defineConfig, extractTranslatableFields, flattenSources, loadConfig, normalize, parseMdx, reconstructFrontmatter };
+/**
+ * Walk up from the current file to find the docs-i18n package.json and return its version.
+ * Falls back to 'unknown' if not found.
+ */
+declare function getPackageVersion(): string;
+
+export { type DocsI18nConfig, type Heading, type ProjectConfig, type RenderedMarkdown, TranslationCache, assemble, defineConfig, extractHeadings, extractTranslatableFields, flattenSources, getPackageVersion, loadConfig, normalize, parseMdx, processor, reconstructFrontmatter, renderMarkdown };

package/dist/index.js

@@ -10,14 +10,15 @@ function defineConfig(config) {
 }
 async function loadConfig(path2) {
   const configPath = path2 ?? "docs-i18n.config.ts";
+  const fullPath = configPath.startsWith("/") ? configPath : `${process.cwd()}/${configPath}`;
   try {
     const mod = await import(
       /* @vite-ignore */
-      `${process.cwd()}/${configPath}`
+      fullPath
     );
     return mod.default ?? mod;
   } catch {
-    throw new Error(`Cannot load config from ${configPath}. Create a docs-i18n.config.ts file.`);
+    throw new Error(`Cannot load config from ${fullPath}. Create a docs-i18n.config.ts file.`);
   }
 }
 function flattenSources(config) {
@@ -532,14 +533,102 @@ function reconstructFrontmatter(frontmatterText, translatedFields) {
 ${doc.toString().trimEnd()}
 ---`;
 }
+
+// src/core/markdown.ts
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkRehype from "remark-rehype";
+import rehypeRaw from "rehype-raw";
+import rehypeCallouts from "rehype-callouts";
+import rehypeSlug from "rehype-slug";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeStringify from "rehype-stringify";
+function getTextContent(node) {
+  if (node.type === "text") {
+    return node.value;
+  }
+  if ("children" in node) {
+    return node.children.map((child) => getTextContent(child)).join("");
+  }
+  return "";
+}
+function rehypeCollectHeadings() {
+  return (tree, file) => {
+    const headings = [];
+    function visit(node) {
+      if (node.type === "element") {
+        const match = node.tagName.match(/^h([1-6])$/);
+        if (match) {
+          const level = Number.parseInt(match[1], 10);
+          const id = node.properties?.id ?? "";
+          const text = getTextContent(node);
+          headings.push({ id, text, level });
+        }
+      }
+      if ("children" in node) {
+        for (const child of node.children) {
+          if (child.type === "element") {
+            visit(child);
+          }
+        }
+      }
+    }
+    visit(tree);
+    file.data.headings = headings;
+  };
+}
+var processor = unified().use(remarkParse).use(remarkGfm).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeRaw).use(rehypeCallouts).use(rehypeSlug).use(rehypeAutolinkHeadings).use(rehypeCollectHeadings).use(rehypeStringify);
+function renderMarkdown(markdown) {
+  const file = processor.processSync(markdown);
+  const headings = file.data.headings ?? [];
+  const html = String(file);
+  return { html, headings };
+}
+function extractHeadings(html) {
+  const headings = [];
+  const regex = /<h([1-6])(?:\s[^>]*?\bid="([^"]*)"[^>]*?)?>([\s\S]*?)<\/h\1>/gi;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const level = Number.parseInt(match[1], 10);
+    const id = match[2] ?? "";
+    const text = match[3].replace(/<[^>]+>/g, "").trim();
+    headings.push({ id, text, level });
+  }
+  return headings;
+}
+
+// src/core/version.ts
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+function getPackageVersion() {
+  try {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+      try {
+        const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf-8"));
+        if (pkg.name === "docs-i18n") return pkg.version;
+      } catch {
+      }
+      dir = dirname(dir);
+    }
+  } catch {
+  }
+  return "unknown";
+}
 export {
   TranslationCache,
   assemble,
   defineConfig,
+  extractHeadings,
   extractTranslatableFields,
   flattenSources,
+  getPackageVersion,
   loadConfig,
   normalize,
   parseMdx,
-  reconstructFrontmatter
+  processor,
+  reconstructFrontmatter,
+  renderMarkdown
 };

package/dist/{rescan-O5D3CYC2.js → rescan-HXMWFAOC.js}

@@ -1,13 +1,15 @@
 import {
   init_parser,
   parseMdx
-} from "./chunk-YN4VJHCQ.js";
+} from "./chunk-JHBSHTXC.js";
 import {
   TranslationCache
-} from "./chunk-XEOYZUHS.js";
+} from "./chunk-QKIR7RKQ.js";
 import {
   flattenSources
-} from "./chunk-SKKZIV3L.js";
+} from "./chunk-TRURQFP4.js";
+import "./chunk-L64GJ4OB.js";
+import "./chunk-PNKVD2UK.js";
 
 // src/commands/rescan.ts
 import { existsSync, readdirSync, readFileSync } from "fs";

package/dist/{status-F4MYIAAY.js → status-AGZDXOTZ.js}

@@ -1,9 +1,11 @@
 import {
   TranslationCache
-} from "./chunk-XEOYZUHS.js";
+} from "./chunk-QKIR7RKQ.js";
 import {
   flattenSources
-} from "./chunk-SKKZIV3L.js";
+} from "./chunk-TRURQFP4.js";
+import "./chunk-L64GJ4OB.js";
+import "./chunk-PNKVD2UK.js";
 
 // src/commands/status.ts
 import { resolve } from "path";

package/dist/{translate-ZIVKNAC4.js → translate-A5X6MX4Y.js}

@@ -1,17 +1,20 @@
-import "./chunk-A3YQNPKZ.js";
+import "./chunk-CLYUAWZE.js";
 import {
   FRONTMATTER_TRANSLATABLE_FIELDS,
   init_parser
-} from "./chunk-YN4VJHCQ.js";
+} from "./chunk-JHBSHTXC.js";
 import {
   TranslationCache
-} from "./chunk-XEOYZUHS.js";
+} from "./chunk-QKIR7RKQ.js";
+import {
+  flattenSources
+} from "./chunk-TRURQFP4.js";
+import "./chunk-L64GJ4OB.js";
 import {
   __esm,
   __export,
-  __toCommonJS,
-  flattenSources
-} from "./chunk-SKKZIV3L.js";
+  __toCommonJS
+} from "./chunk-PNKVD2UK.js";
 
 // src/core/frontmatter.ts
 var frontmatter_exports = {};
@@ -262,7 +265,6 @@ function buildJsonUserMessage(uncached, nodeTypes) {
     const type = nodeTypes[md5] ?? "paragraph";
     if (type === "frontmatter") {
       const fields = extractTranslatableFields2(text);
-      if (Object.keys(fields).length === 0) continue;
       const fieldKeys = {};
       for (const [field, value] of Object.entries(fields)) {
         const virtualKey = `fm:${md5}:${field}`;
@@ -477,6 +479,11 @@ ${choice.message.content}
             log(
               `\u2705 Frontmatter ${fmMd5.substring(0, 8)}: ${Object.keys(fields).join(", ")}`
             );
+          } else if (Object.keys(info.fieldKeys).length === 0) {
+            translations[fmMd5] = info.source;
+            log(
+              `\u2705 Frontmatter ${fmMd5.substring(0, 8)}: no translatable fields, cached as-is`
+            );
           }
           if (!allFound) {
             const vKeys = new Set(Object.values(info.fieldKeys));

package/dist/upload-XL6KG6S2.js

@@ -0,0 +1,132 @@
+import {
+  openDatabase
+} from "./chunk-L64GJ4OB.js";
+import "./chunk-PNKVD2UK.js";
+
+// src/commands/upload.ts
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { resolve, relative, join } from "path";
+function collectContentFiles(projectRoot) {
+  const contentDir = resolve(projectRoot, "content");
+  if (!existsSync(contentDir)) {
+    throw new Error(`Content directory not found: ${contentDir}`);
+  }
+  const rows = [];
+  walkDir(contentDir, contentDir, rows);
+  return rows;
+}
+function walkDir(dir, contentRoot, rows) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    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"))) {
+      const relativePath = relative(contentRoot, fullPath);
+      const body = readFileSync(fullPath, "utf-8");
+      const parts = relativePath.split("/");
+      const { project, version, lang } = parseContentPath(parts);
+      rows.push({
+        path: relativePath,
+        body,
+        project,
+        version,
+        lang,
+        updated_at: Math.floor(Date.now() / 1e3)
+      });
+    }
+  }
+}
+function parseContentPath(parts) {
+  if (parts.length === 2) {
+    return { project: "default", version: "latest", lang: parts[0] };
+  }
+  if (parts.length === 3) {
+    if (isLangCode(parts[0])) {
+      return { project: "default", version: "latest", lang: parts[0] };
+    }
+    return { project: parts[0], version: "latest", lang: parts[1] };
+  }
+  if (parts.length >= 4) {
+    return { project: parts[0], version: parts[1], lang: parts[2] };
+  }
+  return { project: "default", version: "latest", lang: "en" };
+}
+function isLangCode(s) {
+  return /^[a-z]{2}(-[a-z]{2,})?$/.test(s);
+}
+function generateContentSql(rows) {
+  const statements = [];
+  statements.push(
+    `CREATE TABLE IF NOT EXISTS content (
+  path TEXT PRIMARY KEY NOT NULL,
+  body TEXT NOT NULL,
+  project TEXT NOT NULL,
+  version TEXT NOT NULL,
+  lang TEXT NOT NULL,
+  updated_at INTEGER
+);`
+  );
+  for (const row of rows) {
+    const escapedBody = row.body.replace(/'/g, "''");
+    const escapedPath = row.path.replace(/'/g, "''");
+    statements.push(
+      `INSERT OR REPLACE INTO content (path, body, project, version, lang, updated_at) VALUES ('${escapedPath}', '${escapedBody}', '${row.project}', '${row.version}', '${row.lang}', ${row.updated_at});`
+    );
+  }
+  return statements;
+}
+function collectTranslations(projectRoot) {
+  const dbPath = resolve(projectRoot, ".docs-i18n", "translations.db");
+  if (!existsSync(dbPath)) {
+    return { sources: [], translations: [] };
+  }
+  const db = openDatabase(dbPath);
+  try {
+    const sources = db.prepare("SELECT key, text, type FROM sources").all();
+    const translations = db.prepare("SELECT lang, key, value FROM translations").all();
+    return { sources, translations };
+  } finally {
+    db.close();
+  }
+}
+function generateTranslationSql(data) {
+  const statements = [];
+  statements.push(
+    `CREATE TABLE IF NOT EXISTS sources (
+  key TEXT PRIMARY KEY NOT NULL,
+  text TEXT NOT NULL,
+  type TEXT NOT NULL DEFAULT 'paragraph'
+);`
+  );
+  statements.push(
+    `CREATE TABLE IF NOT EXISTS translations (
+  lang TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  PRIMARY KEY (lang, key)
+);
+CREATE INDEX IF NOT EXISTS idx_translations_lang ON translations(lang);`
+  );
+  for (const s of data.sources) {
+    const escapedText = s.text.replace(/'/g, "''");
+    statements.push(
+      `INSERT OR REPLACE INTO sources (key, text, type) VALUES ('${s.key}', '${escapedText}', '${s.type}');`
+    );
+  }
+  for (const t of data.translations) {
+    const escapedValue = t.value.replace(/'/g, "''");
+    statements.push(
+      `INSERT INTO translations (lang, key, value) VALUES ('${t.lang}', '${t.key}', '${escapedValue}') ON CONFLICT(lang, key) DO UPDATE SET value = excluded.value, updated_at = unixepoch();`
+    );
+  }
+  return statements;
+}
+export {
+  collectContentFiles,
+  collectTranslations,
+  generateContentSql,
+  generateTranslationSql
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-i18n",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Universal documentation translation engine — parse, translate, cache, assemble, manage.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "src/admin",
+    "admin",
+    "template",
     "README.md"
   ],
   "scripts": {
@@ -22,8 +23,8 @@
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
+    "prepack": "rm -rf admin template && cp -r ../admin admin && cp -r ../template template && rm -rf admin/node_modules template/node_modules",
+    "postpack": "rm -rf admin template",
     "prepublishOnly": "rm -rf dist && tsup && chmod +x dist/cli.js"
   },
   "dependencies": {
@@ -31,25 +32,26 @@
     "glob": "^11.0.2",
     "hono": "^4.12.0",
     "openai": "^5.1.1",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-callouts": "^2.0.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-slug": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
     "remark": "^15.0.1",
-    "yaml": "^2.8.2",
-    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
-    "@vitejs/plugin-react": "^4.0.0 || ^5.0.0 || ^6.0.0",
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
-    "@tanstack/react-query": "^5.0.0"
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/bun": "^1.3.11",
+    "@types/hast": "^3.0.0",
     "@types/node": "^22.0.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
-    "vite": "^8.0.1",
+    "vfile": "^6.0.0",
     "vitest": "^3.2.0"
   },
   "publishConfig": {

package/template/app/components/BlogArticle.tsx

@@ -0,0 +1,159 @@
+/**
+ * Blog article component.
+ *
+ * Renders a single blog post with:
+ * - Author and date byline prepended to markdown
+ * - Full markdown content with TOC when headings > 1
+ * - Breadcrumb navigation back to blog list
+ * - Fallback banner when showing untranslated content
+ *
+ * Layout matches tanstack.com blog article page.
+ */
+
+import * as React from 'react'
+import { Link } from '@tanstack/react-router'
+import { renderMarkdown } from '~/utils/markdown'
+import { format } from '~/utils/dates'
+import { formatAuthors } from '~/utils/blog'
+import { MarkdownContent } from '~/components/markdown'
+import { Toc } from '~/components/Toc'
+import { Breadcrumbs } from '~/components/Breadcrumbs'
+import { FallbackBanner } from '~/components/FallbackBanner'
+import type { LoadedBlogPost } from '~/utils/blog'
+
+type BlogArticleProps = {
+  post: LoadedBlogPost
+  lang: string
+  /** Locale display name for fallback banner */
+  locale?: string
+}
+
+export function BlogArticle({ post, lang, locale }: BlogArticleProps) {
+  const { title, content, authors, published, filePath, isFallback } = post
+
+  // Prepend byline to content (matches tanstack.com pattern)
+  const blogContent = `<small>_by ${formatAuthors(authors)} on ${format(
+    new Date(published || 0),
+    'MMMM d, yyyy',
+  )}._</small>
+
+${content}`
+
+  const { headings, markup } = React.useMemo(
+    () => renderMarkdown(blogContent),
+    [blogContent],
+  )
+
+  const isTocVisible = headings.length > 1
+
+  const markdownContainerRef = React.useRef<HTMLDivElement>(null)
+  const [activeHeadings, setActiveHeadings] = React.useState<Array<string>>([])
+
+  const headingElementRefs = React.useRef<
+    Record<string, IntersectionObserverEntry>
+  >({})
+
+  React.useEffect(() => {
+    const callback = (headingsList: Array<IntersectionObserverEntry>) => {
+      headingElementRefs.current = headingsList.reduce(
+        (map, headingElement) => {
+          map[headingElement.target.id] = headingElement
+          return map
+        },
+        headingElementRefs.current,
+      )
+
+      const visibleHeadings: Array<IntersectionObserverEntry> = []
+      Object.keys(headingElementRefs.current).forEach((key) => {
+        const headingElement = headingElementRefs.current[key]
+        if (headingElement.isIntersecting) {
+          visibleHeadings.push(headingElement)
+        }
+      })
+
+      if (visibleHeadings.length >= 1) {
+        setActiveHeadings(visibleHeadings.map((h) => h.target.id))
+      }
+    }
+
+    const observer = new IntersectionObserver(callback, {
+      rootMargin: '0px',
+      threshold: 0.2,
+    })
+
+    const headingElements = Array.from(
+      markdownContainerRef.current?.querySelectorAll(
+        'h2[id], h3[id], h4[id], h5[id], h6[id]',
+      ) ?? [],
+    )
+    headingElements.forEach((el) => observer.observe(el))
+
+    return () => observer.disconnect()
+  }, [headings])
+
+  return (
+    <div
+      className={`
+        min-h-[calc(100dvh-var(--navbar-height))]
+        flex flex-col
+        w-full transition-all duration-300`}
+    >
+      <div className="flex flex-col max-w-full min-w-0 w-full min-h-0 relative mb-8">
+        <div className="min-w-0 flex justify-center w-full min-h-[88dvh] lg:min-h-0 mx-auto">
+          <div className="flex-1 flex flex-col w-full min-w-0">
+            <div className="px-4 pt-4 lg:pt-6">
+              <div className="w-full max-w-[1100px] mx-auto">
+                {isFallback && locale && <FallbackBanner locale={locale} />}
+                <div className="flex-1 min-h-0 flex flex-col">
+                  <div className="w-full flex justify-center">
+                    <div
+                      className={[
+                        'w-full p-2 lg:p-4 xl:p-6',
+                        isTocVisible ? 'max-w-full' : 'max-w-[768px]',
+                      ].join(' ')}
+                    >
+                      <Breadcrumbs
+                        section="Blog"
+                        sectionTo={`/${lang}/blog`}
+                        headings={isTocVisible ? headings : undefined}
+                        tocHiddenBreakpoint="lg"
+                      />
+                    </div>
+                    {isTocVisible && (
+                      <div className="pl-4 w-32 lg:w-36 xl:w-44 2xl:w-56 3xl:w-64 shrink-0 hidden lg:block" />
+                    )}
+                  </div>
+                  <div
+                    className={[
+                      'w-full flex justify-center mx-auto',
+                      isTocVisible ? 'max-w-full' : 'max-w-[768px]',
+                    ].join(' ')}
+                  >
+                    <div className="flex overflow-auto flex-col w-full p-2 lg:p-4 xl:p-6 pt-0">
+                      <MarkdownContent
+                        title={title}
+                        htmlMarkup={markup}
+                        repo=""
+                        branch=""
+                        filePath={filePath}
+                        containerRef={markdownContainerRef}
+                      />
+                    </div>
+                    {isTocVisible && (
+                      <div className="pl-4 w-32 lg:w-36 xl:w-44 2xl:w-56 3xl:w-64 shrink-0 hidden lg:block py-4 transition-all">
+                        <Toc
+                          headings={headings}
+                          activeHeadings={activeHeadings}
+                        />
+                      </div>
+                    )}
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}