@tenphi/cookbook 0.20.4 → 0.20.5

package/docs/troubleshooting.md

@@ -36,7 +36,7 @@ contrast. Browser checks complement the numeric diagnostics.
   `doctor --public-dir ./static` if your Astro app uses a custom public directory.
 - **Google request fails:** check the exact family name and supported weights and
   styles. Explicit requests reject missing styles; shorthand warns if italics
-  are unavailable. See [font configuration](./theme-and-components.md#change-font-families).
+  are unavailable. See [font configuration](./fonts-and-typography.md#change-font-families).
 - **Offline cache miss:** warm the cache with `cache: "reuse"` while online, and
   retain `<Astro cacheDir>/cookbook-fonts`. The key includes the requested family,
   weights, and styles. `cache: "refresh"` intentionally needs the network.

package/docs/zh/getting-started.md

@@ -0,0 +1,109 @@
+---
+title: 入门
+description: 创建文档站点、为现有仓库编写文档，或使用已发布的 npm 包。
+sidebar:
+  order: 2
+---
+
+Cookbook 需要 Node.js 22.19 或更高版本。
+
+## 创建第一个站点
+
+```sh
+npm create @tenphi/cookbook@latest my-docs -- --yes
+cd my-docs
+npm run dev
+```
+
+创建工具会生成 README、Astro 配置和 `docs.config.ts`，然后安装依赖。它还会写入包含编程智能体指令的 `AGENTS.md`。编辑 `README.md` 可更改首页；添加 `docs/guide.md` 可创建 `/guide`。新增或修改的页面会直接出现在开发服务器中，无须重启。
+
+## 为现有仓库编写文档
+
+在仓库根目录运行：
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+生成的 `docs.config.ts` 会指向你的仓库。仓库根目录的 README 成为首页，`docs/**/*.{md,mdx}` 提供其他页面。Cookbook 直接读取这些文件，不会复制或改写。
+
+使用 `--no-install` 可先生成文件而不安装依赖。在非交互模式下，创建工具不会覆盖非空的目标目录。
+
+## 为已发布的 npm 包编写文档
+
+```sh
+npm create @tenphi/cookbook@latest my-package-docs -- \
+  --package @scope/package@latest --yes
+cd my-package-docs
+npm run dev
+```
+
+创建工具会从实际发布的包中查找文档，并把准确的版本和完整性校验值写入 `cookbook.lock.json`。请提交此文件。被文档化的软件包不会安装，其生命周期脚本也不会运行。如需重新解析指定的标签或版本范围，请运行 `npm run update`。
+
+## 加入现有 Astro 项目
+
+Cookbook 要求 Astro 使用 `output: "static"`。如果你的项目使用 `output: "server"`，请为文档新建一个独立的静态 Astro 项目。
+
+```sh
+npx astro add @tenphi/cookbook
+```
+
+Astro 配置只需要添加一个集成：
+
+```ts
+import { defineConfig } from "astro/config";
+import cookbook from "@tenphi/cookbook";
+
+export default defineConfig({ integrations: [cookbook()] });
+```
+
+Cookbook 自带 Astro 渲染器，并会自动查找 `docs.config.ts`。如果没有文档配置，它会按照 README 和 `docs/` 的约定读取内容。
+
+## 配置站点
+
+可以先查看完整的[品牌、标志和字体示例](../recipes.md)。若要深入调整样式或添加组件，请阅读[自定义规则](../customization-rules.md)。这些规则和上游参考资料也包含在安装后的 Cookbook 包中。
+
+在 `astro.config.ts` 旁创建 `docs.config.ts`：
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Example Project",
+    description: "Documentation for Example Project",
+    repository: "https://github.com/example/project",
+  },
+  theme: {
+    brand: { from: "#2f5bff" },
+    fonts: { body: "Inter", heading: "Newsreader" },
+  },
+});
+```
+
+修改 `theme.fonts` 可使用[按名称指定的 Google Fonts 或你自己的字体文件](../fonts-and-typography.md)。使用 `theme.presets` 调整排版细节，使用 `theme.styles` 调整内置元素，并结合 `defineComponent()` 与 `theme.customStyles` 添加新元素。[主题指南](../theme-and-components.md)介绍了起点；[组件样式参考](../component-styles.md)列出了全部可自定义部分。
+
+集成和 CLI 读取同一份配置。支持的文件名依优先顺序为 `docs.config.ts`、`.mts`、`.js` 和 `.mjs`。在集成中显式传入的 `config` 对象优先；`configFile: false` 会关闭自动查找。若配置文件位于其他位置，可使用 `cookbook({ configFile: "./config/manual.ts" })` 和 `cookbook doctor --config ./config/manual.ts`。
+
+## 单体仓库的根目录
+
+位于 `apps/docs/` 的应用可以这样读取仓库内容：
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({ root: "../.." });
+```
+
+`root` 相对于文档配置文件，用来定位内容、本地资源和 `cookbook.lock.json`。从应用目录运行 `npm run doctor`，它会解析出与集成相同的仓库根目录。对于包含多个软件包的站点，每个内容来源也可以单独声明根目录。
+
+## 验证并发布
+
+```sh
+npm run validate
+npm run preview
+```
+
+其他指南目前仍以英文提供，包括[示例](../examples.md)、[内容编写组件](../authoring.mdx)、[AI 智能体工作流程](../ai-agents.md)、[部署](../deployment.md)和[按版本升级指南](../migration.md)。如需可修改的完整配置，可从[示例配置](../recipes.md)开始。如果验证失败，请查看[故障排查](../troubleshooting.md)。

