Project AIRI 文档站开发指南从本地预览、类型检查到多语言侧边栏挂载的完整工作流【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇指南讲解 Project AIRI 仓库中 VitePress 文档站docs目录的本地开发、校验构建与内容贡献流程你会掌握如何通过pnpm dev:docs启动预览、用typecheck与build验证文档、以及新增英文页面时如何正确挂载到en侧边栏使其不仅“能通过 URL 访问”更“能出现在导航中”。结合仓库内的 docs/package.json、docs/.vitepress/config.ts 与 docs/netlify.toml本篇将同时给出命令背后的真实脚本映射与配置依据方便搜索引擎、Agent 与 LLM 直接定位到源码证据。文档站的整体布局按语言locale组织内容Project AIRI 的官方文档站使用 VitePress 实际布局docs/ ├── .vitepress/ # VitePress 站点配置、主题、组件与数据函数 │ ├── config.ts # 站点全局配置导航、侧边栏、locales、markdown │ ├── theme/ # 自定义主题样式与入口 │ ├── components/ # 首页/文档页自定义 Vue 组件 │ └── meta.ts # 站点名称、描述、社交链接等元信息 ├── content/ # 文档内容即 VitePress 的 srcDir │ ├── en/ # 英文root locale默认语言 │ ├── zh-Hans/ # 简体中文 │ ├── ja/ # 日语 │ ├── ko/ # 韩语 │ └── public/ # 站点级静态资源图片、字体等 ├── package.json # 包名 proj-airi/docs文档站独立脚本 ├── tsconfig.json # 文档站 TS/Vue 类型检查配置 └── netlify.toml # Netlify 部署配置内容按语言组织是理解文档站的第一步所有 Markdown 页面都位于docs/content/locale/之下每个语言目录内部再按docs/、blog/、about/、references/等栏目分门别类。这个约定与 docs/.vitepress/config.ts 中的srcDir: content设置一一对应——VitePress 会直接把content作为内容源目录因此页面的相对链接、静态资源解析都以它为准。如果你负责的文档改动涉及新语言或新栏目首先就要在这个docs/content/locale树中确认目标位置这与仓库里其它应用如apps/stage-web、apps/stage-tamagotchi以src/组织源码的惯例不同属于文档站专属的“内容即目录”模式。环境准备pnpm 工作区与 Node 版本约束文档站不是孤立项目而是 monorepo 中的一个 pnpm workspace 成员。仓库根 package.json 声明了workspaces其中明确包含docs/**文档站的包名是proj-airi/docs见 docs/package.json所有面向文档站的脚本都会通过包名精确筛选。根 package.json 中dev:docs的真实定义是pnpm -rF proj-airi/docs run dev即“递归地、仅针对proj-airi/docs这个包执行其dev脚本”。理解这一点很重要pnpm dev:docs不是硬编码的单个命令而是 pnpm workspace 的过滤语法-r表示递归进入工作区子包-F--filter表示只选择proj-airi/docs。在运行任何 pnpm 命令之前建议先按仓库约定准备好 Node 环境仓库通过根目录 .tool-versions 固定 Node.js 版本当前为nodejs 26.7.0推荐使用 mise 之类的版本管理器读取该文件启用 Corepack 以获得仓库锁定的 pnpm根package.json中packageManager声明为pnpm11.24.0首次开发时执行mise install安装固定版本再用mise exec -- pnpm install安装依赖。如果你已经配置过 mise 的 shell shims那么后续命令可以直接写pnpm ...否则需要套用mise exec -- pnpm ...的形式。本地开发预览pnpm dev:docs从仓库根目录执行pnpm dev:docs该命令会启动 VitePress 的开发服务器。由于底层是 docs/package.json 中的vitepress dev你得到的是标准的 VitePress 热更新开发体验编辑docs/content/locale/**/*.md或docs/.vitepress下的配置文件后浏览器会即时刷新非常适合边写文档边校对排版、代码块高亮与侧边栏层级。如果你习惯使用 antfu/ni 这类统一包管理器命令的工具可以等价地运行nr dev:docsnr会自动探测仓库使用的包管理器这里是 pnpm并转发到对应的run命令。这只是一个开发体验上的等价替换pnpm dev:docs与nr dev:docs指向同一个脚本。校验与构建typecheck 与 build改动文档后、提交之前文档站提供了两个独立的验证命令建议按顺序执行pnpm -F proj-airi/docs typecheck pnpm -F proj-airi/docs buildtypecheck把 Markdown 当作 Vue 组件做静态检查pnpm -F proj-airi/docs typecheck对应 docs/package.json 中的vue-tsc --noEmit。关键在于 docs/tsconfig.json 的两处配置vueCompilerOptions.vitePressExtensions: [.md]——让vue-tsc把.md文件当作 VitePress 扩展的 Vue 单文件组件来处理types: [vitepress/client, vue]——提供 VitePress 客户端上下文与 Vue 的类型声明。这意味着文档里的 Vue 组件片段、frontmatter 使用方式乃至模板语法都会纳入类型检查能从早期拦截拼写错误或类型不匹配而不只是渲染时才暴露问题。这也解释了为什么文档站虽然全是 Markdown却拥有与源码工程一致的严格类型检查strict: true。build生成可发布的静态站点pnpm -F proj-airi/docs build对应 docs/package.json 中的vitepress build产物输出到docs/.vitepress/dist。除此之外docs/package.json 还提供了三个与构建/预览相关的脚本脚本命令用途buildvitepress build标准生产构建产物在docs/.vitepress/distbuild:baseBASE_URL/docs/ vitepress build以子路径/docs/为 base 的构建子路径部署场景previewvitepress preview本地预览已构建的产物验证生产结果build:base与 docs/.vitepress/config.ts 中的withBase辅助函数相配合config.ts会根据环境变量BASE_URL动态拼接导航与侧边栏链接保证站点部署在域名根路径或/docs/子路径下都能正确解析。新增英文页面侧边栏挂载是关键步骤文档站新增内容的规范流程在关联文档中有一条核心警告新增英文页面时还要把它加到docs/.vitepress/config.ts的en侧边栏中否则该页面虽然可以通过 URL 访问却不会出现在导航里。也就是说“文件存在”与“导航可见”在 VitePress 中是两回事。一个完整的“新增英文文档页”工作流如下创建内容文件在docs/content/en/docs/栏目/下新建 Markdown 文件并在 frontmatter 中写title与description与现有页面保持一致的元信息风格。挂载到侧边栏打开 docs/.vitepress/config.ts在enlocale 的themeConfig.sidebar数组中找到对应的分组例如Developer Guide → Contributing分组添加形如{ text: 页面标题, link: withBase(/en/docs/contributing/页面名) }的条目。注意withBase包装侧边栏与导航中的链接一律通过withBase()生成它读取env.BASE_URL并把站点基础路径拼到链接前避免子路径部署时链接失效。同步其它语言侧边栏仓库配置了root英文、zh-Hans、ja、ko四个 locale每个 locale 都有独立的sidebar数组。英文侧边栏中的“Documentation Site”等条目在 docs/.vitepress/config.ts 中一一对应到各语言的docs/contributing/docs页面因此新增或改名页面时通常需要同步维护四份侧边栏保持导航结构一致。这条规则是文档站贡献中最容易踩坑的地方只创建文件而不更新侧边栏页面会“存在但隐形”。另外config.ts中开启了cleanUrls: trueURL 中不需要.html后缀侧边栏链接统一写目录/文件名路径即可。站点配置速览config.ts 的可复用要点.vitepress/config.ts 是整个文档站的“控制中心”其中有几个与文档写作直接相关的配置值得了解多语言架构localesrooten、zh-Hans、ja、ko四个 locale 各自声明label、lang与独立的themeConfig导航、侧边栏、按钮文案保证多语言内容在导航层面互不干扰Markdown 增强插件markdown.config中启用了tasklist任务列表与footnote脚注两个markdown-it插件因此文档中可以放心使用- [ ]任务列表与[^1]脚注语法见 config.ts代码高亮主题markdown.theme使用 catppuccin 主题亮色catppuccin-latte、暗色catppuccin-mochaconfig.ts代码块默认配色会随站点主题切换站内搜索themeConfig.search.provider: local启用 VitePress 内置本地全文搜索无需外部服务其它细节appearance: dark默认暗色外观、lastUpdated: true显示最后更新时间、sitemap生成站点地图、head中注入 Open Graph 与 Twitter 卡片等 SEO 元信息。写作文档时引用以上能力的配置位置比口头描述更可信例如“页面是否出现在搜索里”其实由search.provider与页面 frontmatter 共同决定。生产部署netlify.toml 中的真实构建链路仓库为文档站提供了 Netlify 部署配置 docs/netlify.toml与本地命令形成完整的“开发—校验—部署”闭环[build] base / command pnpm -F proj-airi/docs run build publish /docs/.vitepress/dist [build.environment] NODE_VERSION 24 NODE_OPTIONS --max-old-space-size4096几点值得注意构建命令与本地完全一致CI 上执行的正是pnpm -F proj-airi/docs run build也就是说本地通过build验证过的内容部署结果与本地一致发布目录指向docs/.vitepress/dist即 VitePress 的标准输出目录环境变量中NODE_VERSION 24是 Netlify 构建环境使用的 Node 大版本而本地开发则以 .tool-versions 锁定的版本为准——两者不必完全相同只要构建产物在目标环境可复现即可若部署目标是域名子路径可改用pnpm -F proj-airi/docs run build:base配合BASE_URL/docs/与withBase()完成子路径适配。文档贡献的完整上下文docs.md属于contributing参与贡献文档族同一目录下还有一系列相关指南建议组合阅读以形成完整工作流docs/content/en/docs/contributing/index.md开发环境搭建与首次 Pull Request 的完整流程Fork → Clone → 建分支 → 安装依赖 → 提交 → 创建 PR是“文档之外”的贡献规范底座docs/content/en/docs/contributing/tamagotchi.md 与 docs/content/en/docs/contributing/webui.md分别针对桌面端与 Web 端的开发指引docs/content/en/docs/contributing/desktop-developer-tools.md应用内调试工具说明docs/content/en/docs/contributing/design-guidelines/index.md设计资源与工具指南。从仓库根 package.json 还能看到提交前整个仓库还要求通过pnpm lintmoeru-lint .与pnpm typecheck递归覆盖packages/*、apps/*、server/**与docs的并行类型检查。文档改动虽然只影响docs目录但仍建议至少在文档站范围内跑一次typecheck把 Markdown-as-Vue 的潜在错误扼杀在提交之前。常见问题与排查要点根据上面的源码证据整理几个文档站开发中容易遇到的状况页面能通过 URL 打开但导航里找不到几乎可以确定是漏改了 docs/.vitepress/config.ts 中对应 locale 的sidebar。这是关联文档明确点名的第一陷阱。其它语言侧边栏不同步四个 locale 各自维护侧边栏数组新增英文页面后zh-Hans、ja、ko侧边栏需要按需同步否则多语言导航结构会出现差异。构建失败与类型错误优先检查文档中嵌入的 Vue 组件片段是否符合vue-tsc的检查规则vueCompilerOptions.vitePressExtensions: [.md]会把.md纳入检查范围错误信息会精确到文件与行号。死链接策略config.ts中设置了ignoreDeadLinks: trueVitePress 构建时不会因个别失效内部链接而中断——但这并不意味着可以随意留死链建议仍然人工核对新增页面间的相互引用。从pnpm dev:docs的本地热更新到typecheck/build的双重验证再到en侧边栏挂载与 Netlify 部署这条文档站开发链路在仓库中均有对应的脚本与配置文件可查证。对新手贡献者而言最值得记住的一句话是新增页面 创建docs/content/locale下的 Markdown 文件 在对应 locale 的侧边栏注册条目两步缺一不可。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Project AIRI 文档站开发指南：从本地预览、类型检查到多语言侧边栏挂载的完整工作流
Project AIRI 文档站开发指南从本地预览、类型检查到多语言侧边栏挂载的完整工作流【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇指南讲解 Project AIRI 仓库中 VitePress 文档站docs目录的本地开发、校验构建与内容贡献流程你会掌握如何通过pnpm dev:docs启动预览、用typecheck与build验证文档、以及新增英文页面时如何正确挂载到en侧边栏使其不仅“能通过 URL 访问”更“能出现在导航中”。结合仓库内的 docs/package.json、docs/.vitepress/config.ts 与 docs/netlify.toml本篇将同时给出命令背后的真实脚本映射与配置依据方便搜索引擎、Agent 与 LLM 直接定位到源码证据。文档站的整体布局按语言locale组织内容Project AIRI 的官方文档站使用 VitePress 实际布局docs/ ├── .vitepress/ # VitePress 站点配置、主题、组件与数据函数 │ ├── config.ts # 站点全局配置导航、侧边栏、locales、markdown │ ├── theme/ # 自定义主题样式与入口 │ ├── components/ # 首页/文档页自定义 Vue 组件 │ └── meta.ts # 站点名称、描述、社交链接等元信息 ├── content/ # 文档内容即 VitePress 的 srcDir │ ├── en/ # 英文root locale默认语言 │ ├── zh-Hans/ # 简体中文 │ ├── ja/ # 日语 │ ├── ko/ # 韩语 │ └── public/ # 站点级静态资源图片、字体等 ├── package.json # 包名 proj-airi/docs文档站独立脚本 ├── tsconfig.json # 文档站 TS/Vue 类型检查配置 └── netlify.toml # Netlify 部署配置内容按语言组织是理解文档站的第一步所有 Markdown 页面都位于docs/content/locale/之下每个语言目录内部再按docs/、blog/、about/、references/等栏目分门别类。这个约定与 docs/.vitepress/config.ts 中的srcDir: content设置一一对应——VitePress 会直接把content作为内容源目录因此页面的相对链接、静态资源解析都以它为准。如果你负责的文档改动涉及新语言或新栏目首先就要在这个docs/content/locale树中确认目标位置这与仓库里其它应用如apps/stage-web、apps/stage-tamagotchi以src/组织源码的惯例不同属于文档站专属的“内容即目录”模式。环境准备pnpm 工作区与 Node 版本约束文档站不是孤立项目而是 monorepo 中的一个 pnpm workspace 成员。仓库根 package.json 声明了workspaces其中明确包含docs/**文档站的包名是proj-airi/docs见 docs/package.json所有面向文档站的脚本都会通过包名精确筛选。根 package.json 中dev:docs的真实定义是pnpm -rF proj-airi/docs run dev即“递归地、仅针对proj-airi/docs这个包执行其dev脚本”。理解这一点很重要pnpm dev:docs不是硬编码的单个命令而是 pnpm workspace 的过滤语法-r表示递归进入工作区子包-F--filter表示只选择proj-airi/docs。在运行任何 pnpm 命令之前建议先按仓库约定准备好 Node 环境仓库通过根目录 .tool-versions 固定 Node.js 版本当前为nodejs 26.7.0推荐使用 mise 之类的版本管理器读取该文件启用 Corepack 以获得仓库锁定的 pnpm根package.json中packageManager声明为pnpm11.24.0首次开发时执行mise install安装固定版本再用mise exec -- pnpm install安装依赖。如果你已经配置过 mise 的 shell shims那么后续命令可以直接写pnpm ...否则需要套用mise exec -- pnpm ...的形式。本地开发预览pnpm dev:docs从仓库根目录执行pnpm dev:docs该命令会启动 VitePress 的开发服务器。由于底层是 docs/package.json 中的vitepress dev你得到的是标准的 VitePress 热更新开发体验编辑docs/content/locale/**/*.md或docs/.vitepress下的配置文件后浏览器会即时刷新非常适合边写文档边校对排版、代码块高亮与侧边栏层级。如果你习惯使用 antfu/ni 这类统一包管理器命令的工具可以等价地运行nr dev:docsnr会自动探测仓库使用的包管理器这里是 pnpm并转发到对应的run命令。这只是一个开发体验上的等价替换pnpm dev:docs与nr dev:docs指向同一个脚本。校验与构建typecheck 与 build改动文档后、提交之前文档站提供了两个独立的验证命令建议按顺序执行pnpm -F proj-airi/docs typecheck pnpm -F proj-airi/docs buildtypecheck把 Markdown 当作 Vue 组件做静态检查pnpm -F proj-airi/docs typecheck对应 docs/package.json 中的vue-tsc --noEmit。关键在于 docs/tsconfig.json 的两处配置vueCompilerOptions.vitePressExtensions: [.md]——让vue-tsc把.md文件当作 VitePress 扩展的 Vue 单文件组件来处理types: [vitepress/client, vue]——提供 VitePress 客户端上下文与 Vue 的类型声明。这意味着文档里的 Vue 组件片段、frontmatter 使用方式乃至模板语法都会纳入类型检查能从早期拦截拼写错误或类型不匹配而不只是渲染时才暴露问题。这也解释了为什么文档站虽然全是 Markdown却拥有与源码工程一致的严格类型检查strict: true。build生成可发布的静态站点pnpm -F proj-airi/docs build对应 docs/package.json 中的vitepress build产物输出到docs/.vitepress/dist。除此之外docs/package.json 还提供了三个与构建/预览相关的脚本脚本命令用途buildvitepress build标准生产构建产物在docs/.vitepress/distbuild:baseBASE_URL/docs/ vitepress build以子路径/docs/为 base 的构建子路径部署场景previewvitepress preview本地预览已构建的产物验证生产结果build:base与 docs/.vitepress/config.ts 中的withBase辅助函数相配合config.ts会根据环境变量BASE_URL动态拼接导航与侧边栏链接保证站点部署在域名根路径或/docs/子路径下都能正确解析。新增英文页面侧边栏挂载是关键步骤文档站新增内容的规范流程在关联文档中有一条核心警告新增英文页面时还要把它加到docs/.vitepress/config.ts的en侧边栏中否则该页面虽然可以通过 URL 访问却不会出现在导航里。也就是说“文件存在”与“导航可见”在 VitePress 中是两回事。一个完整的“新增英文文档页”工作流如下创建内容文件在docs/content/en/docs/栏目/下新建 Markdown 文件并在 frontmatter 中写title与description与现有页面保持一致的元信息风格。挂载到侧边栏打开 docs/.vitepress/config.ts在enlocale 的themeConfig.sidebar数组中找到对应的分组例如Developer Guide → Contributing分组添加形如{ text: 页面标题, link: withBase(/en/docs/contributing/页面名) }的条目。注意withBase包装侧边栏与导航中的链接一律通过withBase()生成它读取env.BASE_URL并把站点基础路径拼到链接前避免子路径部署时链接失效。同步其它语言侧边栏仓库配置了root英文、zh-Hans、ja、ko四个 locale每个 locale 都有独立的sidebar数组。英文侧边栏中的“Documentation Site”等条目在 docs/.vitepress/config.ts 中一一对应到各语言的docs/contributing/docs页面因此新增或改名页面时通常需要同步维护四份侧边栏保持导航结构一致。这条规则是文档站贡献中最容易踩坑的地方只创建文件而不更新侧边栏页面会“存在但隐形”。另外config.ts中开启了cleanUrls: trueURL 中不需要.html后缀侧边栏链接统一写目录/文件名路径即可。站点配置速览config.ts 的可复用要点.vitepress/config.ts 是整个文档站的“控制中心”其中有几个与文档写作直接相关的配置值得了解多语言架构localesrooten、zh-Hans、ja、ko四个 locale 各自声明label、lang与独立的themeConfig导航、侧边栏、按钮文案保证多语言内容在导航层面互不干扰Markdown 增强插件markdown.config中启用了tasklist任务列表与footnote脚注两个markdown-it插件因此文档中可以放心使用- [ ]任务列表与[^1]脚注语法见 config.ts代码高亮主题markdown.theme使用 catppuccin 主题亮色catppuccin-latte、暗色catppuccin-mochaconfig.ts代码块默认配色会随站点主题切换站内搜索themeConfig.search.provider: local启用 VitePress 内置本地全文搜索无需外部服务其它细节appearance: dark默认暗色外观、lastUpdated: true显示最后更新时间、sitemap生成站点地图、head中注入 Open Graph 与 Twitter 卡片等 SEO 元信息。写作文档时引用以上能力的配置位置比口头描述更可信例如“页面是否出现在搜索里”其实由search.provider与页面 frontmatter 共同决定。生产部署netlify.toml 中的真实构建链路仓库为文档站提供了 Netlify 部署配置 docs/netlify.toml与本地命令形成完整的“开发—校验—部署”闭环[build] base / command pnpm -F proj-airi/docs run build publish /docs/.vitepress/dist [build.environment] NODE_VERSION 24 NODE_OPTIONS --max-old-space-size4096几点值得注意构建命令与本地完全一致CI 上执行的正是pnpm -F proj-airi/docs run build也就是说本地通过build验证过的内容部署结果与本地一致发布目录指向docs/.vitepress/dist即 VitePress 的标准输出目录环境变量中NODE_VERSION 24是 Netlify 构建环境使用的 Node 大版本而本地开发则以 .tool-versions 锁定的版本为准——两者不必完全相同只要构建产物在目标环境可复现即可若部署目标是域名子路径可改用pnpm -F proj-airi/docs run build:base配合BASE_URL/docs/与withBase()完成子路径适配。文档贡献的完整上下文docs.md属于contributing参与贡献文档族同一目录下还有一系列相关指南建议组合阅读以形成完整工作流docs/content/en/docs/contributing/index.md开发环境搭建与首次 Pull Request 的完整流程Fork → Clone → 建分支 → 安装依赖 → 提交 → 创建 PR是“文档之外”的贡献规范底座docs/content/en/docs/contributing/tamagotchi.md 与 docs/content/en/docs/contributing/webui.md分别针对桌面端与 Web 端的开发指引docs/content/en/docs/contributing/desktop-developer-tools.md应用内调试工具说明docs/content/en/docs/contributing/design-guidelines/index.md设计资源与工具指南。从仓库根 package.json 还能看到提交前整个仓库还要求通过pnpm lintmoeru-lint .与pnpm typecheck递归覆盖packages/*、apps/*、server/**与docs的并行类型检查。文档改动虽然只影响docs目录但仍建议至少在文档站范围内跑一次typecheck把 Markdown-as-Vue 的潜在错误扼杀在提交之前。常见问题与排查要点根据上面的源码证据整理几个文档站开发中容易遇到的状况页面能通过 URL 打开但导航里找不到几乎可以确定是漏改了 docs/.vitepress/config.ts 中对应 locale 的sidebar。这是关联文档明确点名的第一陷阱。其它语言侧边栏不同步四个 locale 各自维护侧边栏数组新增英文页面后zh-Hans、ja、ko侧边栏需要按需同步否则多语言导航结构会出现差异。构建失败与类型错误优先检查文档中嵌入的 Vue 组件片段是否符合vue-tsc的检查规则vueCompilerOptions.vitePressExtensions: [.md]会把.md纳入检查范围错误信息会精确到文件与行号。死链接策略config.ts中设置了ignoreDeadLinks: trueVitePress 构建时不会因个别失效内部链接而中断——但这并不意味着可以随意留死链建议仍然人工核对新增页面间的相互引用。从pnpm dev:docs的本地热更新到typecheck/build的双重验证再到en侧边栏挂载与 Netlify 部署这条文档站开发链路在仓库中均有对应的脚本与配置文件可查证。对新手贡献者而言最值得记住的一句话是新增页面 创建docs/content/locale下的 Markdown 文件 在对应 locale 的侧边栏注册条目两步缺一不可。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考