@fecommunity/reactpress-theme-starter 1.0.0-beta.0

package/lib/reactpress/materializeBootstrapCatalog.ts

@@ -0,0 +1,31 @@
+import type { AppBootstrapResult } from '@fecommunity/reactpress-toolkit/theme/server'
+import type { SiteCatalogContextValue } from '@fecommunity/reactpress-toolkit/ui'
+import type { ICategory, IPage, ISetting, ITag } from '@fecommunity/reactpress-toolkit/types'
+
+/** Toolkit bootstrap uses loose records; catalog context expects typed entities. */
+export function materializeBootstrapCatalog(bootstrap: AppBootstrapResult) {
+  const globalSetting = normalizeGlobalSetting(bootstrap.globalSetting)
+
+  return {
+    setting: bootstrap.setting as unknown as ISetting,
+    globalSetting,
+    siteConfig: bootstrap.siteConfig as unknown as NonNullable<
+      SiteCatalogContextValue['siteConfig']
+    >,
+    tags: bootstrap.tags as ITag[],
+    categories: bootstrap.categories as ICategory[],
+    pages: bootstrap.pages as IPage[],
+  }
+}
+
+function normalizeGlobalSetting(
+  raw: AppBootstrapResult['globalSetting']
+): SiteCatalogContextValue['globalSetting'] {
+  if (!raw) return undefined
+
+  if (typeof raw.globalConfig === 'object' && raw.globalConfig !== null) {
+    return raw as { globalConfig: Record<string, unknown> }
+  }
+
+  return { globalConfig: raw }
+}

package/lib/reactpress/normalizeApiResponse.ts

@@ -0,0 +1,25 @@
+/** Paginated ReactPress endpoints return `[items, total]` after envelope unwrap. */
+export function normalizePaginated<T>(value: unknown): [T[], number] {
+  if (Array.isArray(value) && value.length >= 2 && Array.isArray(value[0])) {
+    const items = value[0] as T[]
+    const total = typeof value[1] === 'number' ? value[1] : items.length
+    return [items, total]
+  }
+
+  if (Array.isArray(value)) {
+    return [value as T[], value.length]
+  }
+
+  return [[], 0]
+}
+
+/** List endpoints return a plain array after envelope unwrap. */
+export function normalizeList<T>(value: unknown): T[] {
+  if (!Array.isArray(value)) return []
+
+  if (value.length === 2 && Array.isArray(value[0]) && typeof value[1] === 'number') {
+    return value[0] as T[]
+  }
+
+  return value as T[]
+}

package/lib/reactpress/providers.tsx

