docs-i18n 0.6.2 → 0.7.0

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

@@ -0,0 +1,400 @@
+/**
+ * Content loading abstraction — filesystem for dev, D1 for production.
+ *
+ * The ContentLoader interface provides a uniform API for loading documents,
+ * docs config, and listing docs regardless of whether content lives on disk
+ * or in a D1 database.
+ */
+
+import type { LoadedDoc, DocsConfig } from '~/types'
+
+export interface ContentLoader {
+  /** Load a single document with i18n fallback. */
+  loadDoc(
+    project: string,
+    version: string,
+    lang: string,
+    slug: string,
+  ): Promise<LoadedDoc>
+
+  /** Load sidebar config for a project/version. */
+  loadDocsConfig(
+    project: string,
+    version: string,
+  ): Promise<DocsConfig | null>
+
+  /** List available doc slugs for a project/version/lang. */
+  listDocs(
+    project: string,
+    version: string,
+    lang: string,
+    dir?: string,
+  ): Promise<string[]>
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem loader (local development)
+// ---------------------------------------------------------------------------
+
+import {
+  readFileSync,
+  existsSync,
+  readdirSync,
+  statSync,
+} from 'node:fs'
+import { resolve, relative, join } from 'node:path'
+import matter from 'gray-matter'
+import { TranslationCache, assemble } from 'docs-i18n'
+
+/** Singleton cache instance (lazily created, shared across requests) */
+let _translationCache: TranslationCache | null = null
+
+function getTranslationCache(projectRoot: string): TranslationCache | null {
+  if (_translationCache) return _translationCache
+  const cacheDir = resolve(projectRoot, '.cache')
+  const dbPath = resolve(cacheDir, 'translations.db')
+  if (!existsSync(dbPath)) return null
+  try {
+    _translationCache = new TranslationCache(cacheDir)
+    return _translationCache
+  } catch {
+    return null
+  }
+}
+
+export function createFsLoader(projectRoot: string): ContentLoader {
+  /**
+   * Read a raw .md file from one of the candidate base directories.
+   * Returns the raw file content and resolved path, or null.
+   */
+  function readRawFile(
+    project: string,
+    version: string,
+    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`),
+    ]
+    for (const filePath of candidates) {
+      if (existsSync(filePath)) {
+        return { raw: readFileSync(filePath, 'utf-8'), filePath }
+      }
+    }
+    return null
+  }
+
+  function parseRawDoc(
+    raw: string,
+    filePath: string,
+    locale: string,
+    isFallback: boolean,
+  ): LoadedDoc {
+    const { data, content } = matter(raw)
+    return {
+      content,
+      meta: { title: (data.title as string) || '', ...data },
+      locale,
+      isFallback,
+      filePath,
+    }
+  }
+
+  function tryLoadConfig(configPath: string): DocsConfig | null {
+    if (existsSync(configPath)) {
+      return JSON.parse(readFileSync(configPath, 'utf-8'))
+    }
+    return null
+  }
+
+  function scanDirectory(dir: string, base: string): string[] {
+    const slugs: string[] = []
+    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$/, ''))
+        } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          slugs.push(...scanDirectory(join(dir, entry.name), base))
+        }
+      }
+    } catch {
+      // ignore read errors
+    }
+    return slugs
+  }
+
+  return {
+    async loadDoc(project, version, lang, slug) {
+      // For EN, just read the file directly
+      if (lang === 'en') {
+        const en = readRawFile(project, version, 'en', slug)
+        if (en) return parseRawDoc(en.raw, en.filePath, 'en', false)
+        throw new Error(
+          `Document not found: ${project}/${version}/en/${slug}`,
+        )
+      }
+
+      // For non-EN: always read the EN source first
+      const en = readRawFile(project, version, 'en', slug)
+      if (!en) {
+        throw new Error(
+          `Document not found: ${project}/${version}/${lang}/${slug}`,
+        )
+      }
+
+      // Try to assemble from translation cache
+      const cache = getTranslationCache(projectRoot)
+      if (cache) {
+        try {
+          const sourceFilePath = `${slug}.md`
+          const result = assemble(
+            en.raw,
+            lang,
+            cache,
+            sourceFilePath,
+            true, // fallbackToSource — use EN text for untranslated nodes
+          )
+
+          if (result.cachedCount > 0) {
+            // At least some translations found — return assembled content
+            const { data, content } = matter(result.content)
+            return {
+              content,
+              meta: { title: (data.title as string) || '', ...data },
+              locale: lang,
+              isFallback: false,
+              filePath: en.filePath,
+            }
+          }
+        } catch {
+          // Cache read failed, fall through to EN fallback
+        }
+      }
+
+      // No translations available — fall back to EN content
+      return parseRawDoc(en.raw, en.filePath, 'en', true)
+    },
+
+    async loadDocsConfig(project, version) {
+      // Try versioned config
+      const v = tryLoadConfig(
+        resolve(projectRoot, 'content', project, version, 'en', 'config.json'),
+      )
+      if (v) return v
+
+      // Try project-level config (docs.config.json)
+      const p = tryLoadConfig(
+        resolve(projectRoot, 'content', project, 'docs.config.json'),
+      )
+      if (p) return p
+
+      // Try project-level config (config.json)
+      const p2 = tryLoadConfig(
+        resolve(projectRoot, 'content', project, 'config.json'),
+      )
+      if (p2) return p2
+
+      // Try legacy single-project config
+      const l = tryLoadConfig(
+        resolve(projectRoot, 'content', 'docs.config.json'),
+      )
+      if (l) return l
+
+      return null
+    },
+
+    async listDocs(project, version, lang, dir) {
+      // Try requested lang first, then fall back to EN
+      // (translated content comes from the cache, so non-EN dirs may not exist on disk)
+      const langsToTry = lang === 'en' ? ['en'] : [lang, 'en']
+
+      for (const tryLang of langsToTry) {
+        const candidates = [
+          resolve(projectRoot, 'content', project, version, tryLang),
+          resolve(projectRoot, 'content', project, tryLang),
+          resolve(projectRoot, 'content', tryLang),
+        ]
+
+        for (const base of candidates) {
+          const searchDir = dir ? resolve(base, dir) : base
+          if (existsSync(searchDir) && statSync(searchDir).isDirectory()) {
+            const slugs = scanDirectory(searchDir, base)
+            if (slugs.length > 0) return slugs
+          }
+        }
+      }
+
+      return []
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// D1 loader (production)
+// ---------------------------------------------------------------------------
+
+import { eq, and, like } from 'drizzle-orm'
+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
+      const row = await db
+        .select()
+        .from(schema.content)
+        .where(eq(schema.content.path, path))
+        .get()
+
+      if (row) {
+        const { data, content } = matter(row.body)
+        return {
+          content,
+          meta: { title: (data.title as string) || '', ...data },
+          locale: lang,
+          isFallback: false,
+          filePath: 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)
+          return {
+            content,
+            meta: { title: (data.title as string) || '', ...data },
+            locale: 'en',
+            isFallback: true,
+            filePath: enPath,
+          }
+        }
+      }
+
+      throw new Error(
+        `Document not found: ${project}/${version}/${lang}/${slug}`,
+      )
+    },
+
+    async loadDocsConfig(project, version) {
+      // Config stored as a special content entry
+      const configPath = `${project}/${version}/en/config.json`
+      const row = await db
+        .select()
+        .from(schema.content)
+        .where(eq(schema.content.path, configPath))
+        .get()
+
+      if (row) {
+        return JSON.parse(row.body)
+      }
+
+      // Try project-level docs.config.json
+      const docsConfigPath = `${project}/docs.config.json`
+      const row1b = await db
+        .select()
+        .from(schema.content)
+        .where(eq(schema.content.path, docsConfigPath))
+        .get()
+
+      if (row1b) {
+        return JSON.parse(row1b.body)
+      }
+
+      // Try project-level config.json
+      const projectConfigPath = `${project}/config.json`
+      const row2 = await db
+        .select()
+        .from(schema.content)
+        .where(eq(schema.content.path, projectConfigPath))
+        .get()
+
+      if (row2) {
+        return JSON.parse(row2.body)
+      }
+
+      return null
+    },
+
+    async listDocs(project, version, lang, dir) {
+      const prefix = dir
+        ? `${project}/${version}/${lang}/${dir}/`
+        : `${project}/${version}/${lang}/`
+
+      const rows = await db
+        .select({ path: schema.content.path })
+        .from(schema.content)
+        .where(
+          and(
+            like(schema.content.path, `${prefix}%`),
+            eq(schema.content.project, project),
+            eq(schema.content.version, version),
+            eq(schema.content.lang, lang),
+          ),
+        )
+        .all()
+
+      return rows
+        .map((r) => r.path.replace(prefix, '').replace(/\.md$/, ''))
+        .filter((s) => s.length > 0)
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory — selects loader based on environment
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the project root directory.
+ * Uses the same pattern as docs-i18n admin:
+ * 1. DOCS_I18N_PROJECT_ROOT env var
+ * 2. Temp file written by the CLI
+ * 3. Falls back to cwd
+ */
+function getProjectRoot(): string {
+  if (process.env.DOCS_I18N_PROJECT_ROOT) {
+    return process.env.DOCS_I18N_PROJECT_ROOT
+  }
+  // Prefer cwd if it has a content directory (avoids stale temp file from another project)
+  const cwd = process.cwd()
+  if (existsSync(resolve(cwd, 'content'))) {
+    return cwd
+  }
+  try {
+    const tmpDir = process.env.TMPDIR || process.env.TEMP || '/tmp'
+    return readFileSync(resolve(tmpDir, 'docs-i18n-project-root'), 'utf-8').trim()
+  } catch {
+    // ignore
+  }
+  return cwd
+}
+
+/**
+ * Create a content loader based on the current environment.
+ *
+ * - In production with a D1 binding: uses D1Loader
+ * - Otherwise: uses FsLoader reading from the project root
+ *
+ * For D1 in production, pass the D1 database instance.
+ * When no D1 is available, falls back to filesystem.
+ */
+export function getContentLoader(d1?: D1Database): ContentLoader {
+  if (d1) {
+    return createD1Loader(createDb(d1))
+  }
+  return createFsLoader(getProjectRoot())
+}

package/template/app/utils/dates.ts

@@ -0,0 +1,29 @@
+// Native date formatting utilities (ported from tanstack.com)
+// Uses Intl.DateTimeFormat — no external dependencies
+
+export function format(date: Date | number, formatStr: string): string {
+  const d = typeof date === 'number' ? new Date(date) : date
+
+  switch (formatStr) {
+    case 'MMMM d, yyyy':
+      return d.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+      })
+
+    case 'MMM d, yyyy':
+      return d.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      })
+
+    default:
+      return d.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      })
+  }
+}

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

@@ -0,0 +1,150 @@
+/**
+ * Server-side content loading functions.
+ *
+ * Uses the ContentLoader abstraction to support both filesystem (dev)
+ * and D1 (production) content sources.
+ */
+
+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 ContentLoader, createFsLoader } from './content-loader'
+
+/**
+ * Get the project root directory.
+ * Uses the same pattern as docs-i18n admin:
+ * 1. DOCS_I18N_PROJECT_ROOT env var
+ * 2. Temp file written by the CLI
+ * 3. Falls back to cwd
+ */
+function getProjectRoot(): string {
+  if (process.env.DOCS_I18N_PROJECT_ROOT) {
+    return process.env.DOCS_I18N_PROJECT_ROOT
+  }
+  // Prefer cwd if it has a content directory (avoids stale temp file from another project)
+  const cwd = process.cwd()
+  if (existsSync(resolve(cwd, 'content'))) {
+    return cwd
+  }
+  try {
+    const tmpDir = process.env.TMPDIR || process.env.TEMP || '/tmp'
+    return readFileSync(resolve(tmpDir, 'docs-i18n-project-root'), 'utf-8').trim()
+  } catch {
+    // ignore
+  }
+  return cwd
+}
+
+/** Cached content loader instance. */
+let _loader: ContentLoader | null = null
+
+/**
+ * Get or create the content loader.
+ * In dev mode, uses filesystem. In production with D1, uses D1.
+ * The D1 loader is activated by calling `setD1Loader()` from the server entry.
+ */
+export function getLoader(): ContentLoader {
+  if (!_loader) {
+    _loader = createFsLoader(getProjectRoot())
+  }
+  return _loader
+}
+
+/**
+ * Set a custom content loader (e.g., D1-backed for production).
+ * Called from the server entry point when a D1 binding is available.
+ */
+export function setContentLoader(loader: ContentLoader) {
+  _loader = loader
+}
+
+/**
+ * Load a document with i18n fallback.
+ * Delegates to the active ContentLoader.
+ */
+export async function loadDoc(
+  project: string,
+  version: string,
+  lang: string,
+  slug: string,
+): Promise<LoadedDoc> {
+  return getLoader().loadDoc(project, version, lang, slug)
+}
+
+/**
+ * Load docs config (config.json for sidebar structure).
+ * Delegates to the active ContentLoader, with auto-scan fallback.
+ */
+export async function loadDocsConfig(
+  project: string,
+  version: string,
+): Promise<DocsConfig> {
+  const config = await getLoader().loadDocsConfig(project, version)
+  if (config) return config
+
+  // Auto-scan fallback (filesystem only)
+  return autoScanDocs(getProjectRoot(), project, version)
+}
+
+/**
+ * Auto-generate sidebar config by scanning .md files in the content directory.
+ */
+function autoScanDocs(
+  root: string,
+  project: string,
+  version: string,
+): DocsConfig {
+  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 items = scanDirectory(dir, dir)
+      if (items.length > 0) {
+        return {
+          sections: [
+            {
+              label: 'Documentation',
+              children: items,
+            },
+          ],
+        }
+      }
+    }
+  }
+
+  return { sections: [] }
+}
+
+function scanDirectory(dir: string, base: string): DocsConfigItem[] {
+  const items: DocsConfigItem[] = []
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const relativePath = relative(base, join(dir, entry.name))
+        const slug = relativePath.replace(/\.md$/, '')
+        // Read frontmatter for title
+        const filePath = join(dir, entry.name)
+        const raw = readFileSync(filePath, 'utf-8')
+        const { data } = matter(raw)
+        items.push({
+          label: (data.title as string) || slug,
+          to: slug,
+        })
+      } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        const subItems = scanDirectory(join(dir, entry.name), base)
+        items.push(...subItems)
+      }
+    }
+  } catch {
+    // ignore read errors
+  }
+
+  return items
+}