文档站开发
Kuruwa 文档站在 apps/docs/ 中实现，使用 Astro、Yarn 4 workspace 和仓库 Markdown 内容。它是静态站点，不包含搜索、主题切换、外部字体或 CDN；持续集成与发布由仓库工作流负责，见下文。站点默认从根路径提供服务，不设置 Astro base。
工具链
根 package.json 固定：
packageManager: [email protected]
workspaces: apps/*
nodeLinker: node-modulesdevenv.nix 提供 nodejs_24 与 yarn-berry，因此开发 shell 内不需要全局安装包管理器。修改环境后在本仓库根目录重新加载：
direnv reload
direnv export json >/dev/null
node --version
yarn --versionworkspace 的精确管理器版本仍以 packageManager 为准；需要核对 Corepack 实际解析到的版本时，在仓库根运行：
corepack yarn --version不要把 Corepack shim 写进全局目录。安装与检查：
yarn install
yarn install --immutable
yarn docs:check
yarn docs:buildyarn.lock 必须提交；node_modules/、apps/docs/.astro/、apps/docs/dist/ 与 Yarn 的安装状态文件是生成物。
本地预览
yarn docs:dev # 开发服务器
yarn docs:preview # 构建后预览两者默认监听 127.0.0.1:4325。生产构建输出在 apps/docs/dist/，Astro 仍从根路径生成页面，不配置 base；Forgejo Pages 的上传端点只由工作流使用，不是站点公开地址。
持续集成与发布
工作流定义在 .forgejo/workflows/docs.yaml，名称是 Documentation CI：
push到main、pull_request和workflow_dispatch都会触发；push与pull_request使用同一组路径过滤，覆盖apps/docs/**、docs/**、CONTEXT.md、README.md、PLAN.md、assets/**、examples/**、根工作区与 Yarn 清单、devenv/flake/Nix 文件以及该工作流自身；- job 在
[nixos-builder, high-performance]runner 上运行，超时 90 分钟。
检查步骤在仓库根目录的 devenv shell 中执行，与本地命令一致：
yarn install --immutable
yarn docs:check
yarn docs:build只有 main 上的 push 或手动 workflow_dispatch 会在检查与构建成功后发布 apps/docs/dist；pull_request 只检查与构建，不发布。发布使用 Forgejo Pages 的 git-pages/action@v2 和 runner 内置的 forgejo.token，仓库不需要另配密钥。
工作流中的 site 是 Pages 的部署端点：
https://pages.gjz010.com/deploy/gjz010-harness/kuruwa/该地址是上传端点，不要写进 Astro 的 base。公开文档地址为 https://kuruwa.gjz010.page/，已通过实际 HTTPS 访问验证。域名绑定到 gjz010-harness/kuruwa，后续 main 上的相关改动由上述工作流自动构建并发布；发布结果可在仓库 Actions 中查看。
内容清单
仓库 Markdown 是唯一内容来源，站点不复制正文。公开页面由 apps/docs/src/lib/public-content.json 的 groups 选择：
{
"id": "docs/packaging",
"source": "docs/packaging.md",
"route": "/docs/nix-install/",
"label": "Nix 安装",
"description": "面向用户的导航说明。"
}source相对仓库根目录，必须存在。route使用以/结尾的静态路径；首页固定为/。id是 Astro glob loader 去掉.md后的内容 ID，必须与source对应。label与description直接显示在侧栏，应写成用户能理解的目的，而不是内部任务名。- 只有
"optional": true的条目允许暂时缺失；其他缺失源会在构建时直接报错。
content.config.ts 只把这些源加载进 docs collection。首页只渲染路由为 / 的条目，其他 /docs/... 路由由动态页面生成。新增公开页面时修改清单，不要把 Markdown 复制到 apps/docs/。
当前公开路线覆盖快速开始、核心概念、Nix 安装、项目根与后台服务、CLI/授权契约、交互管理和文档站开发。工作计划、任务清单与内部验收日志不进入侧栏。
链接改写
Markdown 中的相对链接由 apps/docs/src/lib/repo-links.mjs 在构建时改写：
- 指向公开 Markdown 的链接改为站点路由；
- 指向
media白名单资源的链接改为/media/<path>； - 指向非公开但必要的源文件时，必须在
sourceLinks中显式登记，避免死链或编造远程 URL； - 外部 URL、根路径和纯
#锚点保持原样； - 缺失文件、越出仓库的路径、未登记的 Markdown/媒体目标、带查询字符串的链接都会使构建失败。
新增图片或下载文件时，在清单的 media 中登记 source、公开 path、contentType，需要下载名时增加 downloadName。assets/logo.svg 是站点 favicon 使用的纯图标资产，页头使用 assets/logo-horizontal.svg 横版组合；站点直接引用，不复制或改写。
样式约定
- 品牌色使用红、橙、黄，正文保持浅色中性背景，代码块使用深色 Shiki
github-dark。 - 桌面为左侧分组导航、中间正文、右侧 H2/H3 目录；窄屏使用顶部目录菜单和内联目录。
- 代码块与宽表格横向滚动，不挤压正文。
- 不加载外部字体或 CDN；字体栈只使用系统字体。
- 修改视觉后运行
yarn docs:check与yarn docs:build，再启动yarn docs:preview做真实页面验收。