docs-i18n 0.6.2 → 0.7.0

package/template/app/types/index.ts

@@ -0,0 +1,77 @@
+export interface SiteConfig {
+  name: string
+  description: string
+  repo: string
+  defaultLocale: string
+  supportedLocales: Record<string, string>
+  defaultProject?: string
+  projects: ProjectConfig[]
+  features: {
+    frameworkSelector: boolean
+    versionSelector: boolean
+    editOnGithub: boolean
+  }
+  /** When true and viewing the latest version, omit the version segment from URLs */
+  hideLatestVersion?: boolean
+  components?: Record<string, () => Promise<{ default: React.ComponentType<any> }>>
+}
+
+export interface ProjectConfig {
+  id: string
+  name: string
+  type: 'doc' | 'blog'
+  repo: string
+  latestVersion: string
+  latestBranch: string
+  availableVersions: string[]
+  docsRoot?: string
+  defaultDocs?: string
+  frameworks?: string[]
+  colorFrom: string
+  colorTo: string
+  textColor?: string
+  bgStyle?: string
+  borderStyle?: string
+  textStyle?: string
+  badge?: string
+  tagline?: string
+  description?: string
+}
+
+export interface MarkdownHeading {
+  id: string
+  level: number
+  text: string
+  framework?: string
+}
+
+export interface DocsConfig {
+  sections: DocsConfigSection[]
+}
+
+export interface DocsConfigSection {
+  label: string
+  children: DocsConfigItem[]
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  frameworks?: DocsConfigFramework[]
+}
+
+export interface DocsConfigItem {
+  label: string
+  to: string
+  badge?: string
+}
+
+export interface DocsConfigFramework {
+  label: string
+  children: DocsConfigItem[]
+}
+
+export interface LoadedDoc {
+  content: string
+  meta: Record<string, any>
+  locale: string
+  isFallback: boolean
+  filePath: string
+}

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

