docs-i18n 0.6.3 → 0.7.0

package/template/app/routes/$lang.$project.tsx

@@ -0,0 +1,89 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+import { notFound, Outlet, useParams } from '@tanstack/react-router'
+import { findProject, siteConfig } from '~/site.config'
+
+export const Route = createFileRoute('/$lang/$project')({
+  beforeLoad: (ctx) => {
+    const project = findProject(ctx.params.project)
+
+    if (!project) {
+      throw notFound()
+    }
+  },
+  loader: (ctx) => {
+    const project = findProject(ctx.params.project)
+
+    if (!project) {
+      throw notFound()
+    }
+  },
+  head: (ctx) => {
+    const project = findProject(ctx.params.project)
+
+    if (!project) {
+      return {
+        meta: [{ title: '404 Not Found' }],
+      }
+    }
+
+    const frameworkTitle = project.frameworks?.length
+      ? ` | ${project.frameworks
+          .map(
+            (framework) =>
+              `${framework.charAt(0).toUpperCase()}${framework.slice(1)} ${project.name}`,
+          )
+          .join(', ')}`
+      : ''
+
+    return {
+      meta: [
+        {
+          title: `${project.name}${frameworkTitle}`,
+        },
+        ...(project.description
+          ? [{ name: 'description', content: project.description }]
+          : []),
+      ],
+    }
+  },
+  component: ProjectLayout,
+  staticData: {
+    Title: () => {
+      const { project: projectId } = Route.useParams()
+      const { version } = useParams({ strict: false })
+      const project = findProject(projectId)
+
+      if (!project) {
+        return null
+      }
+
+      const projectName = project.name
+      const resolvedVersion =
+        version === 'latest' ? project.latestVersion : version!
+      const gradientText = `inline-block text-transparent bg-clip-text bg-linear-to-r ${project.colorFrom} ${project.colorTo}`
+      return (
+        <Link
+          to={`/$lang/$project`}
+          params={{ lang: siteConfig.defaultLocale, project: projectId }}
+          className="relative whitespace-nowrap"
+        >
+          <span className={`${gradientText}`}>{projectName}</span>{' '}
+          {resolvedVersion && resolvedVersion !== 'latest' && (
+            <>
+              <span className="text-sm absolute right-0 top-0 font-normal normal-case">
+                {resolvedVersion}
+              </span>
+              <span className="text-sm opacity-0 normal-case">
+                {resolvedVersion}
+              </span>
+            </>
+          )}
+        </Link>
+      )
+    },
+  },
+})
+
+function ProjectLayout() {
+  return <Outlet />
+}

package/template/app/routes/$lang.blog.$.tsx

