mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-22 10:34:30 +08:00

GeWuYou a021941cab docs(guidelines): 添加文档编写规范和配置设置

- 创建 DOCUMENTATION_STANDARDS.md 文件定义 Markdown 语法规范
- 添加泛型标记转义规则和 HTML 标签转义说明
- 提供内部链接验证规则和已存在文档路径列表
- 定义代码块规范和 Frontmatter 规范
- 添加文档结构规范和验证清单
- 配置 .claude/settings.json 启用 oh-my-claudecode 插件

2026-03-07 15:52:08 +08:00

5.3 KiB

Raw Blame History

GFramework 文档编写规范

Markdown 语法规范

1. 泛型标记转义

在 Markdown 文档中,所有泛型标记必须转义,否则会被 VitePress 误认为 HTML 标签。

错误示例:

`Option<T>` 是一个泛型类型
`Result<TValue, TError>` 表示结果
public class Repository<TData> { }

正确示例:

`Option&lt;T&gt;` 是一个泛型类型
`Result&lt;TValue, TError&gt;` 表示结果
public class Repository&lt;TData&gt; { }

常见泛型标记:

<T> → <T>
<TResult> → <TResult>
<TValue> → <TValue>
<TError> → <TError>
<TSaveData> → <TSaveData>
<TData> → <TData>
<TNode> → <TNode>

2. HTML 标签转义

如果需要在文档中显示 HTML 标签,必须转义:

<summary> → <summary>
<param> → <param>
<returns> → <returns>

3. 链接验证

内部链接规则:

使用相对路径: /zh-CN/core/events
确保目标文件存在
不要链接到尚未创建的页面

已存在的文档路径:

Core 模块:

/zh-CN/core/architecture - 架构系统
/zh-CN/core/ioc - IoC 容器
/zh-CN/core/events - 事件系统
/zh-CN/core/command - 命令系统
/zh-CN/core/query - 查询系统
/zh-CN/core/model - Model 系统
/zh-CN/core/system - System 系统
/zh-CN/core/utility - Utility 系统
/zh-CN/core/controller - Controller 系统
/zh-CN/core/logging - 日志系统
/zh-CN/core/pool - 对象池
/zh-CN/core/property - 可绑定属性
/zh-CN/core/lifecycle - 生命周期管理
/zh-CN/core/coroutine - 协程系统
/zh-CN/core/resource - 资源管理
/zh-CN/core/state-machine - 状态机
/zh-CN/core/cqrs - CQRS 与 Mediator
/zh-CN/core/functional - 函数式编程
/zh-CN/core/pause - 暂停管理
/zh-CN/core/configuration - 配置管理
/zh-CN/core/ecs - ECS 系统集成
/zh-CN/core/extensions - 扩展方法
/zh-CN/core/rule - 规则系统
/zh-CN/core/environment - 环境系统
/zh-CN/core/context - 上下文系统
/zh-CN/core/async-initialization - 异步初始化

Game 模块:

/zh-CN/game/scene - 场景系统
/zh-CN/game/ui - UI 系统
/zh-CN/game/data - 数据与存档
/zh-CN/game/storage - 存储系统
/zh-CN/game/serialization - 序列化系统
/zh-CN/game/setting - 设置系统

Godot 模块:

/zh-CN/godot/architecture - Godot 架构集成
/zh-CN/godot/scene - Godot 场景系统
/zh-CN/godot/ui - Godot UI 系统
/zh-CN/godot/pool - Godot 节点池
/zh-CN/godot/resource - Godot 资源仓储
/zh-CN/godot/logging - Godot 日志系统
/zh-CN/godot/pause - Godot 暂停处理
/zh-CN/godot/extensions - Godot 扩展
/zh-CN/godot/coroutine - Godot 协程
/zh-CN/godot/signal - Godot 信号
/zh-CN/godot/storage - Godot 存储

教程:

/zh-CN/tutorials/coroutine-tutorial - 协程系统教程
/zh-CN/tutorials/state-machine-tutorial - 状态机教程
/zh-CN/tutorials/resource-management - 资源管理教程
/zh-CN/tutorials/save-system - 存档系统教程
/zh-CN/tutorials/godot-complete-project - Godot 完整项目
/zh-CN/tutorials/functional-programming - 函数式编程实践
/zh-CN/tutorials/pause-system - 暂停系统实现
/zh-CN/tutorials/data-migration - 数据迁移实践
/zh-CN/tutorials/godot-integration - Godot 集成
/zh-CN/tutorials/advanced-patterns - 高级模式

其他:

/zh-CN/getting-started/quick-start - 快速开始
/zh-CN/getting-started/installation - 安装指南
/zh-CN/best-practices/architecture-patterns - 架构模式

不存在的路径 (不要链接):

/zh-CN/best-practices/performance - 尚未创建
/zh-CN/core/serializer - 错误路径,应使用 /zh-CN/game/serialization

代码块规范

1. 代码块语言标识

始终指定代码块的语言:

\`\`\`csharp
public class Example { }
\`\`\`

\`\`\`bash
npm install
\`\`\`

2. 代码注释

代码示例应包含中文注释:

// 创建玩家实体
var player = new Player
{
    Name = "玩家1",  // 玩家名称
    Level = 1        // 初始等级
};

Frontmatter 规范

每个文档必须包含正确的 frontmatter:

---
title: 文档标题
description: 简短描述（1-2 句话）
---

文档结构规范

指南文档结构

概述
核心概念
基本用法
高级用法
最佳实践
常见问题
相关文档

教程文档结构

学习目标
前置条件
步骤 1-N (3-7 步)
完整代码
运行结果
下一步
相关文档

验证清单

生成文档后,必须检查:

所有泛型标记已转义 (<T> → <T>)
所有内部链接指向存在的页面
Frontmatter 格式正确
代码块指定了语言
代码包含中文注释
文档结构完整
没有 HTML 标签错误

自动修复脚本

如果文档已生成,可以使用以下脚本修复常见问题:

# 修复泛型标记
sed -i 's/<T>/\&lt;T\&gt;/g' file.md
sed -i 's/<TResult>/\&lt;TResult\&gt;/g' file.md
sed -i 's/<TValue>/\&lt;TValue\&gt;/g' file.md
sed -i 's/<TError>/\&lt;TError\&gt;/g' file.md

# 验证构建
cd docs && bun run build

5.3 KiB Raw Blame History Unescape Escape