package/docs/zh/index.md

@@ -0,0 +1,63 @@
+---
+title: Cookbook
+description: 根据仓库或已发布的 npm 包，创建符合产品风格的静态 Astro 文档站点。
+template: splash
+seo:
+  title: Cookbook — 与代码保持同步、契合产品风格的文档
+hero:
+  title: 与代码放在一起的文档。
+  tagline: 使用仓库中的 Markdown 或锁定版本的 npm 包创建静态 Astro 文档站点，再根据产品调整颜色、字体排版和组件。
+  image:
+    html: '<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
+  actions:
+    - text: 开始使用
+      link: /zh/getting-started/
+      variant: primary
+    - text: 比较工具（英文）
+      link: /comparison/
+      variant: secondary
+sidebar:
+  label: 概览
+  order: 1
+---
+## 从你的仓库开始
+
+在已有 `README.md` 或 `docs/` 目录的项目中运行：
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+Cookbook 会直接读取原位置的文件。你也可以[创建新站点](./getting-started.md)、[为实际发布到 npm 的文件编写文档](./getting-started.md)，或[将 Cookbook 加入现有 Astro 项目](./getting-started.md)。
+
+## 本站就是一个示例
+
+你正在阅读的页面来自 [docs/zh/index.md](https://github.com/tenphi/cookbook/blob/main/docs/zh/index.md)。一个小型 [Astro 应用](https://github.com/tenphi/cookbook/tree/main/apps/reference) 直接从仓库根目录的 `docs/` 构建站点。导航、搜索、代码操作、编辑链接和 Git 更新时间都可用于任何 Cookbook 站点。
+
+## 内容与设计由你决定
+
+### 让源文件留在原处
+
+直接使用仓库中的 Markdown 和本地资源，无须复制到 Astro 内容目录。Cookbook 还可以读取 OpenAPI 规范，或读取已锁定版本和完整性校验值的 npm 包中的文档。[了解内容来源](../content-sources.md)。
+
+### 调整站点外观
+
+从品牌颜色入手，再通过 [Tasty](../upstream/tasty/README.md) 和 [Glaze](../upstream/glaze/README.md) 配置语义色板、字体、排版以及组件的命名部分。`theme.styles` 中的局部覆盖会在提取 CSS 前与 Cookbook 的默认样式合并，浏览器只会收到静态 CSS。[了解主题](../theme-and-components.md)。
+
+### 在发布前发现问题
+
+无效链接、缺失资源、重复路由和错误的导航配置会产生包含源文件位置的错误。生成结果是带有本地搜索功能的预渲染 HTML，可部署到任意静态托管服务。[查看验证流程](../quality-checks.md)。
+
+## 浏览指南
+
+* [入门](./getting-started.md)：仓库、npm 包和现有 Astro 项目的使用方法。
+* [文档工具对比](../comparison.md)：Cookbook 的内容与自定义方式。
+* [示例](../examples.md)：仓库、单体仓库、软件包和共享主题配置。
+* [搜索与导航](../site-navigation.md)：读者如何找到页面。
+* [内容编写](../authoring.mdx)：页面、组件和交互示例。
+* [主题与组件](../theme-and-components.md)：品牌、设计标记、字体、内置样式和自定义组件。
+* [部署](../deployment.md)：验证与静态托管。
+
+其他文档目前仍以英文提供。另请参阅 [AI 智能体工作流程](../ai-agents.md)、[配置参考](../configuration.md)、[发布选项](../publishing.md)和 [CLI 参考](../cli.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.20.4",
+  "version": "0.20.5",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.20.4",
-    "@tenphi/renderer": "0.20.4"
+    "@tenphi/docs": "0.20.5",
+    "@tenphi/renderer": "0.20.5"
   },
   "peerDependencies": {
     "astro": "^7.3.2"