@@ -0,0 +1,193 @@
+/**
+ * Server-side blog content loading functions.
+ *
+ * Blog posts are stored as markdown files in content/blog/{lang}/{slug}.md
+ * with frontmatter: title, published, excerpt, authors, draft
+ *
+ * Uses the same filesystem loading pattern as docs.server.ts,
+ * with i18n fallback to English when a translation is missing.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import matter from 'gray-matter'
+
+// Re-export shared types and utilities from the non-server module
+export type { BlogPostMeta, LoadedBlogPost } from './blog'
+export { formatAuthors } from './blog'
+
+import type { BlogPostMeta, LoadedBlogPost } from './blog'
+
+/**
+ * Get the project root directory.
+ * Same resolution as docs.server.ts.
+ */
+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
+}
+
+// formatAuthors is re-exported from ./blog above
+
+/**
+ * Load all published blog posts for a given locale, sorted newest first.
+ *
+ * Resolution:
+ * 1. Scan content/blog/en/ for all .md files (source of truth for available posts)
+ * 2. For each post, try content/blog/{lang}/{slug}.md first, fallback to en
+ * 3. Filter out drafts and future-dated posts
+ * 4. Sort by published date descending
+ */
+export function loadBlogPosts(lang: string): BlogPostMeta[] {
+  const root = getProjectRoot()
+  const enDir = resolve(root, 'content', 'blog', 'en')
+
+  if (!existsSync(enDir)) {
+    return []
+  }
+
+  const now = new Date()
+  const posts: BlogPostMeta[] = []
+
+  try {
+    const files = readdirSync(enDir).filter((f) => f.endsWith('.md'))
+
+    for (const file of files) {
+      const slug = file.replace(/\.md$/, '')
+      const meta = loadPostMeta(root, lang, slug)
+
+      if (!meta) continue
+      // Filter drafts and future posts
+      if (meta.draft) continue
+      if (new Date(meta.published) > now) continue
+
+      posts.push(meta)
+    }
+  } catch {
+    // ignore read errors
+  }
+
+  // Sort newest first
+  posts.sort(
+    (a, b) =>
+      new Date(b.published).getTime() - new Date(a.published).getTime(),
+  )
+
+  return posts
+}
+
+/**
+ * Load a single blog post by slug with i18n fallback.
+ *
+ * Resolution:
+ * 1. content/blog/{lang}/{slug}.md
+ * 2. content/blog/en/{slug}.md (fallback, isFallback = true)
+ */
+export function loadBlogPost(lang: string, slug: string): LoadedBlogPost | null {
+  const root = getProjectRoot()
+
+  // Try requested language
+  const langPath = resolve(root, 'content', 'blog', lang, `${slug}.md`)
+  if (existsSync(langPath)) {
+    return parsePostFile(langPath, slug, lang, false)
+  }
+
+  // Fallback to English
+  if (lang !== 'en') {
+    const enPath = resolve(root, 'content', 'blog', 'en', `${slug}.md`)
+    if (existsSync(enPath)) {
+      return parsePostFile(enPath, slug, 'en', true)
+    }
+  }
+
+  return null
+}
+
+/**
+ * Load just the metadata for a blog post (used for listing).
+ */
+function loadPostMeta(
+  root: string,
+  lang: string,
+  slug: string,
+): BlogPostMeta | null {
+  // Try requested language
+  const langPath = resolve(root, 'content', 'blog', lang, `${slug}.md`)
+  if (existsSync(langPath)) {
+    return parsePostMeta(langPath, slug)
+  }
+
+  // Fallback to English
+  if (lang !== 'en') {
+    const enPath = resolve(root, 'content', 'blog', 'en', `${slug}.md`)
+    if (existsSync(enPath)) {
+      return parsePostMeta(enPath, slug)
+    }
+  }
+
+  return null
+}
+
+function parsePostMeta(filePath: string, slug: string): BlogPostMeta | null {
+  try {
+    const raw = readFileSync(filePath, 'utf-8')
+    const { data, content } = matter(raw)
+
+    // Extract header image from first markdown image
+    const headerImageMatch = content.match(/!\[([^\]]*)\]\(([^)]+)\)/)
+    const headerImage = headerImageMatch ? headerImageMatch[2] : undefined
+
+    return {
+      slug,
+      title: (data.title as string) || slug,
+      published: (data.published as string) || '',
+      excerpt: (data.excerpt as string) || '',
+      authors: Array.isArray(data.authors) ? data.authors : [],
+      draft: data.draft === true,
+      headerImage,
+    }
+  } catch {
+    return null
+  }
+}
+
+function parsePostFile(
+  filePath: string,
+  slug: string,
+  locale: string,
+  isFallback: boolean,
+): LoadedBlogPost {
+  const raw = readFileSync(filePath, 'utf-8')
+  const { data, content } = matter(raw)
+
+  // Extract header image from first markdown image
+  const headerImageMatch = content.match(/!\[([^\]]*)\]\(([^)]+)\)/)
+  const headerImage = headerImageMatch ? headerImageMatch[2] : undefined
+
+  return {
+    slug,
+    title: (data.title as string) || slug,
+    published: (data.published as string) || '',
+    excerpt: (data.excerpt as string) || '',
+    authors: Array.isArray(data.authors) ? data.authors : [],
+    draft: data.draft === true,
+    headerImage,
+    content,
+    locale,
+    isFallback,
+    filePath,
+  }
+}

package/template/app/utils/blog.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared blog utilities — safe for both client and server.
+ */
+
+/**
+ * Intl-based author list formatter.
+ */
+const listJoiner = new Intl.ListFormat('en-US', {
+  style: 'long',
+  type: 'conjunction',
+})
+
+export function formatAuthors(authors: string[]): string {
+  if (!authors.length) return 'Unknown'
+  return listJoiner.format(authors)
+}
+
+/** Metadata parsed from blog post frontmatter */
+export interface BlogPostMeta {
+  slug: string
+  title: string
+  published: string
+  excerpt: string
+  authors: string[]
+  draft?: boolean
+  headerImage?: string
+}
+
+/** A fully loaded blog post with content */
+export interface LoadedBlogPost {
+  slug: string
+  title: string
+  published: string
+  excerpt: string
+  authors: string[]
+  draft?: boolean
+  headerImage?: string
+  content: string
+  locale: string
+  isFallback: boolean
+  filePath: string
+}

