@icebreakers/monorepo-templates 1.2.1 → 1.3.1

package/templates/tsdown/package.json

@@ -6,7 +6,7 @@
   "description": "Internal TypeScript library template shipped with repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
   "license": "MIT",
-  "homepage": "https://repo.icebreaker.top",
+  "homepage": "https://repoctl.icebreaker.top",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sonofmagic/repoctl.git",

package/templates/vitepress/.vitepress/config.ts

@@ -2,116 +2,30 @@ import Tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vitepress'
 import llmstxt from 'vitepress-plugin-llms'
 import { withMermaid } from 'vitepress-plugin-mermaid'
-
-interface SidebarLabels {
-  repoctl: string
-  repoctlItems: string[]
-  knowledge: string
-  knowledgeItems: string[]
-  packages: string
-  packageItems: string[]
-  ai: string
-  aiItems: string[]
-  tools: string
-  toolItems: string[]
-}
-
-const repoctlPaths = [
-  '',
-  'getting-started',
-  'adopt-existing',
-  'scenarios',
-  'execution-model',
-  'commands',
-  'checks',
-  'doctor',
-  'config',
-  'templates',
-  'template-assets',
-  'workflows',
-  'reports',
-  'troubleshooting',
-  'aliases',
-]
-const knowledgePaths = ['', 'manage', 'publish', 'commands', 'templates', 'troubleshooting']
-const packagePaths = [
-  'how-to-reuse-js-code',
-  'js-cjs-mjs',
-  'js-keywords',
-  'what-is-npm-package',
-  'publish-basic-npm-package',
-  'index',
-  'modern/',
-  'modern/esm-vs-cjs',
-  'modern/dts',
-  'modern/package-entry-points',
-  'modern/bundlers',
-  'modern/typescript',
-]
-const aiPaths = ['', 'llms-txt']
-const toolPaths = ['', 'pnpm', 'turborepo', 'changeset', 'husky', 'lint-staged', 'renovate', 'llms-txt']
-
-const englishLabels: SidebarLabels = {
-  repoctl: 'repoctl',
-  repoctlItems: ['Overview', 'Getting Started', 'Adopt Existing Repos', 'Choose By Scenario', 'Execution Model', 'Command Reference', 'Verification', 'Doctor', 'Configuration', 'Templates', 'Template Assets', 'Workflows and CI', 'Reports', 'Troubleshooting', 'Command Aliases'],
-  knowledge: 'Knowledge Base',
-  knowledgeItems: ['Why Monorepo', 'Managing A Monorepo', 'Publishing and Changelogs', 'Monorepo Commands', 'Template Systems', 'Troubleshooting'],
-  packages: 'Modern Packages',
-  packageItems: ['Reusing JavaScript', 'Module Extensions', 'Runtime Globals', 'What Is An npm Package?', 'Publishing A Package', 'Package Evolution', 'Modern Package Guide', 'ESM vs CommonJS', 'Type Declarations', 'Package Entry Points', 'Bundlers', 'TypeScript'],
-  ai: 'AI',
-  aiItems: ['AI Documentation', 'llms.txt'],
-  tools: 'Tool Guides',
-  toolItems: ['Overview', 'pnpm', 'Turborepo', 'pnpm Versioning', 'Husky', 'lint-staged', 'Renovate', 'llms.txt'],
-}
-
-const chineseLabels: SidebarLabels = {
-  repoctl: 'repoctl',
-  repoctlItems: ['概览', '快速开始', '接入已有仓库', '按场景选命令', '执行模型', '命令速查', '校验链路', 'Doctor 诊断', '配置文件', '模板与创建', '模板资产治理', '工作流与 CI', '报告与自动化输出', '排障', '命令别名'],
-  knowledge: '知识库',
-  knowledgeItems: ['为什么使用 Monorepo', '管理 Monorepo', '发包与变更日志', 'Monorepo 命令', '模板体系', '常见问题排障'],
-  packages: '现代 npm 包',
-  packageItems: ['复用 JavaScript', '模块文件后缀', '运行时关键字', '什么是 npm 包', '发布 npm 包', '包的演进', '现代包指南', 'ESM 与 CommonJS', '类型声明', '包入口', '构建工具', 'TypeScript'],
-  ai: 'AI',
-  aiItems: ['AI 文档', 'llms.txt'],
-  tools: '工具专题',
-  toolItems: ['概览', 'pnpm', 'Turborepo', 'pnpm Versioning', 'Husky', 'lint-staged', 'Renovate', 'llms.txt'],
-}
-
-function prefixed(prefix: string, section: string, paths: string[], labels: string[]) {
-  return paths.map((path, index) => ({
-    text: labels[index]!,
-    link: `${prefix}/${section}/${path}`.replace(/\/+/g, '/'),
-  }))
-}
-
-function createSidebars(prefix: '' | '/zh', labels: SidebarLabels) {
-  const repoctl = [{ text: labels.repoctl, items: prefixed(prefix, 'repoctl', repoctlPaths, labels.repoctlItems) }]
-  const knowledge = [
-    { text: labels.knowledge, items: prefixed(prefix, 'monorepo', knowledgePaths, labels.knowledgeItems) },
-    { text: labels.packages, items: prefixed(prefix, 'why', packagePaths, labels.packageItems) },
-  ]
-  const ai = [{ text: labels.ai, items: prefixed(prefix, 'ai', aiPaths, labels.aiItems) }]
-  const tools = [{ text: labels.tools, items: prefixed(prefix, 'tools', toolPaths, labels.toolItems) }]
-  return {
-    [`${prefix}/repoctl/`]: repoctl,
-    [`${prefix}/knowledge/`]: knowledge,
-    [`${prefix}/monorepo/`]: knowledge,
-    [`${prefix}/why/`]: knowledge,
-    [`${prefix}/ai/`]: ai,
-    [`${prefix}/tools/`]: tools,
-    [`${prefix || ''}/`]: repoctl,
-  }
-}
+import { createNav, createSidebars } from './navigation/routes'
+import { createPageHead, siteOrigin } from './seo'
 
 export default withMermaid(defineConfig({
   outDir: '.vitepress/dist',
+  srcExclude: ['CHANGELOG.md', 'learn/packages/examples/**', 'zh/learn/packages/examples/**'],
   title: 'repoctl',
-  description: 'Task-first CLI for initializing, maintaining, validating, and releasing pnpm and Turborepo monorepos.',
+  description: 'A practical CLI guide for setting up, checking, and maintaining pnpm and Turborepo monorepos.',
   lastUpdated: true,
   cleanUrls: true,
-  head: [['link', { rel: 'icon', href: '/logo.jpg' }]],
+  sitemap: { hostname: siteOrigin },
+  transformHead: createPageHead,
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/brand/repoctl-mark.svg' }],
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/brand/repoctl-mark-dark.svg', media: '(prefers-color-scheme: dark)' }],
+    ['link', { rel: 'alternate icon', type: 'image/x-icon', href: '/brand/favicon.ico' }],
+    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/brand/apple-touch-icon.png' }],
+  ],
   themeConfig: {
-    logo: '/logo.jpg',
+    logo: {
+      light: '/brand/repoctl-mark.svg',
+      dark: '/brand/repoctl-mark-dark.svg',
+      alt: 'repoctl',
+    },
     search: { provider: 'local' },
     socialLinks: [{ icon: 'github', link: 'https://github.com/sonofmagic/repoctl' }],
   },
@@ -120,18 +34,11 @@ export default withMermaid(defineConfig({
       label: 'English',
       lang: 'en-US',
       title: 'repoctl',
-      description: 'Task-first CLI for practical pnpm and Turborepo monorepos.',
+      description: 'A practical CLI guide for setting up, checking, and maintaining pnpm and Turborepo monorepos.',
       themeConfig: {
-        nav: [
-          { text: 'repoctl', link: '/repoctl/' },
-          { text: 'Getting Started', link: '/repoctl/getting-started' },
-          { text: 'Commands', link: '/repoctl/commands' },
-          { text: 'Knowledge Base', link: '/knowledge/' },
-          { text: 'AI Docs', link: '/ai/' },
-          { text: 'Tool Guides', link: '/tools/' },
-        ],
+        nav: createNav('en'),
         outline: { label: 'On This Page', level: [2, 3] },
-        sidebar: createSidebars('', englishLabels),
+        sidebar: createSidebars('en'),
         editLink: {
           pattern: 'https://github.com/sonofmagic/repoctl/edit/main/templates/vitepress/:path',
           text: 'Edit this page',
@@ -145,18 +52,11 @@ export default withMermaid(defineConfig({
       lang: 'zh-CN',
       link: '/zh/',
       title: 'repoctl',
-      description: '面向 pnpm 与 Turborepo monorepo 的任务型 CLI。',
+      description: '面向 pnpm 与 Turborepo monorepo 的实用 CLI 文档。',
       themeConfig: {
-        nav: [
-          { text: 'repoctl', link: '/zh/repoctl/' },
-          { text: '快速开始', link: '/zh/repoctl/getting-started' },
-          { text: '命令', link: '/zh/repoctl/commands' },
-          { text: '知识库', link: '/zh/knowledge/' },
-          { text: 'AI 文档', link: '/zh/ai/' },
-          { text: '工具专题', link: '/zh/tools/' },
-        ],
+        nav: createNav('zh'),
         outline: { label: '目录', level: [2, 3] },
-        sidebar: createSidebars('/zh', chineseLabels),
+        sidebar: createSidebars('zh'),
         editLink: {
           pattern: 'https://github.com/sonofmagic/repoctl/edit/main/templates/vitepress/:path',
           text: '为此页提供修改建议',
@@ -172,14 +72,14 @@ export default withMermaid(defineConfig({
       Tailwindcss(),
       llmstxt({
         title: 'repoctl',
-        description: 'Task-first CLI for pnpm and Turborepo monorepos. Simplified Chinese documentation is available under /zh/.',
-        domain: 'https://repo.icebreaker.top',
+        description: 'Practical documentation for setting up, checking, and maintaining pnpm and Turborepo monorepos. Chinese documentation is available under /zh/.',
+        domain: siteOrigin,
         ignoreFiles: [
           'zh/**',
           'en/**',
           'CHANGELOG.md',
           'thinking.md',
-          'why/examples/**',
+          'learn/packages/examples/**',
           '.vitepress/**',
           '**/node_modules/**',
           '**/internal/**',

package/templates/vitepress/.vitepress/env.d.ts

@@ -0,0 +1 @@
+declare module '*.css'

package/templates/vitepress/.vitepress/home/content.ts

@@ -0,0 +1,94 @@
+import type { DocsLocale } from '../navigation/routes'
+import type { HomeContent } from './types'
+
+const english = {
+  hero: {
+    label: 'repoctl documentation',
+    title: 'What does your repository need next?',
+    description: 'Initialize, diagnose, create, check, and release pnpm or Turborepo workspaces from one task-first CLI.',
+    primaryAction: { label: 'Get started', href: '/start/' },
+    secondaryAction: { label: 'Browse commands', href: '/reference/commands' },
+    imageAlt: 'A real repoctl doctor report showing repository checks and findings',
+  },
+  tasks: {
+    title: 'Choose a task',
+    description: 'Pick the result you need. Each path begins with the smallest safe command.',
+    items: [
+      { title: 'Start a new repository', body: 'Set up the shared conventions before you add projects.', command: 'repo init', link: { label: 'Start here', href: '/start/' } },
+      { title: 'Adopt an existing repository', body: 'Inspect current choices and preview changes before writing.', command: 'repo doctor', link: { label: 'Plan adoption', href: '/tasks/adopt-existing' } },
+      { title: 'Create a package or app', body: 'Use a known template so names, scripts, and boundaries stay consistent.', command: 'repo new', link: { label: 'Create a project', href: '/tasks/create-project' } },
+      { title: 'Run a repository check', body: 'Plan lint, types, builds, and tests before a commit or CI run.', command: 'repo check', link: { label: 'Run checks', href: '/tasks/checks' } },
+    ],
+  },
+  firstRun: {
+    title: 'Three commands to a useful baseline',
+    description: 'Install repoctl, initialize its managed defaults, then diagnose the workspace.',
+    steps: [
+      { title: 'Install', command: 'pnpm add -D repoctl', body: 'Keep repoctl with the repository so teammates and CI use the same version.' },
+      { title: 'Initialize', command: 'pnpm exec repo init', body: 'Review the file plan before adding managed scripts and configuration.' },
+      { title: 'Diagnose', command: 'pnpm exec repo doctor', body: 'Use the first blocker as your next task. Run the diagnosis again after each fix.' },
+    ],
+  },
+  evidence: {
+    title: 'See the plan before the repository changes',
+    description: 'Preview work, redact local paths, and keep the exact command sequence with the report.',
+    code: 'pnpm exec repo new docs --template vitepress --dry-run\npnpm exec repo check --dry-run\npnpm exec repo doctor --markdown --redact',
+    link: { label: 'See how diagnosis works', href: '/start/diagnose' },
+  },
+  layers: {
+    title: 'Continue with the decision in front of you',
+    description: 'Move from the current task to the level of detail you need.',
+    items: [
+      { title: 'Daily tasks', body: 'Adoption, project creation, checks, CI, reports, releases, and troubleshooting.', link: { label: 'Open tasks', href: '/tasks/' } },
+      { title: 'Understand the system', body: 'Monorepo boundaries, modern npm packages, templates, and the tools underneath.', link: { label: 'Open Learn', href: '/learn/' } },
+      { title: 'Look up exact behavior', body: 'Commands, configuration, output formats, aliases, and execution details.', link: { label: 'Open Reference', href: '/reference/' } },
+    ],
+  },
+} satisfies HomeContent
+
+const chinese = {
+  hero: {
+    label: 'repoctl 文档',
+    title: '仓库下一步，该做什么？',
+    description: '用一个任务型 CLI 初始化、诊断、创建、校验与发布 pnpm 和 Turborepo 工作区。',
+    primaryAction: { label: '开始使用', href: '/zh/start/' },
+    secondaryAction: { label: '查看命令', href: '/zh/reference/commands' },
+    imageAlt: '真实的 repoctl doctor 报告，展示仓库检查结果与发现项',
+  },
+  tasks: {
+    title: '选择一项任务',
+    description: '选择你要得到的结果，每条路径都从最小的安全命令开始。',
+    items: [
+      { title: '新建仓库', body: '先建立共享约定，再开始添加项目。', command: 'repo init', link: { label: '从这里开始', href: '/zh/start/' } },
+      { title: '接入已有仓库', body: '先检查当前决策，预览变化后再写入。', command: 'repo doctor', link: { label: '制定接入计划', href: '/zh/tasks/adopt-existing' } },
+      { title: '创建包或应用', body: '使用已知模板，让名称、脚本和边界保持一致。', command: 'repo new', link: { label: '创建项目', href: '/zh/tasks/create-project' } },
+      { title: '运行仓库校验', body: '提交或运行 CI 前，先规划 lint、类型、构建和测试。', command: 'repo check', link: { label: '运行校验', href: '/zh/tasks/checks' } },
+    ],
+  },
+  firstRun: {
+    title: '三条命令，建立可用基线',
+    description: '安装 repoctl，初始化受管默认值，再诊断当前工作区。',
+    steps: [
+      { title: '安装', command: 'pnpm add -D repoctl', body: '把 repoctl 保存在仓库中，让成员和 CI 使用相同版本。' },
+      { title: '初始化', command: 'pnpm exec repo init', body: '写入受管脚本和配置前，先检查文件计划。' },
+      { title: '诊断', command: 'pnpm exec repo doctor', body: '把第一个阻塞项作为下一项任务，修复后再次运行诊断。' },
+    ],
+  },
+  evidence: {
+    title: '仓库变化前，先看清执行计划',
+    description: '预览操作、脱敏本地路径，并让报告保留准确的命令顺序。',
+    code: 'pnpm exec repo new docs --template vitepress --dry-run\npnpm exec repo check --dry-run\npnpm exec repo doctor --markdown --redact',
+    link: { label: '了解诊断流程', href: '/zh/start/diagnose' },
+  },
+  layers: {
+    title: '沿着当前决策继续深入',
+    description: '从手头任务出发，只进入你现在需要的细节层级。',
+    items: [
+      { title: '日常任务', body: '接入、创建项目、校验、CI、报告、发布和排障。', link: { label: '打开任务', href: '/zh/tasks/' } },
+      { title: '理解系统', body: 'Monorepo 边界、现代 npm 包、模板和底层工具。', link: { label: '打开理解', href: '/zh/learn/' } },
+      { title: '查找准确行为', body: '命令、配置、输出格式、别名和执行细节。', link: { label: '打开参考', href: '/zh/reference/' } },
+    ],
+  },
+} satisfies HomeContent
+
+export const homeContent: Record<DocsLocale, HomeContent> = { en: english, zh: chinese }

package/templates/vitepress/.vitepress/home/types.ts

@@ -0,0 +1,49 @@
+export interface HomeLink {
+  label: string
+  href: string
+}
+
+export interface HomeContent {
+  hero: {
+    label: string
+    title: string
+    description: string
+    primaryAction: HomeLink
+    secondaryAction: HomeLink
+    imageAlt: string
+  }
+  tasks: {
+    title: string
+    description: string
+    items: Array<{
+      title: string
+      body: string
+      command: string
+      link: HomeLink
+    }>
+  }
+  firstRun: {
+    title: string
+    description: string
+    steps: Array<{
+      title: string
+      command: string
+      body: string
+    }>
+  }
+  evidence: {
+    title: string
+    description: string
+    code: string
+    link: HomeLink
+  }
+  layers: {
+    title: string
+    description: string
+    items: Array<{
+      title: string
+      body: string
+      link: HomeLink
+    }>
+  }
+}

package/templates/vitepress/.vitepress/navigation/routes.ts

@@ -0,0 +1,146 @@
+import type { DefaultTheme } from 'vitepress'
+
+export type DocsLocale = 'en' | 'zh'
+
+interface LocalizedText {
+  en: string
+  zh: string
+}
+
+export interface RouteItem {
+  slug: string
+  label: LocalizedText
+}
+
+export interface RouteSection {
+  id: 'start' | 'tasks' | 'reference' | 'learn' | 'ai'
+  label: LocalizedText
+  items: readonly RouteItem[]
+}
+
+const item = (slug: string, en: string, zh: string): RouteItem => ({ slug, label: { en, zh } })
+
+export const routeSections = [
+  {
+    id: 'start',
+    label: { en: 'Start', zh: '开始' },
+    items: [
+      item('', 'Start here', '从这里开始'),
+      item('install', 'Install and initialize', '安装并初始化'),
+      item('first-run', 'Your first run', '第一次运行'),
+      item('diagnose', 'Run a diagnosis', '运行诊断'),
+      item('choose-next', 'Choose the next task', '选择下一项任务'),
+    ],
+  },
+  {
+    id: 'tasks',
+    label: { en: 'Tasks', zh: '任务' },
+    items: [
+      item('', 'Task index', '任务索引'),
+      item('adopt-existing', 'Adopt an existing workspace', '接入已有 workspace'),
+      item('create-project', 'Create a package or app', '创建包或应用'),
+      item('checks', 'Run checks', '运行校验'),
+      item('reports', 'Reports and output', '报告与输出'),
+      item('ci', 'Add checks to CI', '把校验加入 CI'),
+      item('release', 'Release packages', '发布包'),
+      item('troubleshooting', 'Troubleshoot', '排障'),
+    ],
+  },
+  {
+    id: 'reference',
+    label: { en: 'Reference', zh: '参考' },
+    items: [
+      item('', 'Reference overview', '参考总览'),
+      item('commands', 'Command reference', '命令参考'),
+      item('config', 'Configuration', '配置文件'),
+      item('execution-model', 'Execution model', '执行模型'),
+      item('output', 'Output formats', '输出格式'),
+      item('aliases', 'Command aliases', '命令别名'),
+      item('templates', 'Templates', '模板'),
+      item('template-assets', 'Managed template assets', '受管模板资产'),
+    ],
+  },
+  {
+    id: 'learn',
+    label: { en: 'Learn', zh: '理解' },
+    items: [
+      item('', 'Learn overview', '理解总览'),
+      item('repoctl-model', 'How repoctl fits in', 'repoctl 如何融入仓库'),
+      item('monorepo/', 'Monorepo foundations', 'Monorepo 基础'),
+      item('monorepo/manage', 'Manage a monorepo', '管理 Monorepo'),
+      item('monorepo/publish', 'Publishing and changelogs', '发包与变更日志'),
+      item('monorepo/commands', 'Monorepo commands', 'Monorepo 命令'),
+      item('monorepo/templates', 'Template systems', '模板体系'),
+      item('monorepo/troubleshooting', 'Monorepo troubleshooting', 'Monorepo 排障'),
+      item('packages/', 'Modern npm packages', '现代 npm 包'),
+      item('packages/modern-overview', 'Modern package guide', '现代包指南'),
+      item('packages/reuse-javascript', 'Reuse JavaScript', '复用 JavaScript'),
+      item('packages/module-extensions', 'Module extensions', '模块文件后缀'),
+      item('packages/runtime-globals', 'Runtime globals', '运行时关键字'),
+      item('packages/publish', 'Publish a package', '发布 npm 包'),
+      item('packages/modern/', 'Package details', '现代包细节'),
+      item('packages/modern/esm-vs-cjs', 'ESM and CommonJS', 'ESM 与 CommonJS'),
+      item('packages/modern/dts', 'Type declarations', '类型声明'),
+      item('packages/modern/package-entry-points', 'Package entry points', '包入口'),
+      item('packages/modern/bundlers', 'Bundlers', '构建工具'),
+      item('packages/modern/typescript', 'TypeScript', 'TypeScript'),
+      item('tools/', 'Tool guides', '工具专题'),
+      item('tools/pnpm', 'pnpm', 'pnpm'),
+      item('tools/turborepo', 'Turborepo', 'Turborepo'),
+      item('tools/changeset', 'Versioning', '版本管理'),
+      item('tools/husky', 'Husky', 'Husky'),
+      item('tools/lint-staged', 'lint-staged', 'lint-staged'),
+      item('tools/renovate', 'Renovate', 'Renovate'),
+      item('tools/llms-txt', 'llms.txt', 'llms.txt'),
+    ],
+  },
+  {
+    id: 'ai',
+    label: { en: 'AI', zh: 'AI' },
+    items: [
+      item('', 'AI documentation', 'AI 文档'),
+      item('llms-txt', 'llms.txt', 'llms.txt'),
+    ],
+  },
+] as const satisfies readonly RouteSection[]
+
+export type RouteSectionId = (typeof routeSections)[number]['id']
+
+function prefixFor(locale: DocsLocale) {
+  return locale === 'zh' ? '/zh' : ''
+}
+
+export function routePath(section: RouteSectionId, slug: string, locale: DocsLocale) {
+  const prefix = prefixFor(locale)
+  return `${prefix}/${section}/${slug}`.replace(/\/+/g, '/')
+}
+
+function sectionItems(section: RouteSection, locale: DocsLocale): DefaultTheme.SidebarItem[] {
+  return section.items.map(route => ({
+    text: route.label[locale],
+    link: routePath(section.id, route.slug, locale),
+  }))
+}
+
+export function createSidebars(locale: DocsLocale): DefaultTheme.SidebarMulti {
+  const prefix = prefixFor(locale)
+  return Object.fromEntries(routeSections.map(section => [
+    `${prefix}/${section.id}/`,
+    [{ text: section.label[locale], items: sectionItems(section, locale) }],
+  ]))
+}
+
+export function createNav(locale: DocsLocale): DefaultTheme.NavItem[] {
+  const prefix = prefixFor(locale)
+  const text = locale === 'zh'
+    ? { start: '开始', tasks: '任务', reference: '参考', learn: '理解', ai: 'AI 文档' }
+    : { start: 'Start', tasks: 'Tasks', reference: 'Reference', learn: 'Learn', ai: 'AI Docs' }
+  return (Object.keys(text) as RouteSectionId[]).map(section => ({
+    text: text[section],
+    link: `${prefix}/${section}/`.replace(/\/+/g, '/'),
+  }))
+}
+
+export function allDocumentRoutes(locale: DocsLocale) {
+  return routeSections.flatMap(section => section.items.map(item => routePath(section.id, item.slug, locale)))
+}

package/templates/vitepress/.vitepress/seo.ts

@@ -0,0 +1,54 @@
+import type { HeadConfig, TransformContext } from 'vitepress'
+
+export const siteOrigin = 'https://repoctl.icebreaker.top'
+
+function routeFromPage(page: string) {
+  const withoutExtension = page.replace(/\.md$/, '')
+  if (withoutExtension === 'index') {
+    return '/'
+  }
+  if (withoutExtension.endsWith('/index')) {
+    return `/${withoutExtension.slice(0, -6)}`
+  }
+  return `/${withoutExtension}`
+}
+
+function localeRoutes(page: string) {
+  const sourcePage = page.startsWith('zh/') ? page.slice(3) : page
+  const english = routeFromPage(sourcePage)
+  const chinese = routeFromPage(`zh/${sourcePage}`)
+  return { english, chinese }
+}
+
+export function createPageHead({ page, title, description }: TransformContext): HeadConfig[] {
+  const { english, chinese } = localeRoutes(page)
+  const isChinese = page.startsWith('zh/')
+  const current = isChinese ? chinese : english
+  const canonical = `${siteOrigin}${current}`
+  const socialImage = `${siteOrigin}/brand/repoctl-social-${isChinese ? 'zh' : 'en'}.png`
+  const socialImageAlt = isChinese
+    ? 'repoctl：面向 pnpm 与 Turborepo monorepo 的任务型 CLI'
+    : 'repoctl: task-first CLI for pnpm and Turborepo monorepos'
+
+  return [
+    ['link', { rel: 'canonical', href: canonical }],
+    ['link', { rel: 'alternate', hreflang: 'en', href: `${siteOrigin}${english}` }],
+    ['link', { rel: 'alternate', hreflang: 'zh-CN', href: `${siteOrigin}${chinese}` }],
+    ['link', { rel: 'alternate', hreflang: 'x-default', href: `${siteOrigin}${english}` }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:site_name', content: 'repoctl' }],
+    ['meta', { property: 'og:title', content: title }],
+    ['meta', { property: 'og:description', content: description }],
+    ['meta', { property: 'og:url', content: canonical }],
+    ['meta', { property: 'og:locale', content: isChinese ? 'zh_CN' : 'en_US' }],
+    ['meta', { property: 'og:image', content: socialImage }],
+    ['meta', { property: 'og:image:width', content: '1200' }],
+    ['meta', { property: 'og:image:height', content: '630' }],
+    ['meta', { property: 'og:image:alt', content: socialImageAlt }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:title', content: title }],
+    ['meta', { name: 'twitter:description', content: description }],
+    ['meta', { name: 'twitter:image', content: socialImage }],
+    ['meta', { name: 'twitter:image:alt', content: socialImageAlt }],
+  ]
+}

package/templates/vitepress/.vitepress/theme/Layout.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { useData } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import { computed } from 'vue'
+
+const { Layout } = DefaultTheme
+const { lang } = useData()
+const notFoundTitle = computed(() => lang.value === 'zh-CN' ? '页面不存在' : 'Page not found')
+const notFoundBody = computed(() => lang.value === 'zh-CN'
+  ? '这个地址不属于新的文档结构。请从开始、任务或参考章节继续。'
+  : 'This address is not part of the new documentation structure. Continue with Start, Tasks, or Reference.')
+</script>
+
+<template>
+  <Layout>
+    <template #not-found>
+      <main class="repoctl-not-found">
+        <p class="repoctl-not-found__code">
+          404
+        </p>
+        <h1>{{ notFoundTitle }}</h1>
+        <p>{{ notFoundBody }}</p>
+        <a href="/start/">{{ lang === 'zh-CN' ? '返回开始' : 'Back to Start' }}</a>
+      </main>
+    </template>
+  </Layout>
+</template>