文档编写使用手册

欢迎来到 Laby Blog 文档系统！本手册将指导你快速创建专业、规范的技术文档。

核心价值

两种编写方式：AI 辅助编写 + 手动编写，灵活选择
完整模板库：标准模板、日报模板、周报模板，开箱即用
规范体系：统一的编写规范，确保文档质量
炫酷风格：DevManga 主题，粗边框、阴影、漫画风格

一、快速开始

1.1 选择编写方式

AI 辅助编写

适合场景：

快速生成文档框架
需要大量技术细节
多文档批量创建

优势：

几分钟完成文档
自动遵循规范
内容丰富完整

手动编写

适合场景：

完全掌控内容
个性化定制
精细化调整

优势：

灵活自由
精准表达
深度优化

1.2 三步创建文档

二、AI 辅助编写

2.1 准备提示词

复制以下提示词模板，替换 [你的主题] 为具体内容：

text

1我需要编写一篇关于 [你的主题] 的技术文档。
2
3请严格遵循以下规范：
41. 文档编写规范：.kiro/steering/document-writing-standards.md
52. 参考模板：docs/document-template/template.md
6
7要求：
8- 禁止使用 Emoji 图标
9- 使用中文数字编号（一、二、三）作为主章节
10- 使用阿拉伯数字编号（1.1、1.2）作为子章节
11- 包含完整的 Front Matter
12- 使用提示框突出重点
13- 代码块必须指定语言类型

2.2 AI 生成流程

生成步骤

提供提示词 → 告诉 AI 你的需求和规范
AI 生成内容 → 获得完整的文档框架和内容
人工审查 → 检查准确性、代码示例、链接
保存发布 → 放入 docs 目录相应位置

2.3 最佳实践

技巧	说明	效果
提供上下文	说明目标读者、技术栈版本	内容更精准
分段生成	先大纲，再逐章节生成	结构更清晰
迭代优化	要求 AI 补充和优化	质量更高

三、手动编写

3.1 创建文档结构

文件组织规则

1docs/
2├── frontend/              # 文件夹 = 菜单分类
3│   ├── react-guide.md    # 文件 = 文档页面
4│   └── vue-guide.md
5├── backend/
6│   ├── spring-boot.md
7│   └── database.md
8└── document-template/
9    └── template.md       # 标准模板

命名规范

文件夹和文件名：小写字母 + 连字符（kebab-case）
避免：中文、空格、特殊字符
示例：react-hooks-guide.md ✓ React Hooks 指南.md ✗

配置目录（可选）

在文件夹中创建 _category_.json：

docs/frontend/_category_.json

json

1{
2  "label": "前端开发",
3  "position": 1,
4  "link": {
5    "type": "generated-index",
6    "description": "前端开发技术文档"
7  }
8}

3.2 使用标准模板

模板位置

文档标准模板包含 18 个章节的完整示例

3.3 编写步骤

步骤 1：复制模板

从 template.md 复制内容作为起点。

步骤 2：填写 Front Matter

yaml

1---
2sidebar_position: 1          # 侧边栏位置
3title: React 开发指南        # 页面标题
4description: React 框架完整开发指南，包含组件、Hooks、状态管理等核心概念
5tags: [React, 前端, JavaScript]
6keywords: [React, 组件, Hooks, 状态管理, 前端开发]
7authors: [Laby]
8last_update:
9  date: 2026-04-24
10  author: Laby
11---

步骤 3：编写内容

参考 template.md 中的所有组件和格式示例。

步骤 4：本地预览

bash

1npm start
2# 访问 http://localhost:3000

3.4 核心规范

禁止事项

禁止使用 Emoji 图标
禁止中文文件名
禁止省略代码块语言类型
禁止空格和特殊字符命名

四、组件速查

4.1 常用组件

组件	用途	查看示例
Front Matter	文档元数据配置	第一章
标题层级	文档结构组织	第二章
文本格式	基本文本样式	第三章
提示框	突出重点信息	第四章
代码块	展示代码	第五章
表格	结构化数据	第六章
图片媒体	插入图片视频	第七章
链接引用	文档链接	第八章
分隔线	章节分隔	第九章
Emoji	图标使用	第十章
嵌套内容	复杂结构	第十一章
实际应用	真实案例	第十二章
最佳实践	编写建议	第十三章
Tabs	多选项展示	第十四章
高级嵌套	复杂嵌套	第十五章
快速模板	复制使用	第十六章
折叠面板	隐藏详情	第十七章
卡片	内容分组	第十八章

