Handbook 编写指南

1. 你在这里:
2. Handbook 编写指南

• 简介
• 入门视频
• 写作空间
• 如何新建一篇 Handbook
• 如何添加 url 跳转链接和嵌入视频
• 如何添加图片
• 可能存在的问题
• 使用链接

更多 Markdown 相关内容，请查看 Markdown 指南

简介

Handbook 编写指南，主要是针对非工程技术团队的成员了解如何撰写 handbook，遵循我们 “Handbook 优先（Handbook-First）” 的工作原则。

入门视频

如果您是第一次接触极狐GitLab，请先观看如下视频，了解极狐GitLab 的基本使用方式。

写作空间

• Repo 地址：https://jihulab.com/gitlab-cn/handbook
• 具体目录：/sites/handbook/source/handbook
• 工作分支：jh-staging
  • 请勿在 jh-master 或其他分支工作
  • jh-staging 分支会每日定时由管理员审核，通过后并入 jh-master 分支
• 预览地址：http://about1s.gitlab.cn/handbook/
• 正式上线地址：https://gitlab.cn/handbook/

如何新建一篇 Handbook

1. (建议)先新建一个议题（issue），指派人选择自己
2. 创建一个合并请求（Merge Request）
   • 注意目标分支设置为 main

3. 打开 Web IDE

   刷新 Web IDE 页面会导致新增信息丢失，推荐使用 Gitpod 或在先在本地 Markdown 编辑器中编辑

4. 新建目录 directory，并在该目录下创建 index.html.md 文件
5. 填写 Markdown 文档内容
6. 选择提交，并填写提交信息，点击提交
7. 选择标记为已就绪，选择合并
   • 在合并前，会有核准要求

更多内容见：本地开发指南

如何添加 url 跳转链接和嵌入视频

• 内部 handbook 页面 url，建议文件都创建在 /sites/handbook/source/handbook 目录下，例如要跳转至 /people-group/index.html.md，则填写 [People Group](/handbook/people-group/)
• 外部网页 url，例如跳转到一个视频链接，则填写 [从GitLab到极狐GitLab，十年发展之路](https://www.bilibili.com/video/BV1844y1r76m)
• 嵌入视频，详情见 Markdown 指南 - 视频

如何添加图片

1. 在目标 handbook 页面的目录下，上传图片

2. 填写图片所在的文件路径，如下图的源码示例

    ![Semantic description of image](/images/path/to/folder/image.png){: .shadow}
   

   

更多内容见 Markdown 指南 - 图片。

可能存在的问题

1. Handbook 里的 Markdown 表格需要和上一行文本有一个空行间隔，否则会识别错误
2. Handbook 目录名称不要使用 _ 特殊字符，否则会识别错误

使用链接

1. Markdown 指南
2. GitLab Inc. Practical Handbook Edits Sample
3. GitLab Flavored Markdown语法文档