@@ -0,0 +1,199 @@
+'use client'
+
+import { normalizeSessionUser } from '@/lib/auth/sessionUser'
+import { fetchVisitorSetting } from '@/lib/reactpress/fetchSetting'
+import { materializeBootstrapCatalog } from '@/lib/reactpress/materializeBootstrapCatalog'
+import {
+  ReactPressProvider,
+  SiteCatalogProvider,
+  readPersistedLocale,
+  useLocale,
+  type SiteCatalogContextValue,
+} from '@fecommunity/reactpress-toolkit/ui'
+import {
+  applyColorModeClass,
+  clearThemeSession,
+  mergeVisitorI18n,
+  persistColorMode,
+  persistThemeSession,
+  persistVisitorLocale,
+  resolveClientThemeMode,
+  resolveStoredUser,
+  safeJsonParse,
+  type ThemeColorMode,
+} from '@fecommunity/reactpress-toolkit/theme'
+import type { AppBootstrapResult } from '@fecommunity/reactpress-toolkit/theme/server'
+import type { IUser } from '@fecommunity/reactpress-toolkit/types'
+import { useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react'
+
+import { HomeFooterProvider } from './homeFooter'
+import { LayoutShell } from './layout-shell'
+
+type Props = {
+  bootstrap: AppBootstrapResult
+  children: React.ReactNode
+}
+
+function VisitorLocaleBootstrap({ locales, ssrLocale }: { locales: string[]; ssrLocale: string }) {
+  const { setLocale } = useLocale()
+
+  useLayoutEffect(() => {
+    const stored = readPersistedLocale(locales, ssrLocale)
+    if (stored && stored !== ssrLocale) {
+      setLocale(stored)
+    }
+  }, [locales, setLocale, ssrLocale])
+
+  return null
+}
+
+export function ReactPressAppProviders({ bootstrap, children }: Props) {
+  const catalogSeed = useMemo(() => materializeBootstrapCatalog(bootstrap), [bootstrap])
+  const { i18n: bootstrapI18n, locales, initialLocale, themeMods } = bootstrap
+
+  const [theme, setTheme] = useState<ThemeColorMode>('light')
+  const [locale, setLocale] = useState(initialLocale)
+  const [collapsed, setCollapsed] = useState(false)
+  const [user, setUserState] = useState<SiteCatalogContextValue['user']>(null)
+  const [i18nCatalog, setI18nCatalog] = useState<Record<string, Record<string, string>>>(
+    () =>
+      mergeVisitorI18n(bootstrapI18n as Record<string, unknown>) as Record<
+        string,
+        Record<string, string>
+      >
+  )
+
+  useLayoutEffect(() => {
+    const storedUser = resolveStoredUser()
+    if (storedUser) {
+      persistThemeSession(storedUser)
+      setUserState(storedUser)
+    }
+
+    const preferred = resolveClientThemeMode()
+    applyColorModeClass(preferred === 'dark')
+    setTheme(preferred)
+  }, [])
+
+  useEffect(() => {
+    applyColorModeClass(theme === 'dark')
+  }, [theme])
+
+  const prefetchRemainingI18nLocales = useCallback(() => {
+    if (!Array.isArray(locales) || locales.length <= 1) return
+
+    fetchVisitorSetting()
+      .then((res) => {
+        if (!res) return
+        const full = mergeVisitorI18n(safeJsonParse(res.i18n, {})) as Record<
+          string,
+          Record<string, string>
+        >
+        setI18nCatalog((prev) => ({ ...prev, ...full }))
+      })
+      .catch(() => {
+        // Active locale messages are already available from SSR / builtins.
+      })
+  }, [locales])
+
+  useEffect(() => {
+    prefetchRemainingI18nLocales()
+  }, [prefetchRemainingI18nLocales])
+
+  const changeTheme = useCallback((next: ThemeColorMode) => {
+    const isDark = next === 'dark'
+    applyColorModeClass(isDark)
+    persistColorMode(isDark)
+    setTheme(next)
+  }, [])
+
+  const changeLocale = useCallback(
+    (key: string) => {
+      if (!key || key === locale) return
+      persistVisitorLocale(key)
+      setLocale(key)
+
+      if (!i18nCatalog[key]) {
+        prefetchRemainingI18nLocales()
+      }
+    },
+    [i18nCatalog, locale, prefetchRemainingI18nLocales]
+  )
+
+  const setUser = useCallback((next: IUser) => {
+    const session = normalizeSessionUser(next)
+    if (session) {
+      persistThemeSession(session)
+    }
+    setUserState(next)
+  }, [])
+
+  const removeUser = useCallback(() => {
+    clearThemeSession()
+    setUserState(null)
+    window.location.reload()
+  }, [])
+
+  const toggleCollapse = useCallback(() => setCollapsed((value) => !value), [])
+
+  const catalogValue = useMemo<SiteCatalogContextValue>(
+    () => ({
+      setting: catalogSeed.setting,
+      i18n: i18nCatalog,
+      locale,
+      locales,
+      globalSetting: catalogSeed.globalSetting,
+      siteConfig: catalogSeed.siteConfig,
+      tags: catalogSeed.tags,
+      categories: catalogSeed.categories,
+      pages: catalogSeed.pages,
+      theme,
+      collapsed,
+      changeLocale,
+      user,
+      setUser,
+      removeUser,
+      changeTheme,
+      getSetting: () => catalogSeed.setting,
+      toggleCollapse,
+    }),
+    [
+      catalogSeed,
+      i18nCatalog,
+      locale,
+      locales,
+      theme,
+      collapsed,
+      changeLocale,
+      user,
+      setUser,
+      removeUser,
+      changeTheme,
+      toggleCollapse,
+    ]
+  )
+
+  const messages = (i18nCatalog[locale] ?? {}) as Record<string, string>
+
+  return (
+    <ReactPressProvider
+      locale={locale}
+      locales={locales}
+      messages={messages}
+      catalog={i18nCatalog}
+      themeId="reactpress-theme-starter"
+      activeThemeId="reactpress-theme-starter"
+      mods={themeMods}
+      onLocaleChange={changeLocale}
+    >
+      <SiteCatalogProvider value={catalogValue}>
+        <HomeFooterProvider>
+          <LayoutShell>
+            <VisitorLocaleBootstrap locales={locales} ssrLocale={initialLocale} />
+            {children}
+          </LayoutShell>
+        </HomeFooterProvider>
+      </SiteCatalogProvider>
+    </ReactPressProvider>
+  )
+}

package/lib/reactpress/resolveSiteNav.ts

@@ -0,0 +1,56 @@
+import themeManifest from '../../theme.json'
+import { safeJsonParse } from '@fecommunity/reactpress-toolkit/theme'
+
+export type SiteNavBlocks = {
+  urlConfig: unknown[]
+  searchCategories: {
+    categories?: Array<{ key: string; label: string }>
+    subCategories?: Record<string, Array<{ key: string; label: string; url?: string }>>
+  }
+}
+
+type GlobalSettingRaw = {
+  theme?: { activeTheme?: string }
+  config?: Record<
+    string,
+    {
+      nav?: {
+        urlConfig?: unknown[]
+        searchCategories?: SiteNavBlocks['searchCategories']
+      }
+    }
+  >
+  en?: { globalConfig?: { urlConfig?: unknown[]; navConfig?: SiteNavBlocks['searchCategories'] } }
+  zh?: { globalConfig?: { urlConfig?: unknown[]; navConfig?: SiteNavBlocks['searchCategories'] } }
+}
+
+const EMPTY_NAV: SiteNavBlocks = {
+  urlConfig: [],
+  searchCategories: { categories: [], subCategories: {} },
+}
+
+/** Resolve nav blocks for the active theme and visitor locale (client-safe). */
+export function resolveSiteNavConfig(
+  globalSettingRaw: unknown,
+  locale: string,
+  themeId = themeManifest.id
+): SiteNavBlocks {
+  const gs = (globalSettingRaw ?? {}) as GlobalSettingRaw
+  const activeTheme = gs.theme?.activeTheme ?? themeId
+  const themeNav = gs.config?.[activeTheme]?.nav
+  const legacyBundle = locale === 'en' ? (gs.en ?? gs.zh) : (gs.zh ?? gs.en)
+  const legacy = legacyBundle?.globalConfig
+
+  return {
+    urlConfig: themeNav?.urlConfig ?? legacy?.urlConfig ?? [],
+    searchCategories: themeNav?.searchCategories ?? legacy?.navConfig ?? EMPTY_NAV.searchCategories,
+  }
+}
+
+export function resolveSiteNavFromSetting(
+  setting: { globalSetting?: unknown } | null | undefined,
+  locale: string
+): SiteNavBlocks {
+  const raw = safeJsonParse(setting?.globalSetting, {})
+  return resolveSiteNavConfig(raw, locale)
+}

package/lib/reactpress/seoMetadata.ts

@@ -0,0 +1,82 @@
+import type { Metadata } from 'next'
+
+const DEFAULT_DESCRIPTION = 'Blog powered by ReactPress'
+const DEFAULT_OG_IMAGE = '/logo-400.png'
+
+export function resolveFullPageTitle(pageTitle: string, siteName: string): string {
+  return `${pageTitle} - ${siteName}`
+}
+
+export function buildCanonicalUrl(siteUrl: string, path: string): string {
+  const base = siteUrl.replace(/\/$/, '')
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`
+  return normalizedPath === '/' ? base : `${base}${normalizedPath}`
+}
+
+export type PageMetadataInput = {
+  /** Page-specific title segment; root layout template appends site name. */
+  title: string
+  /** Full document title without template (home: site - slogan). */
+  titleAbsolute?: boolean
+  description?: string
+  keywords?: string | string[]
+  path?: string
+  siteUrl?: string
+  siteName?: string
+  ogType?: 'website' | 'article'
+  images?: string[]
+  publishedTime?: string
+  modifiedTime?: string
+  tags?: string[]
+  locale?: string
+  robots?: Metadata['robots']
+}
+
+export function buildPageMetadata(input: PageMetadataInput): Metadata {
+  const siteName = input.siteName ?? 'Blog'
+  const description = input.description?.trim() || DEFAULT_DESCRIPTION
+  const keywords = input.keywords
+    ? Array.isArray(input.keywords)
+      ? input.keywords
+      : input.keywords
+    : undefined
+  const canonical =
+    input.siteUrl && input.path ? buildCanonicalUrl(input.siteUrl, input.path) : undefined
+  const fullTitle = input.titleAbsolute ? input.title : resolveFullPageTitle(input.title, siteName)
+  const imageUrls = input.images?.filter(Boolean) ?? []
+  const ogImages = imageUrls.map((url) => ({ url }))
+
+  return {
+    title: input.titleAbsolute ? { absolute: input.title } : input.title,
+    description,
+    ...(keywords ? { keywords } : {}),
+    ...(canonical ? { alternates: { canonical } } : {}),
+    openGraph: {
+      title: fullTitle,
+      description,
+      type: input.ogType ?? 'website',
+      siteName,
+      ...(canonical ? { url: canonical } : {}),
+      ...(ogImages.length ? { images: ogImages } : {}),
+      ...(input.publishedTime ? { publishedTime: input.publishedTime } : {}),
+      ...(input.modifiedTime ? { modifiedTime: input.modifiedTime } : {}),
+      ...(input.tags?.length ? { tags: input.tags } : {}),
+      ...(input.locale ? { locale: input.locale } : {}),
+    },
+    twitter: {
+      card: ogImages.length ? 'summary_large_image' : 'summary',
+      title: fullTitle,
+      description,
+      ...(imageUrls.length ? { images: imageUrls } : {}),
+    },
+    ...(input.robots ? { robots: input.robots } : {}),
+  }
+}
+
+export function defaultOgImageMetadata(
+  siteName?: string
+): NonNullable<Metadata['openGraph']>['images'] {
+  return [{ url: DEFAULT_OG_IMAGE, width: 400, height: 400, alt: siteName ?? 'Blog' }]
+}
+
+export { DEFAULT_DESCRIPTION, DEFAULT_OG_IMAGE }

package/lib/reactpress/serverLocale.ts

@@ -0,0 +1,43 @@
+import {
+  createTranslator,
+  DEFAULT_VISITOR_LOCALES,
+  LEGACY_LOCALE_STORAGE_KEY,
+  mergeVisitorI18n,
+  resolveRequestLocale,
+  VISITOR_LOCALE_COOKIE,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import { cookies, headers } from 'next/headers'
+
+export async function getServerTranslator() {
+  const catalog = mergeVisitorI18n({}) as Record<string, Record<string, string>>
+  const locales = Object.keys(catalog).length ? Object.keys(catalog) : [...DEFAULT_VISITOR_LOCALES]
+  const cookieStore = await cookies()
+  const preferred =
+    cookieStore.get(VISITOR_LOCALE_COOKIE)?.value ??
+    cookieStore.get(LEGACY_LOCALE_STORAGE_KEY)?.value
+  const acceptLanguage = (await headers()).get('accept-language') ?? undefined
+  const locale = resolveRequestLocale(locales, {
+    preferred,
+    acceptLanguage,
+    fallback: locales.includes('zh') ? 'zh' : (locales[0] ?? 'en'),
+  })
+  const messages = catalog[locale] ?? {}
+  const t = createTranslator(messages)
+
+  return {
+    locale,
+    t,
+    format(template: string, vars: Record<string, string | number>) {
+      return Object.entries(vars).reduce(
+        (text, [key, value]) => text.replace(new RegExp(`\\{${key}\\}`, 'g'), String(value)),
+        template
+      )
+    },
+  }
+}
+
+export async function tServer(key: string, vars?: Record<string, string | number>) {
+  const { t, format } = await getServerTranslator()
+  const text = t(key)
+  return vars ? format(text, vars) : text
+}

package/lib/reactpress/siteMetadata.ts

@@ -0,0 +1,151 @@
+import {
+  fetchSiteMeta,
+  getSiteTitle,
+  themeApi,
+  unwrapSetting,
+  withApiRetry,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { Metadata } from 'next'
+
+import {
+  buildCanonicalUrl,
+  buildPageMetadata,
+  defaultOgImageMetadata,
+  DEFAULT_DESCRIPTION,
+  DEFAULT_OG_IMAGE,
+} from './seoMetadata'
+import { tServer } from './serverLocale'
+
+async function fetchSiteSeoBase() {
+  const [siteMeta, settingRow] = await Promise.all([
+    withApiRetry(() => fetchSiteMeta(themeApi)),
+    withApiRetry(() => themeApi.setting.findAll()).then(unwrapSetting),
+  ])
+  return { siteMeta, settingRow }
+}
+
+function resolveSiteDescription(
+  settingRow: Record<string, unknown> | null,
+  siteDescription?: string
+): string {
+  return (
+    (settingRow?.seoDesc != null ? String(settingRow.seoDesc).trim() : '') ||
+    siteDescription ||
+    DEFAULT_DESCRIPTION
+  )
+}
+
+export async function buildRootMetadata(): Promise<Metadata> {
+  try {
+    const { siteMeta, settingRow } = await fetchSiteSeoBase()
+    const siteName = siteMeta.siteName ?? 'Blog'
+    const title = getSiteTitle({
+      systemTitle: siteMeta.siteName,
+      systemSubTitle: siteMeta.siteDescription,
+    })
+    const description = resolveSiteDescription(settingRow, siteMeta.siteDescription)
+    const keywords = settingRow?.seoKeyword != null ? String(settingRow.seoKeyword) : undefined
+    const canonical = siteMeta.siteUrl ? buildCanonicalUrl(siteMeta.siteUrl, '/') : undefined
+    const ogImages = defaultOgImageMetadata(siteName)
+
+    return {
+      title: {
+        default: title,
+        template: `%s - ${siteName}`,
+      },
+      description,
+      keywords,
+      metadataBase: siteMeta.siteUrl ? new URL(siteMeta.siteUrl) : undefined,
+      ...(canonical ? { alternates: { canonical } } : {}),
+      openGraph: {
+        title,
+        description,
+        type: 'website',
+        siteName,
+        ...(canonical ? { url: canonical } : {}),
+        images: ogImages,
+      },
+      twitter: {
+        card: 'summary_large_image',
+        title,
+        description,
+        images: [DEFAULT_OG_IMAGE],
+      },
+      robots: { index: true, follow: true },
+    }
+  } catch (error) {
+    console.error('[reactpress-theme-starter] root metadata fetch failed', error)
+    return {
+      title: { default: 'Blog', template: '%s - Blog' },
+      description: DEFAULT_DESCRIPTION,
+    }
+  }
+}
+
+export async function buildHomePageMetadata(): Promise<Metadata> {
+  try {
+    const { siteMeta, settingRow } = await fetchSiteSeoBase()
+    const siteName = siteMeta.siteName ?? 'Blog'
+    const title = getSiteTitle({
+      systemTitle: siteMeta.siteName,
+      systemSubTitle: siteMeta.siteDescription,
+    })
+    const description = resolveSiteDescription(settingRow, siteMeta.siteDescription)
+    const keywords = settingRow?.seoKeyword != null ? String(settingRow.seoKeyword) : undefined
+
+    return buildPageMetadata({
+      title,
+      titleAbsolute: true,
+      description,
+      keywords,
+      path: '/',
+      siteUrl: siteMeta.siteUrl,
+      siteName,
+      images: [DEFAULT_OG_IMAGE],
+    })
+  } catch (error) {
+    console.error('[reactpress-theme-starter] home metadata fetch failed', error)
+    return { title: { absolute: 'Blog' } }
+  }
+}
+
+export async function buildLocalizedListPageMetadata(
+  titleKey: string,
+  vars?: Record<string, string | number>,
+  options?: { description?: string; path?: string }
+): Promise<Metadata> {
+  const pageTitle = await tServer(titleKey, vars)
+  return buildListPageMetadata(pageTitle, options?.description, options?.path)
+}
+
+export async function buildListPageMetadata(
+  pageTitle: string,
+  description?: string,
+  path?: string
+): Promise<Metadata> {
+  try {
+    const { siteMeta, settingRow } = await fetchSiteSeoBase()
+    const resolvedDescription = resolveSiteDescription(settingRow, siteMeta.siteDescription)
+
+    return buildPageMetadata({
+      title: pageTitle,
+      description: description?.trim() || resolvedDescription,
+      path,
+      siteUrl: siteMeta.siteUrl,
+      siteName: siteMeta.siteName ?? 'Blog',
+      images: [DEFAULT_OG_IMAGE],
+    })
+  } catch (error) {
+    console.error('[reactpress-theme-starter] list page metadata fetch failed', error)
+    return { title: pageTitle }
+  }
+}
+
+export async function buildNoIndexMetadata(pageTitle: string, path?: string): Promise<Metadata> {
+  const base = await buildListPageMetadata(pageTitle, undefined, path)
+  return {
+    ...base,
+    description: base.description ?? DEFAULT_DESCRIPTION,
+    robots: { index: false, follow: false },
+  }
+}

package/lib/reactpress/staticParams.ts

@@ -0,0 +1,46 @@
+import {
+  themeApi,
+  unpackList,
+  unpackPaginatedPair,
+  withApiRetry,
+} from '@fecommunity/reactpress-toolkit/theme/server'
+import type { IArticle, ICategory, ITag } from '@fecommunity/reactpress-toolkit/types'
+
+const STATIC_PARAM_LIMIT = 200
+
+export async function generateArticleStaticParams() {
+  try {
+    const response = await withApiRetry(() =>
+      themeApi.article.findAll({
+        query: { page: 1, pageSize: STATIC_PARAM_LIMIT, status: 'publish' },
+      } as never)
+    )
+    const [articles] = unpackPaginatedPair<IArticle>(response)
+    return articles.map((article) => ({ id: article.id }))
+  } catch (error) {
+    console.error('[reactpress-theme-starter] article static params failed', error)
+    return []
+  }
+}
+
+export async function generateTagStaticParams() {
+  try {
+    const response = await withApiRetry(() => themeApi.tag.findAll())
+    const tags = unpackList<ITag>(response).slice(0, STATIC_PARAM_LIMIT)
+    return tags.map((tag) => ({ tag: tag.value }))
+  } catch (error) {
+    console.error('[reactpress-theme-starter] tag static params failed', error)
+    return []
+  }
+}
+
+export async function generateCategoryStaticParams() {
+  try {
+    const response = await withApiRetry(() => themeApi.category.findAll())
+    const categories = unpackList<ICategory>(response).slice(0, STATIC_PARAM_LIMIT)
+    return categories.map((category) => ({ category: category.value }))
+  } catch (error) {
+    console.error('[reactpress-theme-starter] category static params failed', error)
+    return []
+  }
+}

package/lib/reactpress/suggestionsContent.ts

@@ -0,0 +1,48 @@
+const REACTPRESS_GITHUB = 'https://github.com/fecommunity/reactpress'
+const REACTPRESS_SITE = 'https://reactpress.surge.sh/'
+
+const suggestionsHtmlEn = `
+<p>Thank you for using ReactPress. We welcome your ideas, bug reports, and documentation feedback.</p>
+<h2>Share your thoughts</h2>
+<ul>
+<li>Report bugs or UX issues on the <a href="${REACTPRESS_GITHUB}/issues" rel="noopener noreferrer">GitHub issue tracker</a>.</li>
+<li>Suggest features for the CLI, admin console, or theme toolkit.</li>
+<li>Share deployment guides for platforms beyond Vercel.</li>
+<li>Tell us which documentation topics need clearer examples.</li>
+</ul>
+<h2>Contributing</h2>
+<p>ReactPress is open source under the MIT license. Fork the repository, run <code>pnpm install</code> and <code>pnpm run dev</code>, and open a pull request. Meaningful contributions are credited in the README.</p>
+<h2>Related reading</h2>
+<ul>
+<li><a href="/article/what-is-reactpress/">What is ReactPress?</a></li>
+<li><a href="/article/quick-start/">Quick Start with ReactPress</a></li>
+<li><a href="${REACTPRESS_SITE}" rel="noopener noreferrer">Official documentation</a></li>
+<li><a href="${REACTPRESS_GITHUB}" rel="noopener noreferrer">GitHub repository</a></li>
+</ul>
+`.trim()
+
+const suggestionsHtmlZh = `
+<p>感谢使用 ReactPress。欢迎反馈想法、Bug 与文档改进建议。</p>
+<h2>分享你的想法</h2>
+<ul>
+<li>在 <a href="${REACTPRESS_GITHUB}/issues" rel="noopener noreferrer">GitHub Issue</a> 反馈 Bug 或体验问题。</li>
+<li>为 CLI、管理端或主题工具包提出功能建议。</li>
+<li>分享 Vercel 之外平台的部署实践经验。</li>
+<li>告诉我们哪些文档主题需要更清晰的示例。</li>
+</ul>
+<h2>参与贡献</h2>
+<p>ReactPress 基于 MIT 协议开源。Fork 仓库后执行 <code>pnpm install</code> 与 <code>pnpm run dev</code>，提交 Pull Request 即可参与贡献。</p>
+<h2>延伸阅读</h2>
+<ul>
+<li><a href="/article/what-is-reactpress/">什么是 ReactPress？</a></li>
+<li><a href="/article/quick-start/">ReactPress 快速上手</a></li>
+<li><a href="${REACTPRESS_SITE}" rel="noopener noreferrer">官方文档</a></li>
+<li><a href="${REACTPRESS_GITHUB}" rel="noopener noreferrer">GitHub 仓库</a></li>
+</ul>
+`.trim()
+
+/** Theme starter fallback — switches with visitor locale on the suggestions page. */
+export function getSuggestionsPageHtml(locale: string, cmsHtml?: string) {
+  if (locale === 'zh') return suggestionsHtmlZh
+  return cmsHtml?.trim() || suggestionsHtmlEn
+}