Obook Doc Generator

OBook 文档生成器

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

章节 _config.yaml

定义章节内的页面导航：

- name: 介绍
  url: ./introduction.md
- name: 开始使用
  content:
    - name: 脚本引用
      url: ./script-reference.md
    - name: 创建第一个应用
      url: ./create-first-app.md
- name: 快速上手
  url: ./quick-start.md

Markdown 文档编写

基本格式

# 标题

简短的介绍段落。

## 第一节

内容。

### 子节 1.1

详细内容。

## 相关链接

- [链接文本](./related-file.md)

最佳实践

1. 使用正确的标题层级（h1 → h2 → h3）
2. 保持标题简短且具描述性
3. 代码示例使用带语言标注的代码块
4. 内部链接使用相对路径
5. 图片放在同目录或子目录中

o-playground 交互式演示

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> 属性：

<code> 属性：

样式变量：

<template> 类型识别与处理

普通模板示例：

<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>

完整示例：ofa.js 应用

<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 助手只生成写作语言的文档，无需生成其他语言版本。

工作流程：

1. 在根 _config.yaml 中设置 writingLang 和 languages
2. AI 助手只在写作语言目录（如 cn/）中编写内容
3. 用户通过 OBook 应用自动翻译新增或修改的内容
4. OBook 应用翻译更省 token（只翻译增量内容、使用优化策略）

最佳实践：

• 只创建写作语言的配置文件和文档，OBook 自动处理其他语言
• 编写易于翻译的内容：避免特定文化引用，使用清晰明确的语言

工作流程：创建新文档

步骤 1：规划结构

• 需要哪些章节？
• 每个章节涵盖哪些主题？
• 逻辑顺序是什么？

步骤 2：创建配置文件

只需创建写作语言的配置文件：

1. 根配置（如不存在）
2. 语言根配置（如 cn/_config.yaml）
3. 章节配置（如 cn/documentation/_config.yaml）

步骤 3：编写 Markdown 文件

1. 创建 .md 文件
2. 编写清晰简洁的内容
3. 包含代码示例
4. 添加相关文档链接

步骤 4：更新导航

更新相关 _config.yaml，将新文件加入导航。

示例：创建"高级特性"章节

1. 创建目录：cn/advanced-features/

2. 创建 cn/advanced-features/_config.yaml：

   - name: 概述
     url: ./overview.md
   - name: 特性 A
     url: ./feature-a.md
   - name: 特性 B
     url: ./feature-b.md
   

3. 为每个主题创建 markdown 文件

4. 更新 cn/_config.yaml：

   header:
     - name: 教程
       url: ./documentation/_config.yaml
     - name: API
       url: ./api/_config.yaml
     - name: 高级特性
       url: ./advanced-features/_config.yaml
   

AI 助手指南

1. 理解上下文：生成文档前了解项目内容、目标受众和文档目标
2. 遵循现有模式：查看已有文档，匹配写作风格、格式和命名约定
3. 保持简单：使用清晰语言，避免不必要术语，解释技术术语
4. 提供示例：为技术主题包含代码示例，适当使用交互式演示
5. 链接相关内容：添加相关文档链接，在页面间建立逻辑流程
6. 只生成写作语言：仅在写作语言目录（如 cn/）中生成内容，其他语言由 OBook 应用翻译

验证清单

• 所有 _config.yaml 文件具有有效的 YAML 语法
• 配置文件中的所有 URL 指向现有文件
• Markdown 文件具有正确的标题层级
• 代码示例正确且可运行
• 内部链接使用相对路径
• 图片和资源正确放置
• 内容清晰且组织良好
• 多语言支持配置正确

资源

• OBook GitHub 仓库
• ofa.js 文档
• 示例文档站