@@ -0,0 +1,82 @@
+/**
+ * Blog article route — renders a single blog post.
+ *
+ * Loads post content via server function with i18n fallback.
+ * Uses splat route to support any slug depth (e.g., /en/blog/my-post).
+ */
+
+import { notFound, createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { siteConfig } from '~/site.config'
+import { formatAuthors } from '~/utils/blog'
+import { BlogArticle } from '~/components/BlogArticle'
+import { PostNotFound } from '~/components/PostNotFound'
+
+const fetchBlogPost = createServerFn({ method: 'GET' })
+  .inputValidator((data: { lang: string; slug: string }) => data)
+  .handler(async ({ data }) => {
+    const { loadBlogPost } = await import('~/utils/blog.server')
+    const post = loadBlogPost(data.lang, data.slug)
+
+    if (!post) {
+      throw notFound()
+    }
+
+    // Hide drafts and future-dated posts
+    const now = new Date()
+    const publishDate = new Date(post.published)
+    const isUnpublished = post.draft || publishDate > now
+
+    return {
+      ...post,
+      isUnpublished,
+    }
+  },
+)
+
+export const Route = createFileRoute('/$lang/blog/$')({
+  staleTime: Infinity,
+  loader: ({ params }) =>
+    fetchBlogPost({
+      data: {
+        lang: params.lang,
+        slug: params._splat || '',
+      },
+    }),
+  head: ({ loaderData }) => ({
+    meta: loaderData
+      ? [
+          {
+            title: `${loaderData.title} | ${siteConfig.name} Blog`,
+          },
+          {
+            name: 'description',
+            content: loaderData.excerpt,
+          },
+          {
+            name: 'author',
+            content: `${
+              loaderData.authors.length > 1 ? 'co-authored by ' : ''
+            }${formatAuthors(loaderData.authors)}`,
+          },
+        ]
+      : [],
+  }),
+  notFoundComponent: () => <PostNotFound />,
+  component: BlogPostPage,
+})
+
+function BlogPostPage() {
+  const post = Route.useLoaderData()
+  const { lang } = Route.useParams()
+  const localeName =
+    siteConfig.supportedLocales[lang] || lang
+
+  return (
+    <BlogArticle
+      post={post}
+      lang={lang}
+      locale={localeName}
+    />
+  )
+}

package/template/app/routes/$lang.blog.index.tsx

@@ -0,0 +1,56 @@
+/**
+ * Blog index route — lists all published blog posts.
+ *
+ * Loads blog post metadata via server function, renders using BlogList component.
+ * Posts are sorted by published date (newest first), drafts are excluded.
+ */
+
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { siteConfig } from '~/site.config'
+import { BlogList } from '~/components/BlogList'
+import { PostNotFound } from '~/components/PostNotFound'
+
+const fetchBlogPosts = createServerFn({ method: 'GET' })
+  .inputValidator((data: { lang: string }) => data)
+  .handler(async ({ data }) => {
+    const { loadBlogPosts } = await import('~/utils/blog.server')
+    return loadBlogPosts(data.lang)
+  })
+
+export const Route = createFileRoute('/$lang/blog/')({
+  staleTime: Infinity,
+  loader: ({ params }) => fetchBlogPosts({ data: { lang: params.lang } }),
+  notFoundComponent: () => <PostNotFound />,
+  head: () => ({
+    meta: [
+      {
+        title: `Blog | ${siteConfig.name}`,
+      },
+    ],
+  }),
+  component: BlogIndex,
+})
+
+function BlogIndex() {
+  const posts = Route.useLoaderData()
+  const { lang } = Route.useParams()
+
+  return (
+    <div className="flex flex-col max-w-full min-h-screen gap-12 p-4 md:p-8 pb-0">
+      <div className="flex-1 w-full max-w-[1400px] mx-auto">
+        <div className="flex gap-8 items-start">
+          <div className="flex-1 space-y-12 min-w-0">
+            <header>
+              <h1 className="text-3xl font-black">Blog</h1>
+              <p className="text-lg mt-4 text-gray-600 dark:text-gray-400">
+                The latest news and blog posts
+              </p>
+            </header>
+            <BlogList posts={posts} lang={lang} />
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/template/app/routes/$lang.blog.tsx

@@ -0,0 +1,26 @@
+/**
+ * Blog layout route.
+ *
+ * Simple wrapper — no sidebar, just navbar + content.
+ * The navbar is already rendered by __root.tsx.
+ */
+
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { siteConfig } from '~/site.config'
+import { PostNotFound } from '~/components/PostNotFound'
+
+export const Route = createFileRoute('/$lang/blog')({
+  head: () => ({
+    meta: [
+      {
+        title: `Blog | ${siteConfig.name}`,
+      },
+    ],
+  }),
+  component: BlogLayout,
+  notFoundComponent: PostNotFound,
+})
+
+function BlogLayout() {
+  return <Outlet />
+}

package/template/app/routes/$lang.docs.$.tsx

@@ -0,0 +1,100 @@
+import {
+  createFileRoute,
+  notFound,
+} from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { siteConfig, isSingleProject, getSingleProject } from '~/site.config'
+import { Doc } from '~/components/Doc'
+
+const fetchDoc = createServerFn({ method: 'GET' })
+  .inputValidator(
+    (data: { project: string; version: string; lang: string; slug: string }) =>
+      data,
+  )
+  .handler(async ({ data }) => {
+    const { loadDoc } = await import('~/utils/docs.server')
+    return loadDoc(data.project, data.version, data.lang, data.slug)
+  })
+
+export const Route = createFileRoute('/$lang/docs/$')({
+  staleTime: 1000 * 60 * 5,
+  beforeLoad: () => {
+    if (!isSingleProject()) {
+      throw notFound()
+    }
+  },
+  loader: async ({ params }) => {
+    const { lang, _splat: slug } = params
+    if (!slug) throw notFound()
+
+    const project = getSingleProject()
+
+    try {
+      return await fetchDoc({
+        data: {
+          project: project.id,
+          version: project.latestVersion,
+          lang,
+          slug,
+        },
+      })
+    } catch (error) {
+      throw notFound()
+    }
+  },
+  head: ({ loaderData }) => {
+    const project = getSingleProject()
+    const title = loaderData?.meta?.title
+    const projectName = project?.name || siteConfig.name
+
+    return {
+      meta: [
+        {
+          title: title ? `${title} | ${projectName} Docs` : `${projectName} Docs`,
+        },
+        ...(loaderData?.meta?.description
+          ? [{ name: 'description', content: loaderData.meta.description }]
+          : []),
+      ],
+    }
+  },
+  headers: () => {
+    return {
+      'cache-control': 'public, max-age=60, must-revalidate',
+      'cdn-cache-control':
+        'max-age=600, stale-while-revalidate=3600, durable',
+      vary: 'Accept-Encoding',
+    }
+  },
+  component: SingleProjectDocsPage,
+  errorComponent: DocNotFound,
+})
+
+function SingleProjectDocsPage() {
+  const loaderData = Route.useLoaderData()
+  const project = getSingleProject()
+
+  return (
+    <Doc
+      title={loaderData.meta?.title || ''}
+      content={loaderData.content}
+      isFallback={loaderData.isFallback}
+      filePath={loaderData.filePath}
+      repo={project.repo}
+      branch={project.latestBranch}
+    />
+  )
+}
+
+function DocNotFound() {
+  return (
+    <div className="flex-1 flex items-center justify-center py-20">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold mb-2">Page Not Found</h1>
+        <p className="text-gray-500 dark:text-gray-400">
+          The document you are looking for does not exist.
+        </p>
+      </div>
+    </div>
+  )
+}

package/template/app/routes/$lang.docs.framework.$framework.$.tsx

@@ -0,0 +1,104 @@
+import {
+  createFileRoute,
+  notFound,
+  redirect,
+} from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { siteConfig, isSingleProject, getSingleProject } from '~/site.config'
+import { Doc } from '~/components/Doc'
+
+const fetchFrameworkDoc = createServerFn({ method: 'GET' })
+  .inputValidator(
+    (data: {
+      project: string
+      version: string
+      lang: string
+      framework: string
+      slug: string
+    }) => data,
+  )
+  .handler(async ({ data }) => {
+    const { loadDoc } = await import('~/utils/docs.server')
+    return loadDoc(
+      data.project,
+      data.version,
+      data.lang,
+      `framework/${data.framework}/${data.slug}`,
+    )
+  })
+
+export const Route = createFileRoute(
+  '/$lang/docs/framework/$framework/$',
+)({
+  staleTime: 1000 * 60 * 5,
+  beforeLoad: () => {
+    if (!isSingleProject()) {
+      throw notFound()
+    }
+  },
+  loader: async ({ params }) => {
+    const { lang, framework, _splat: slug } = params
+    const project = getSingleProject()
+
+    try {
+      return await fetchFrameworkDoc({
+        data: {
+          project: project.id,
+          version: project.latestVersion,
+          lang,
+          framework,
+          slug: slug || '',
+        },
+      })
+    } catch (error) {
+      throw redirect({
+        to: '/$lang/docs/framework/$framework',
+        params: { lang, framework },
+      })
+    }
+  },
+  head: ({ loaderData, params }) => {
+    const project = getSingleProject()
+    const projectName = project?.name || siteConfig.name
+    const framework =
+      params.framework.charAt(0).toUpperCase() + params.framework.slice(1)
+    const title = loaderData?.meta?.title
+
+    return {
+      meta: [
+        {
+          title: title
+            ? `${title} | ${projectName} ${framework} Docs`
+            : `${projectName} ${framework} Docs`,
+        },
+      ],
+    }
+  },
+  headers: () => {
+    return {
+      'cache-control': 'public, max-age=60, must-revalidate',
+      'cdn-cache-control':
+        'max-age=600, stale-while-revalidate=3600, durable',
+      vary: 'Accept-Encoding',
+    }
+  },
+  component: FrameworkDocsPage,
+})
+
+function FrameworkDocsPage() {
+  const loaderData = Route.useLoaderData()
+  const { framework } = Route.useParams()
+  const project = getSingleProject()
+
+  return (
+    <Doc
+      title={loaderData.meta?.title || ''}
+      content={loaderData.content}
+      isFallback={loaderData.isFallback}
+      filePath={loaderData.filePath}
+      repo={project.repo}
+      branch={project.latestBranch}
+      framework={framework}
+    />
+  )
+}

package/template/app/routes/$lang.docs.framework.$framework.index.tsx

@@ -0,0 +1,32 @@
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { isSingleProject, getSingleProject } from '~/site.config'
+
+export const Route = createFileRoute(
+  '/$lang/docs/framework/$framework/',
+)({
+  beforeLoad: () => {
+    if (!isSingleProject()) {
+      throw notFound()
+    }
+  },
+  component: FrameworkIndex,
+})
+
+function FrameworkIndex() {
+  const { framework } = Route.useParams()
+  const project = getSingleProject()
+  const frameworkLabel =
+    framework.charAt(0).toUpperCase() + framework.slice(1)
+
+  return (
+    <div className="py-8 max-w-3xl mx-auto">
+      <h1 className="text-3xl font-bold mb-4">
+        {project?.name} {frameworkLabel} Documentation
+      </h1>
+      <div className="h-px bg-gray-200 dark:bg-gray-700 mb-6" />
+      <p className="text-gray-600 dark:text-gray-400">
+        Use the sidebar to select a documentation page.
+      </p>
+    </div>
+  )
+}

package/template/app/routes/$lang.docs.framework.index.tsx

@@ -0,0 +1,47 @@
+import { createFileRoute, Link, notFound } from '@tanstack/react-router'
+import { isSingleProject, getSingleProject } from '~/site.config'
+
+export const Route = createFileRoute('/$lang/docs/framework/')({
+  beforeLoad: () => {
+    if (!isSingleProject()) {
+      throw notFound()
+    }
+  },
+  component: FrameworkSelectionPage,
+})
+
+function FrameworkSelectionPage() {
+  const { lang } = Route.useParams()
+  const project = getSingleProject()
+  const frameworks = project?.frameworks || []
+
+  return (
+    <div className="py-8 max-w-3xl mx-auto">
+      <h1 className="text-3xl font-bold mb-4">
+        {project?.name} Frameworks
+      </h1>
+      <div className="h-px bg-gray-200 dark:bg-gray-700 mb-6" />
+
+      {frameworks.length > 0 ? (
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+          {frameworks.map((fw) => (
+            <Link
+              key={fw}
+              to="/$lang/docs/framework/$framework"
+              params={{ lang, framework: fw }}
+              className="p-4 rounded-lg border border-gray-200 dark:border-gray-700 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors"
+            >
+              <span className="text-lg font-medium">
+                {fw.charAt(0).toUpperCase() + fw.slice(1)}
+              </span>
+            </Link>
+          ))}
+        </div>
+      ) : (
+        <p className="text-gray-600 dark:text-gray-400">
+          No frameworks are configured for this project.
+        </p>
+      )}
+    </div>
+  )
+}

package/template/app/routes/$lang.docs.index.tsx

@@ -0,0 +1,20 @@
+import { createFileRoute, notFound, redirect } from '@tanstack/react-router'
+import { isSingleProject, getSingleProject } from '~/site.config'
+
+export const Route = createFileRoute('/$lang/docs/')({
+  beforeLoad: () => {
+    if (!isSingleProject()) {
+      throw notFound()
+    }
+
+    const project = getSingleProject()
+
+    throw redirect({
+      from: '/$lang/docs',
+      to: './$',
+      params: {
+        _splat: project.defaultDocs || 'overview',
+      },
+    })
+  },
+})

package/template/app/routes/$lang.docs.tsx

@@ -0,0 +1,90 @@
+import * as React from 'react'
+import {
+  createFileRoute,
+  notFound,
+  Outlet,
+  Link,
+} from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { siteConfig, findProject, isSingleProject, getSingleProject } from '~/site.config'
+import { DocsLayout } from '~/components/DocsLayout'
+import { frameworkOptions } from '~/config/frameworks'
+import type { Framework } from '~/config/frameworks'
+
+const fetchDocsConfig = createServerFn({ method: 'GET' })
+  .inputValidator((data: { project: string; version: string }) => data)
+  .handler(async ({ data }) => {
+    const { loadDocsConfig } = await import('~/utils/docs.server')
+    return loadDocsConfig(data.project, data.version)
+  })
+
+export const Route = createFileRoute('/$lang/docs')({
+  staleTime: 1000 * 60 * 5,
+  beforeLoad: () => {
+    // This route only works for single-project sites
+    if (!isSingleProject()) {
+      throw notFound()
+    }
+  },
+  loader: async () => {
+    const project = getSingleProject()
+    const config = await fetchDocsConfig({
+      data: { project: project.id, version: project.latestVersion },
+    })
+    return { config }
+  },
+  component: SingleProjectDocsLayout,
+  head: () => {
+    const project = getSingleProject()
+    return {
+      meta: [{ title: project ? `${project.name} Docs` : siteConfig.name }],
+    }
+  },
+  headers: () => ({
+    'cache-control': 'public, max-age=0, must-revalidate',
+    'cdn-cache-control': 'max-age=300, stale-while-revalidate=300, durable',
+  }),
+  staticData: {
+    Title: () => {
+      const project = getSingleProject()
+      const gradientText = `inline-block text-transparent bg-clip-text bg-linear-to-r ${project.colorFrom} ${project.colorTo}`
+      return (
+        <Link
+          to="/$lang/docs"
+          params={{ lang: siteConfig.defaultLocale }}
+          className="relative whitespace-nowrap"
+        >
+          <span className={gradientText}>{project.name}</span>
+        </Link>
+      )
+    },
+  },
+})
+
+function SingleProjectDocsLayout() {
+  const { config } = Route.useLoaderData()
+  const project = getSingleProject()
+
+  // Map string framework IDs to Framework type
+  const frameworks: Framework[] = (project.frameworks ?? []).filter(
+    (f): f is Framework =>
+      frameworkOptions.some((opt) => opt.value === f),
+  )
+
+  return (
+    <DocsLayout
+      name={project.name}
+      version={project.latestVersion}
+      colorFrom={project.colorFrom}
+      colorTo={project.colorTo}
+      textColor={project.textColor ?? ''}
+      config={config}
+      frameworks={frameworks}
+      versions={project.availableVersions}
+      repo={project.repo}
+      docsBasePath="/$lang/docs"
+    >
+      <Outlet />
+    </DocsLayout>
+  )
+}

package/template/app/routes/$lang.tsx

@@ -0,0 +1,16 @@
+import { createFileRoute, notFound, Outlet } from '@tanstack/react-router'
+import { siteConfig } from '~/site.config'
+
+export const Route = createFileRoute('/$lang')({
+  beforeLoad: ({ params }) => {
+    // Validate locale against supported locales
+    if (!(params.lang in siteConfig.supportedLocales)) {
+      throw notFound()
+    }
+  },
+  component: LangLayout,
+})
+
+function LangLayout() {
+  return <Outlet />
+}