Menu
帮助生成 OBook 文档站内容，包括配置文件和 markdown 文档。在创建或更新 OBook 文档、为 ofa.js 项目编写文档或生成多语言文档时调用。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | obook-doc-generator |
| description | 帮助生成 OBook 文档站内容，包括配置文件和 markdown 文档。在创建或更新 OBook 文档、为 ofa.js 项目编写文档或生成多语言文档时调用。 |
OBook 是基于 ofa.js 构建的现代化文档系统，使用 Markdown 创建文档站点。此 SKILL 帮助 AI 助手生成 OBook 文档站内容。
适用场景：创建新文档站、添加文档页面、更新现有文档、生成多语言文档、创建 API 文档、为 ofa.js 项目编写教程或指南。
your-project/
├── _config.yaml # 根配置文件
├── cn/ # 中文内容（写作语言）
│ ├── _config.yaml # 语言根配置（定义章节导航）
│ ├── index.html # 首页（可选）
│ ├── footer.html # 页脚组件（可选）
│ ├── documentation/ # 文档章节
│ │ ├── _config.yaml # 章节配置
│ │ └── *.md # Markdown 文件
│ └── api/ # API 章节
│ ├── _config.yaml
│ └── *.md
├── en/ # 英文内容（自动翻译）
└── website/ # 生成的静态站点
关键规则：
documentation/、api/）通过语言根配置的 header 字段定义_config.yaml 来定义页面结构header 决定顶部导航栏显示的章节_config.yaml定义项目基本信息和多语言配置：
name: 我的文档
writingLang: cn
languages:
- cn
- en
- ja
_config.yaml（如 cn/_config.yaml）定义该语言版本的导航结构和章节组织：
index: ./index.html
header:
- name: 教程
url: ./documentation/_config.yaml
- name: API
url: ./api/_config.yaml
- name: 其他
content:
- name: 场景问答
url: ./scenarios/_config.yaml
| 字段 | 说明 |
|---|---|
index | 首页文件路径 |
header | 顶部导航栏章节列表 |
header[].name | 章节显示名称 |
header[].url | 章节配置文件路径（指向章节目录下的 _config.yaml） |
header[].content | 嵌套子章节列表（可选，与 url 二选一） |
_config.yaml定义章节内的页面导航：
- name: 介绍
url: ./introduction.md
- name: 开始使用
content:
- name: 脚本引用
url: ./script-reference.md
- name: 创建第一个应用
url: ./create-first-app.md
- name: 快速上手
url: ./quick-start.md
# 标题
简短的介绍段落。
## 第一节
内容。
### 子节 1.1
详细内容。
## 相关链接
- [链接文本](./related-file.md)
OBook 支持使用 o-playground 组件创建交互式代码演示，展示 ofa.js 项目的运行效果。
规则一：标签内禁止空行
<o-playground> 及其子标签之间不能有空行（连续两个换行符），否则会导致解析错误。可以有正常的换行和缩进。
❌ 错误（有空行）：
<o-playground name="示例">
<code path="demo.html">
<template>
<div>Hello World</div>
</template>
</code>
</o-playground>
✅ 正确（无空行）：
<o-playground name="示例">
<code path="demo.html">
<template>
<div>Hello World</div>
</template>
</code>
</o-playground>
规则二：禁止重复引用 ofa.js
playground 虚拟环境已自动加载 ofa.js，代码中不需要再引用。
❌ 错误（重复加载）：
<o-playground name="Button 基本用法">
<code path="demo.html" preview active>
<template>
<script src="https://cdn.jsdelivr.net/gh/ofajs/ofa.js/dist/ofa.min.mjs" type="module"></script>
<l-m src="https://punch-ui-v2.pages.dev/packages/button/button.html"></l-m>
<p-button>默认按钮</p-button>
</template>
</code>
</o-playground>
✅ 正确（无需引用 ofa.js）：
<o-playground name="Button 基本用法">
<code path="demo.html" preview active>
<template>
<l-m src="https://punch-ui-v2.pages.dev/packages/button/button.html"></l-m>
<p-button>默认按钮</p-button>
</template>
</code>
</o-playground>
规则三：preview 属性仅用于普通模板
<template>（不带 page 或 component 属性）<template page> 或 <template component>原因：Page 模块和组件模块需通过 ofa.js 特定机制加载，不能直接作为预览文件。
<o-playground name="示例名称" style="--editor-height: 500px">
<code path="demo.html">
<template>
<div id="target">Hello World</div>
<script>
console.log("Hello");
</script>
</template>
</code>
</o-playground>
使用多个 <code> 标签定义多个文件：
<o-playground name="组件示例" style="--editor-height: 600px">
<code path="demo.html" preview>
<template>
<l-m src="./my-component.html"></l-m>
<my-component></my-component>
</template>
</code>
<code path="my-component.html" active>
<template component>
<style>
.container { padding: 20px; }
</style>
<div class="container">组件内容</div>
<script>
export default {
tag: "my-component",
data: {},
ready() {
console.log("组件已就绪");
}
};
</script>
</template>
</code>
</o-playground>
<o-playground> 属性：
| 属性 | 说明 |
|---|---|
name | 项目名称，标识项目来源 |
<code> 属性：
| 属性 | 必需 | 说明 |
|---|---|---|
path | 是 | 文件路径和文件名 |
preview | 否 | 标记为预览文件（仅普通模板可用） |
active | 否 | 设为当前激活状态，默认在编辑器中显示 |
unimportant | 否 | 标记为"不重要"文件，可通过设置隐藏 |
样式变量：
| 变量 | 说明 | 默认值 |
|---|---|---|
--editor-height | 编辑器高度 | 200px |
--preview-height | 预览区高度 | 200px |
<template> 类型识别与处理| 类型 | 标记 | 处理方式 | 适用场景 |
|---|---|---|---|
| 普通模板 | <template> | 去掉 <template> 标签，内容直接放入 HTML，自动注入 ofa.js | 快速演示 HTML/JS 代码 |
| Page 模块 | <template page> | 保留 <template page> 标签，作为 ofa.js Page 模块处理 | 演示 ofa.js 页面功能 |
| 组件模块 | <template component> | 保留 <template component> 标签，作为 ofa.js 组件模块处理 | 演示 ofa.js 组件功能 |
普通模板示例：
<template>
<div>Hello World</div>
<script>console.log("Hello");</script>
</template>
Page 模块示例：
<template page>
<style>:host { display: block; }</style>
<div>{{message}}</div>
<script>
export default async () => {
return { data: { message: "Hello" } };
};
</script>
</template>
组件模块示例：
<template component>
<style>.container { padding: 20px; }</style>
<div class="container">组件内容</div>
<script>
export default {
tag: "my-component",
data: {},
ready() { console.log("ready"); }
};
</script>
</template>
<o-playground name="ofa.js 应用示例" style="--editor-height: 500px">
<code path="demo.html" preview active>
<template>
<o-app src="./app-config.js"></o-app>
</template>
</code>
<code path="app-config.js">
export const home = "./home.html";
</code>
<code path="home.html">
<template page>
<style>
:host {
display: block;
padding: 10px;
}
</style>
<p>{{val}}</p>
<script>
export default async () => {
return {
data: {
val: "Hello ofa.js App Demo",
},
};
};
</script>
</template>
</code>
</o-playground>
OBook 内置 AI 翻译支持，可自动将文档翻译成多种语言。
核心原则：AI 助手只生成写作语言的文档，无需生成其他语言版本。
工作流程：
_config.yaml 中设置 writingLang 和 languagescn/）中编写内容最佳实践：
只需创建写作语言的配置文件：
cn/_config.yaml）cn/documentation/_config.yaml）.md 文件更新相关 _config.yaml，将新文件加入导航。
创建目录：cn/advanced-features/
创建 cn/advanced-features/_config.yaml：
- name: 概述
url: ./overview.md
- name: 特性 A
url: ./feature-a.md
- name: 特性 B
url: ./feature-b.md
为每个主题创建 markdown 文件
更新 cn/_config.yaml：
header:
- name: 教程
url: ./documentation/_config.yaml
- name: API
url: ./api/_config.yaml
- name: 高级特性
url: ./advanced-features/_config.yaml
cn/）中生成内容，其他语言由 OBook 应用翻译_config.yaml 文件具有有效的 YAML 语法