4.2 提示框类型

markdown

1:::tip[技巧]
2有用的建议和最佳实践
3:::

markdown

1:::warning[警告]
2需要注意的事项和潜在问题
3:::

markdown

1:::danger[危险]
2严重问题和禁止操作
3:::

五、发布前检查

5.1 内容检查

Front Matter 完整且正确
标题层级合理，编号正确
没有使用 Emoji 图标
技术内容准确无误
代码示例完整可运行
链接有效且文字有意义

5.2 格式检查

5.3 规范检查

样式符合 template.md 规范
文件命名规范（小写字母和连字符）
标注了最后更新时间
遵循 DevManga 主题风格

六、FAQ（常见问题）

文档不显示在侧边栏？

可能原因：

文件不在 docs 目录下
文件名或路径不正确
Front Matter 格式错误

解决方法：

确认文件在 docs 目录下
检查文件名是否使用小写字母和连字符
检查 Front Matter 格式是否正确

代码块显示异常？

可能原因：

没有指定语言类型
代码块标记不完整

解决方法：

查看代码块示例，确保指定了语言类型。

提示框不生效？

可能原因：

语法格式不正确
缺少空行

解决方法：

查看提示框示例，确保语法正确。

图片无法显示？

可能原因：

图片路径不正确
图片文件不存在

解决方法：

使用绝对路径：/img/example.jpg
确认图片在 static/img 目录下
检查文件名大小写

七、参考资源

7.1 必读文档

标准模板

文档标准模板

包含 18 个章节的完整示例，涵盖所有组件和格式。

编写规范

查看项目根目录 .kiro/steering/document-writing-standards.md

详细的编写规范、检查清单、最佳实践。

报告模板

7.2 快速链接

内部链接

首页 | 博客 | 项目 | 关于我 | 联系我

外部资源

八、获取帮助

如果遇到问题，按以下顺序寻求帮助：

查看文档标准模板寻找示例
查看项目根目录 .kiro/steering/document-writing-standards.md 文档编写规范
查看本手册的常见问题部分
使用搜索功能查找相关文档
访问联系我页面反馈问题

最后更新时间：2026-04-24

祝你编写出专业、规范、炫酷的技术文档！

forum

评论区 / Comments

share分享文章 / Share

一、快速开始​

1.1 选择编写方式​

AI 辅助编写​

手动编写​

1.2 三步创建文档​

二、AI 辅助编写​

2.1 准备提示词​

2.2 AI 生成流程​

2.3 最佳实践​

三、手动编写​

3.1 创建文档结构​

文件组织规则​

配置目录（可选）​

3.2 使用标准模板​

3.3 编写步骤​

3.4 核心规范​

禁止事项​

推荐做法​

四、组件速查​

4.1 常用组件​

4.2 提示框类型​

五、发布前检查​

5.1 内容检查​

5.2 格式检查​

5.3 规范检查​

六、FAQ（常见问题）​

七、参考资源​

7.1 必读文档​

标准模板​

编写规范​

报告模板​

7.2 快速链接​

八、获取帮助​

评论区 / Comments

一、快速开始

1.1 选择编写方式

AI 辅助编写

手动编写

1.2 三步创建文档

二、AI 辅助编写

2.1 准备提示词

2.2 AI 生成流程

2.3 最佳实践

三、手动编写

3.1 创建文档结构

文件组织规则

配置目录（可选）

3.2 使用标准模板

3.3 编写步骤

3.4 核心规范

禁止事项

推荐做法

四、组件速查

4.1 常用组件

4.2 提示框类型

五、发布前检查

5.1 内容检查

5.2 格式检查

5.3 规范检查

六、FAQ（常见问题）

七、参考资源

7.1 必读文档

标准模板

编写规范

报告模板

7.2 快速链接

八、获取帮助