package/template/app/utils/config.ts

@@ -0,0 +1,120 @@
+/**
+ * Config utilities for parsing and validating docs config.json files.
+ *
+ * Follows the same schema as tanstack.com's config.json:
+ * - sections: array of sidebar sections
+ * - Each section has label, children, optional frameworks, collapsible, defaultCollapsed
+ * - Children have label, to, optional badge
+ */
+
+import type { DocsConfig, DocsConfigSection, DocsConfigItem, DocsConfigFramework } from '~/types'
+
+/**
+ * Validate and normalize a raw config.json object into a typed DocsConfig.
+ * Returns null if the input is invalid.
+ */
+export function parseDocsConfig(raw: unknown): DocsConfig | null {
+  if (!raw || typeof raw !== 'object') return null
+
+  const obj = raw as Record<string, unknown>
+  if (!Array.isArray(obj.sections)) return null
+
+  const sections: DocsConfigSection[] = []
+
+  for (const section of obj.sections) {
+    if (!section || typeof section !== 'object') continue
+    const s = section as Record<string, unknown>
+
+    if (typeof s.label !== 'string') continue
+    if (!Array.isArray(s.children)) continue
+
+    const children = parseConfigItems(s.children)
+    const frameworks = s.frameworks ? parseFrameworks(s.frameworks) : undefined
+
+    sections.push({
+      label: s.label,
+      children,
+      collapsible: typeof s.collapsible === 'boolean' ? s.collapsible : undefined,
+      defaultCollapsed: typeof s.defaultCollapsed === 'boolean' ? s.defaultCollapsed : undefined,
+      frameworks,
+    })
+  }
+
+  return { sections }
+}
+
+function parseConfigItems(items: unknown[]): DocsConfigItem[] {
+  const result: DocsConfigItem[] = []
+
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue
+    const i = item as Record<string, unknown>
+
+    if (typeof i.label !== 'string' || typeof i.to !== 'string') continue
+
+    result.push({
+      label: i.label,
+      to: i.to,
+      badge: typeof i.badge === 'string' ? i.badge : undefined,
+    })
+  }
+
+  return result
+}
+
+function parseFrameworks(frameworks: unknown): DocsConfigFramework[] | undefined {
+  if (!Array.isArray(frameworks)) return undefined
+
+  const result: DocsConfigFramework[] = []
+
+  for (const fw of frameworks) {
+    if (!fw || typeof fw !== 'object') continue
+    const f = fw as Record<string, unknown>
+
+    if (typeof f.label !== 'string') continue
+    if (!Array.isArray(f.children)) continue
+
+    result.push({
+      label: f.label,
+      children: parseConfigItems(f.children),
+    })
+  }
+
+  return result.length > 0 ? result : undefined
+}
+
+/**
+ * Build sidebar menu items from a DocsConfig, resolving paths
+ * relative to the current route.
+ */
+export function buildSidebarItems(
+  config: DocsConfig,
+  basePath: string,
+  framework?: string,
+) {
+  return config.sections.map((section) => {
+    const children = section.children.map((item) => ({
+      ...item,
+      to: `${basePath}/${item.to}`,
+    }))
+
+    // If framework is specified, also include framework-specific items
+    let frameworkChildren: DocsConfigItem[] = []
+    if (framework && section.frameworks) {
+      const fwSection = section.frameworks.find(
+        (fw) => fw.label.toLowerCase() === framework.toLowerCase(),
+      )
+      if (fwSection) {
+        frameworkChildren = fwSection.children.map((item) => ({
+          ...item,
+          to: `${basePath}/framework/${framework}/${item.to}`,
+        }))
+      }
+    }
+
+    return {
+      ...section,
+      children: [...children, ...frameworkChildren],
+    }
+  })
+}