@tenphi/cookbook 0.20.4 → 0.21.0

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,61 @@
+---
+title: Cookbook
+description: 根据仓库或已发布的 npm 包，创建符合产品风格的静态 Astro 文档站点。
+template: splash
+seo:
+  title: Cookbook — 与代码保持同步、契合产品风格的文档
+hero:
+  title: 与代码放在一起的文档。
+  tagline: Cookbook 是一套 Astro 文档工具。将仓库中的 Markdown 或已发布的 npm 包转换为可搜索的静态站点，再根据产品调整颜色、字体排版和组件。
+  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
+---
+## 主要功能
+
+* **直接使用现有文档。** 从仓库读取 Markdown、MDX 和本地资源，或使用已锁定版本和完整性校验值的 npm 包构建站点。[内容来源](../content-sources.md)。
+* **生成 API 参考。** 将本地 OpenAPI 规范转换为可搜索的概览和每个操作的独立页面，展示参数、请求体、响应和示例。[OpenAPI 参考](../content-sources.md#openapi-references)。
+* **内置搜索。** Pagefind 在本地为页面和标题建立索引，支持键盘快捷键，搜索资源按需加载。[搜索](../site-navigation.md#search)。
+* **适应文档增长的导航。** 使用标签页和分组侧边栏组织章节，提供页内目录、上一页和下一页链接，以及移动端抽屉导航。[搜索与导航](../site-navigation.md)。
+* **技术写作组件。** 在 MDX 中使用标签页、提示框、卡片、步骤、代码组、带复制功能的代码高亮，以及隔离运行的交互预览。[内容编写组件](../authoring.mdx)。
+* **契合产品的主题。** 通过 [Tasty](../upstream/tasty/README.md) 和 [Glaze](../upstream/glaze/README.md) 配置品牌颜色、语义色板、字体、排版和组件的各个部分。浅色、深色和高对比度模式都使用构建时生成的静态 CSS。[主题与组件](../theme-and-components.md)。
+* **语言与版本。** 提供翻译页面和不同版本的文档；切换时，如果存在对应页面，就会直接打开该页面。[语言与版本](../site-navigation.md#contents-languages-and-versions)。
+* **发布前检查。** 检测无效链接、缺失资源、重复路由和错误的导航配置，并指出源文件位置。将预渲染 HTML 部署到任意静态托管服务。[质量检查](../quality-checks.md)。
+* **便于分享和读取的页面。** 发布规范网址、社交预览、站点地图、可下载的 Markdown，以及供编程智能体使用的 `llms.txt` 索引。[发布元数据](../publishing.md)。
+
+## 从你的仓库开始
+
+在已有 `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 站点。
+
+## 浏览指南
+
+* [入门](./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.21.0",
   "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.21.0",
+    "@tenphi/renderer": "0.21.0"
   },
   "peerDependencies": {
     "astro": "^7.3.2"